Что такое type annotation?

Type annotation (аннотация типов) в Python — это способ явно указать, какого типа данные ожидаются в переменных, аргументах функций и их возвращаемых значениях.

📌 Они не влияют на выполнение кода (Python всё равно остаётся динамически типизированным языком) — это в первую очередь подсказка для разработчиков, IDE и инструментов статического анализа (mypy, pyright).

---

1. Синтаксис

Аннотации добавляются после имени переменной или параметра через двоеточие :, а для возвращаемого значения — через стрелку ->.

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

---

2. Аннотация переменных

username: str = "Alice"
age: int = 30
scores: list[int] = [10, 20, 30]

---

3. Сложные типы (модуль typing)

В Python до 3.9 для сложных структур используют typing:

from typing import List, Dict, Tuple, Optional

names: List[str] = ["Alice", "Bob"]
user: Dict[str, int] = {"age": 25}
coords: Tuple[int, int] = (10, 20)
maybe_value: Optional[int] = None  # int или None

С Python 3.9+ можно писать короче:

names: list[str] = ["Alice", "Bob"]

---

4. Аннотация Any, Union, Literal

from typing import Any, Union, Literal

data: Any = "любой тип"
value: Union[int, str] = 42  # int или str
direction: Literal["up", "down"] = "up"

---

5. Пример с классами

class User:
    def __init__(self, name: str, active: bool) -> None:
        self.name = name
        self.active = active

    def deactivate(self) -> None:
        self.active = False

---

6. Пример в автотестах

from typing import List

def get_failed_tests(test_results: List[str]) -> List[str]:
    """Возвращает список упавших тестов"""
    return [t for t in test_results if "FAILED" in t]

---

✅ Зачем использовать type annotations?

• Улучшает читаемость кода.

• Ускоряет понимание API функций.

• Позволяет IDE делать автодополнение и проверку.

• Упрощает рефакторинг.

• Работает с mypy и другими линтерами для поиска ошибок до запуска кода.