Как писать аннотацию к функции?

Аннотации к функциям в Python: полное руководство

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

Основные типы аннотаций

1. Аннотации параметров функции

Аннотации параметров указываются после двоеточия : после имени параметра:

def greet(name: str, age: int) -> str:
    return f"Привет, {name}! Тебе {age} лет."

2. Аннотация возвращаемого значения

Указывается после -> перед двоеточием, завершающим сигнатуру функции:

def calculate_total(price: float, quantity: int) -> float:
    return price * quantity

Расширенные возможности аннотаций

Использование сложных типов

from typing import List, Dict, Optional, Union

def process_data(
    items: List[str],
    config: Dict[str, int],
    timeout: Optional[int] = None
) -> Union[str, None]:
    """Обрабатывает данные и возвращает результат или None."""
    if timeout and timeout < 0:
        return None
    return f"Обработано {len(items)} элементов"

Пользовательские типы и Aliases

from typing import TypeVar, Sequence

T = TypeVar('T')  # Обобщенный тип

def first_item(items: Sequence[T]) -> T:
    """Возвращает первый элемент последовательности."""
    return items[0]

Лучшие практики написания аннотаций

1. Будьте конкретными

# Плохо
def get_user(data: dict) -> any:
    ...

# Хорошо
from typing import TypedDict

class User(TypedDict):
    id: int
    name: str
    email: str

def get_user(user_id: int) -> User:
    ...

2. Используйте Optional для nullable-значений

from typing import Optional

def find_user(username: str) -> Optional[dict]:
    """Возвращает пользователя или None, если не найден."""
    # реализация

3. Комбинируйте с docstring

Аннотации дополняют, но не заменяют документацию:

def calculate_discount(
    price: float,
    discount_percent: float,
    minimum_purchase: float = 100.0
) -> float:
    """
    Рассчитывает конечную цену с учетом скидки.
    
    Args:
        price: Исходная цена товара
        discount_percent: Процент скидки (0-100)
        minimum_purchase: Минимальная сумма покупки для скидки
    
    Returns:
        Конечная цена после применения скидки
    """
    if price >= minimum_purchase:
        return price * (1 - discount_percent / 100)
    return price

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

Пример для QA Automation

from typing import List, Tuple
from selenium.webdriver.remote.webelement import WebElement

def find_interactive_elements(
    driver: WebDriver,
    timeout: int = 10
) -> List[WebElement]:
    """
    Находит все интерактивные элементы на странице.
    
    Args:
        driver: Экземпляр Selenium WebDriver
        timeout: Максимальное время ожидания в секундах
    
    Returns:
        Список веб-элементов (кнопки, ссылки, поля ввода)
    
    Raises:
        TimeoutException: Если элементы не найдены за указанное время
    """
    locator = (By.XPATH, "//button | //a | //input")
    wait = WebDriverWait(driver, timeout)
    return wait.until(
        EC.presence_of_all_elements_located(locator)
    )

Инструменты для работы с аннотациями

• Mypy — статический анализатор типов
• Pydantic — валидация данных на основе аннотаций
• FastAPI — использует аннотации для автоматической документации API

Преимущества использования аннотаций

• Улучшенная читаемость кода
• Автодополнение в современных IDE
• Статическая проверка типов с помощью mypy
• Автодокументирование API (например, в FastAPI)
• Раннее обнаружение ошибок

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