Ответ

История вопроса

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

Проблема

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

Решение

Аннотации типа используются для документации, автоматической проверки с помощью mypy, pylance, pyright и аналогичных инструментов, а также для интеграции с IDE. Реализуются через двоеточия после имени аргумента и стрелку после списка параметров:**

def greet(name: str, times: int = 1) -> None:
    for _ in range(times):
        print(f"Hello, {name}!")

# Корректная аннотация для функции обработки словаря
from typing import Dict, List

def transform(data: Dict[str, List[int]]) -> float:
    return sum(sum(lst) for lst in data.values()) / 10

Ключевые особенности:

Аннотации не проверяются интерпретатором, они остаются при выполнении кода, но никаким образом не изменяют выполнение
Актуальны для крупных проектов, где важно понимать интерфейсы и взаимодействие компонентов
Для комплексных конструкций нужны typing.List, typing.Dict, typing.Optional, typing.Union и пр.

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

Может ли Python "автоматически" проверять соответствие типам, объявленным в аннотациях?

Нет! Проверка типов происходит только внешними инструментами статического анализа, например, mypy. В рантайме Python полностью игнорирует содержимое аннотаций.

def f(x: int):
    return x * 2

print(f('oops'))  # Тип str, ошибки не будет!

Где хранятся аннотации и как их получить в рантайме, зачем это может быть нужно?

Хранятся в специальном атрибуте annotations:

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

print(add.__annotations__)  # {'x': <class 'int'>, 'y': <class 'int'>, 'return': <class 'int'>}

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

Можно ли аннотировать любую переменную, только функции, что будет в глобальной области?

Аннотировать можно как локальные, так и глобальные переменные через двоеточие, это также не влияет на выполнение:

index: int = 0

def func(x: 'User') -> None:
    ...

Типовые ошибки и анти-паттерны

Считать, что type hints — часть строгой типизации и строгого контроля типов
Забывать, что значения по умолчанию обязаны быть совместимы с заявленным типом (хотя это не проверяется на этапе выполнения)
Неправильное использование сложных типов из typing (например, List<int> вместо List[int])

Пример из жизни

Негативный кейс

В корпоративном проекте все разработчики стали активно внедрять аннотации, а реальные типы аргументов функций часто не совпадали с указанными. Python пропускал эти ошибки, и неожиданные баги появлялись только в глубине бизнес-логики. Отсутствовала настройка mypy.

Плюсы:

Улучшение автодополнения и документации

Минусы:

Остались неявные ошибки, уводящие причину далеко от места аннотирования

Позитивный кейс

Использование type hints и обязательный запуск mypy в CI, а также автогенерация документации по annotations:

Плюсы:

Минимум ошибок по несогласованности типов
Повышение качества совместной работы над API

Минусы:

Появляется накладная работа по поддержанию актуальности аннотаций при рефакторинге