Аннотации типов

Категория

Функции и типы

Уровень

Средний

Версия

Python 3.10+ для записи int | str

Зачем это знать

Делать назначение функции понятным без чтения её тела

§1Зачем нужны аннотации

По заголовку функции без аннотаций не видно, с чем она работает. Строка def add(a, b) одинаково подходит и для чисел, и для строк, и для списков.

def add(a, b)              что можно передать? неизвестно
def add(a: int, b: int)    ожидаются целые числа

Аннотация типа — это пометка о том, какой тип значения ожидается. Она решает три задачи: документирует код, позволяет редактору подсказывать методы и даёт статическим анализаторам вроде mypy находить несоответствия до запуска программы.

§2Синтаксис

Тип параметра пишут после имени через двоеточие, а тип результата — после стрелки -> перед двоеточием заголовка.

def add(a: int, b: int) -> int:
           │       │       └ тип возвращаемого значения
           └───────┴ типы параметров

def add(a: int, b: int) -> int:
    return a + b

print(add(2, 3))

5

Использовать можно любые встроенные типы: int, float, str, bool, list, dict и другие. Имя типа пишется без кавычек и без скобок.

§3Аннотация не проверяет тип

Это главное, что нужно понять про аннотации: Python их не исполняет. Функция с аннотацией int спокойно примет строки.

def add(a: int, b: int) -> int:
    return a + b

print(add("Py", "thon"))

Python

Обратная сторона тоже верна: несоответствие типов может привести к настоящей ошибке позже — там, где значение не поддержит нужную операцию. Аннотации помогают заметить это заранее.

§4Возвращаемое значение и None

Если функция ничего не возвращает, её результат — None, и это записывают явно.

def greet(name: str) -> None:
    print("Привет,", name)

greet("Аня")

Привет, Аня

Запись -> None означает «возвращать нечего». Она отличает такую функцию от той, где программист просто забыл указать тип результата.

§5Коллекции в аннотациях

Для коллекции полезно указать не только сам тип, но и тип элементов. Это делают квадратными скобками.

def average(values: list[int]) -> float:
    return sum(values) / len(values)

print(average([1, 2, 3]))

2.0

§6Несколько типов через |

Когда допустимо несколько типов, их перечисляют через вертикальную черту.

def process(value: int | str) -> None:
    if isinstance(value, int):
        print(value * 2)
    else:
        print(value.upper())

process(5)
process("код")

10
КОД

Здесь аннотация и настоящая проверка работают вместе: int | str сообщает читателю о замысле, а isinstance() действительно разделяет случаи во время выполнения.

§7Значение может отсутствовать

Частный, но очень частый случай — функция возвращает результат либо None, если ничего не нашла.

def find_city(name: str) -> str | None:
    cities = {"Аня": "Москва"}
    return cities.get(name)

print(find_city("Аня"))
print(find_city("Борис"))

Москва
None

Такая аннотация — предупреждение вызывающему коду: результат нужно проверить перед использованием. В старых версиях то же самое записывали как Optional[str] из модуля typing.

§8Аннотации переменных

Аннотировать можно не только функции. Переменной тип указывают так же — через двоеточие после имени.

x: int = 10
y: float = 5.5
z: str = "Hello"

print(x, y, z)

10 5.5 Hello

То же работает внутри функции для локальных переменных: count: int = 0. Значение можно и не присваивать — запись total: int объявляет только тип, но саму переменную не создаёт, и обращение к ней вызовет NameError.

§9Атрибут __annotations__

Аннотации не исчезают при запуске: Python складывает их в словарь __annotations__, где ключи — имена, а значения — типы.

def add(a: int, b: int) -> int:
    return a + b

print(add.__annotations__)

{'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}

Тип возвращаемого значения лежит под специальным ключом 'return'. У классов есть свой такой словарь — по аннотациям атрибутов.

class Point:
    x: int
    y: int

print(Point.__annotations__)

{'x': <class 'int'>, 'y': <class 'int'>}

В повседневном коде этот словарь почти не нужен. Он важен библиотекам, которые строят поведение по аннотациям, — так работают, например, валидация данных в Pydantic и внедрение зависимостей в FastAPI.

§10Где аннотации не нужны

Аннотации — инструмент, а не обязанность. Они окупаются там, где код читают другие или где типы неочевидны.

Аннотация, которая не соответствует действительности, хуже её отсутствия: она вводит в заблуждение. Если тип изменился — исправьте аннотацию.

§11Частые ошибки

§12Проверьте себя

§13Шпаргалка

Итог главы

Аннотации описывают ожидаемые типы параметров, результата и переменных. Они не влияют на выполнение: программа с «неправильным» типом отработает как обычно. Ценность аннотаций в другом — они документируют замысел, помогают редактору и позволяют статическому анализатору находить несоответствия до запуска.