Ответ.

Аннотации типов (type hints) — это способ явно указывать ожидаемые типы переменных, аргументов и возвращаемых значений функций. Синтаксис появился в Python 3.5 (PEP 484). Аннотации статичны — интерпретатор их игнорирует во время выполнения, они предназначены для инструментов анализа кода (mypy, Pyright, IDE).

Аннотации помогают:

• Улучшить читаемость и само-документацию кода.
• Позволяют инструментам анализировать и отлавливать типовые ошибки до запуска.
• Используются в автодополнении, рефакторинге и документации.

Пример:

def add(x: int, y: int) -> int:
    return x + y

def show(items: list[str]) -> None:
    print(', '.join(items))

Вопрос с подвохом.

Частый вопрос:

Могут ли аннотации типов каким-либо образом повлиять на быстродействие или корректность выполнения кода?

Ответ: Нет, аннотации типов не влияют ни на быстродействие, ни на функцию программы в runtime. Это лишь метаданные. Но они могут использоваться сторонними инструментами или фреймворками для контроля и валидации типов (например, в FastAPI).

Примеры реальных ошибок из-за незнания тонкостей темы.

---

История

В проекте большие динамические структуры помечали типами через list, dict без уточнения элементов (например: def f(x: list): ...). В результате статические анализаторы не могли выявлять ошибки типа, потому что из аннотации не ясно, что лежит внутри.

---

История

Использовали from __future__ import annotations для поддержки postponed evaluation в Python 3.7, но забыли про это в одной части проекта. Это привело к тому, что forward references вызывали ошибки при статическом анализе и в рантайме при использовании некоторых фреймворков.

---

История

В большом проекте некорректно задали тип возвращаемого значения: забыли импортировать Optional, получили ошибку от mypy и ряд недокументированных проблем в IDE, которые мешали автокомплиту и подсветке ошибок.