Как правильно использовать аннотации типов для аргументов и возвращаемого значения?

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

Базовый синтаксис

Для аргумента тип указывается после двоеточия, для возвращаемого значения — после стрелки -> перед двоеточием функции.

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

# Использование с подсказкой типа для строки
message: str = "Hello"
print(add(5, 3))  # 8

Использование модуля typing

Для более сложных структур, таких как списки, словари, опциональные значения или пользовательские классы, используется модуль typing.

from typing import List, Optional, Dict

def process_items(items: List[int], config: Optional[Dict[str, str]] = None) -> bool:
    """Обрабатывает список целых чисел и опциональный словарь конфигурации."""
    if not items:
        return False
    # ... логика обработки
    return True

# Вызов функции
result = process_items([1, 2, 3], {"mode": "fast"})

Практическое применение и инструменты

Аннотации типов особенно полезны в крупных проектах и при командной разработке. Они позволяют:

• Инструментам статического анализа (mypy, pyright, Pylance) проверять соответствие типов и находить потенциальные ошибки до запуска кода.
• IDE (VS Code, PyCharm) предоставлять более точные автодополнения и подсказки.
• Создавать самодокументируемый код, где контракт функции (что принимает и что возвращает) ясен из её сигнатуры.

Важно помнить, что Python остаётся динамически типизированным языком — аннотации не влияют на выполнение в runtime (если не использовать дополнительные библиотеки типа pydantic для валидации).

Пример с пользовательским типом

from typing import Union

class User:
    def __init__(self, name: str):
        self.name = name

def get_identifier(entity: Union[User, int]) -> str:
    """Принимает либо объект User, либо целое число."""
    if isinstance(entity, User):
        return entity.name
    else:
        return f"ID-{entity}"

# Использование
user = User("Alice")
print(get_identifier(user))   # Alice
print(get_identifier(42))     # ID-42

В Python 3.10+ вместо Union[User, int] можно использовать более краткий синтаксис с вертикальной чертой: User | int.

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