Type hints и mypy в Python: практическая типизация

Optional и сужение типа

Тип str | None означает два реальных состояния. До вызова методов строки нужно сузить тип проверкой.

def normalize(name: str | None) -> str:
    if name is None:
        return "anonymous"
    return name.strip().lower()

Не используйте Optional как синоним необязательного аргумента: он говорит именно о допустимом None. Аргумент может быть необязательным из-за значения по умолчанию, но при этом никогда не принимать None.

Для конечного набора строк полезен Literal, для структурных интерфейсов — Protocol, для обобщённых контейнеров — type parameters. Начинайте с сигнатур на границах модулей, не пытаясь за один день аннотировать весь legacy-код.