Свои исключения и проектирование API без sentinel-значений

В C функция сигнализирует об ошибке через возвращаемое значение — NULL, -1, специальный код, — а полезный результат приходится передавать через выходной параметр (int parse(const char *s, int *out)). Это заставляет вызывающего каждый раз помнить: проверить возврат, только потом читать *out. Ошибка и результат живут в одном канале и постоянно рискуют перепутаться — классический баг «забыли проверить -1, прочитали мусор из *out».

Python-функция может просто возвращать полезное значение и никогда не возвращать «код ошибки» — потому что для ошибки есть отдельный канал: raise. Питонические API сигнализируют о неудаче исключением, а не sentinel-значением. Это меняет сам контракт функции: аннотация def parse(s: str) -> int означает, что либо вы получаете int, либо получаете исключение — третьего не бывает, и не нужно проверять, «а не является ли этот int замаскированным -1».

Собственные исключения — это то, чем в C были бы именованные коды ошибок (enum ParseError { ERR_EMPTY, ERR_OVERFLOW, ... }), но с двумя преимуществами: они несут произвольные данные (не только код, а хоть весь контекст сбоя) и распространяются по стеку вызовов автоматически, без ручной проверки на каждом промежуточном уровне.

class ConfigError(Exception):
    """Базовая ошибка конфигурации."""

class MissingKeyError(ConfigError):
    def __init__(self, key):
        super().__init__(f"missing required key: {key}")
        self.key = key

def get_required(config, key):
    if key not in config:
        raise MissingKeyError(key)
    return config[key]

Вызывающему на трёх уровнях выше не нужно ничего проверять — если MissingKeyError не перехвачена явно, она сама долетит до верхнего уровня со всем traceback'ом. В C та же задача требует, чтобы каждая промежуточная функция проверяла код возврата и явно перепробрасывала его вверх — то есть повторяла логику обработки на каждом уровне, даже если сама эта функция ничего не может с ошибкой сделать.

Важный нюанс: собственные исключения стоит наследовать от Exception (или от более специфичного встроенного класса, если ошибка реально того же рода — например, ValueError для некорректного значения), а не от BaseException напрямую, и группировать их в иерархию с общим базовым классом модуля/библиотеки (как выше ConfigError). Это позволяет вызывающему коду перехватывать либо конкретный случай, либо весь класс ошибок одной строкой except ConfigError.

def read_record(buf):
    if len(buf) < 4:
        return None  # sentinel: "не хватает данных"
    length = int.from_bytes(buf[:4], "big")
    if length > len(buf) - 4:
        return -1  # sentinel: "повреждённый заголовок"
    return buf[4:4+length]

class ProtocolError(Exception):
    pass

class IncompleteData(ProtocolError):
    pass

class CorruptedHeader(ProtocolError):
    def __init__(self, declared, available):
        super().__init__(f"declared length {declared} exceeds available {available}")

def read_record(buf: bytes) -> bytes:
    if len(buf) < 4:
        raise IncompleteData()
    length = int.from_bytes(buf[:4], "big")
    if length > len(buf) - 4:
        raise CorruptedHeader(length, len(buf) - 4)
    return buf[4:4+length]

def find_user(db, user_id):
    row = db.query(user_id)
    if row is None:
        return None  # sentinel: пользователь не найден
    if row.get("deleted"):
        return -1  # sentinel: пользователь удалён
    return row

flowchart LR
    subgraph C["C-стиль: sentinel"]
        C1[find_user] -->|return None / -1 / row| C2[Вызывающий проверяет значение]
        C2 --> C3[Каждый уровень выше повторяет проверку]
    end
    subgraph PY["Python: исключение"]
        P1[find_user] -->|return row или raise| P2[except UserLookupError на нужном уровне]
        P2 --> P3[Промежуточные уровни ничего не проверяют]
    end