Для чего нужен missing?

missing из dataclasses: назначение и применение

missing — это специальный объект-маркер из модуля dataclasses, который используется для обозначения полей без значения по умолчанию. Это один из инструментов, которые часто игнорируют, но который решает специфические, но важные проблемы в работе с dataclass'ами.

Что такое missing?

missing — это уникальный объект, который является "дозорным" (sentinel value). Он означает: "это поле должно быть передано явно при создании экземпляра, значения по умолчанию нет".

from dataclasses import dataclass, field, missing, fields, MISSING

@dataclass
class User:
    name: str  # Поле без значения по умолчанию
    email: str
    age: int = 18  # Поле со значением по умолчанию

# Проверим метаинформацию
for f in fields(User):
    print(f"Поле {f.name}: default={f.default}, default_factory={f.default_factory}")

Основное применение: различие между "нет значения" и "значение None"

Это ключевой момент! missing нужен для решения проблемы: как отличить "параметр не передан" от "параметр передан со значением None"?

from dataclasses import dataclass, field, MISSING
from typing import Optional

@dataclass
class DatabaseConfig:
    host: str
    port: int
    password: Optional[str] = field(default=MISSING)
    
    def __post_init__(self):
        if self.password is MISSING:
            import os
            self.password = os.getenv("DB_PASSWORD")
        elif self.password is None:
            # Пароль явно None, это означает "без аутентификации"
            pass

Практический пример: валидация конфигураций

from dataclasses import dataclass, field, MISSING
from typing import Optional
import os

@dataclass
class AppConfig:
    app_name: str
    debug: bool = False
    api_key: str = field(default=MISSING)
    database_url: Optional[str] = field(default=MISSING)
    
    def __post_init__(self):
        if self.api_key is MISSING:
            self.api_key = os.getenv("API_KEY")
            if not self.api_key:
                raise ValueError("API_KEY не передан")

Проверка наличия значения по умолчанию

MISSING используется при анализе структуры dataclass:

from dataclasses import dataclass, fields, MISSING

@dataclass
class Product:
    name: str
    price: float
    category: str = "General"
    discount: int = 0

for f in fields(Product):
    has_default = f.default is not MISSING or f.default_factory is not MISSING
    status = "опционально" if has_default else "обязательно"
    print(f"{f.name}: {status}")

Сравнение с другими подходами

Без MISSING (проблема): невозможно различить

@dataclass
class User:
    name: str
    email: Optional[str] = None

user = User(name="Alice")
# email=None потому что не передан или это None?

С MISSING (ясно)

from dataclasses import dataclass, field, MISSING

@dataclass
class User:
    name: str
    email: Optional[str] = field(default=MISSING)
    
    def __post_init__(self):
        if self.email is MISSING:
            self.email = self._generate_email()

Работа с MISSING в генерике

from dataclasses import dataclass, field, MISSING, fields
from typing import Any

@dataclass
class Document:
    title: str
    content: str = field(default=MISSING)
    tags: list = field(default_factory=list)

def to_dict_clean(obj: Any) -> dict:
    result = {}
    for f in fields(obj):
        value = getattr(obj, f.name)
        if value is not MISSING:
            result[f.name] = value
    return result

doc = Document(title="Hello")
print(to_dict_clean(doc))  # {title: Hello, tags: []}

Когда использовать MISSING

Хорошие применения:

• Различие между "не передано" и "передано None"
• Обязательные поля из конфигураций
• Ленивая инициализация в __post_init__
• Валидация: требует ли поле значение или нет

Когда избегать:

• Если None достаточно (не усложняйте)
• Если используете Optional[T] = None (это яснее)
• В публичном API с простыми требованиями

Заключение

missing (MISSING) — это тонкий, но мощный инструмент для:

• Явного обозначения отсутствия значения
• Различения между "не передано" и "передано None"
• Валидации структур данных
• Функционального программирования где каждое состояние значимо

Это не повседневный инструмент, но когда он нужен — других решений нет. Используйте его в конфигурациях, валидаторах и когда нужно различить несколько состояний значения.