Что такое type hints (аннотации типов) и зачем они нужны?

Type hints (аннотации типов) в Python

Type hints — это способ явно указать, какие типы данных ожидают параметры функции и что она возвращает. Это не обязательно, но сильно улучшает качество кода.

Базовая синтаксис type hints

from typing import List, Dict, Optional, Union

# Простые аннотации
def greet(name: str) -> str:
    return f"Hello, {name}!"

# С несколькими параметрами
def add(a: int, b: int) -> int:
    return a + b

# С более сложными типами
def process_users(users: List[Dict[str, int]]) -> bool:
    return len(users) > 0

# Опциональные параметры (может быть None)
def get_user(user_id: int, fallback: Optional[str] = None) -> Optional[str]:
    if user_id > 0:
        return f"User {user_id}"
    return fallback

# Union — один из нескольких типов
def convert(value: Union[str, int]) -> str:
    return str(value)

Зачем нужны type hints?

1. Самодокументирование кода

Когда разработчик смотрит на функцию, сразу видит, что она ожидает и что возвращает. Не нужно гадать.

# Без type hints — не понятно
def calculate(values):
    return sum(values)

# С type hints — сразу ясно
def calculate(values: List[float]) -> float:
    return sum(values)

2. Помощь IDE и автодополнение

Модерные IDE (PyCharm, VS Code) используют type hints для автодополнения и подсказок.

users: List[str] = ["John", "Jane"]
for user in users:
    user.upper()  # IDE подскажет методы строки

3. Обнаружение ошибок до запуска

Инструменты статического анализа (mypy, pyright) проверяют типы и находят ошибки.

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

add(5, "10")  # mypy выдаст ошибку: str не является int

4. Рефакторинг безопаснее

Если ты переделываешь функцию, type hints помогут убедиться, что все вызовы совместимы.

5. Улучшение качества кода

Type hints заставляют думать о том, какие данные используются, что часто выявляет проблемы в дизайне.

Пример: сложный случай

from typing import Callable, TypeVar, Generic
from datetime import datetime

T = TypeVar('T')

class Cache(Generic[T]):
    def __init__(self, ttl: int = 3600):
        self.ttl: int = ttl
        self.data: Dict[str, tuple[T, datetime]] = {}
    
    def get(self, key: str) -> Optional[T]:
        if key not in self.data:
            return None
        value, timestamp = self.data[key]
        if (datetime.now() - timestamp).seconds > self.ttl:
            del self.data[key]
            return None
        return value
    
    def set(self, key: str, value: T) -> None:
        self.data[key] = (value, datetime.now())

# Использование
cache: Cache[str] = Cache(ttl=3600)
cache.set("user_1", "John")
user: Optional[str] = cache.get("user_1")

Python 3.10+: улучшения

# Старый стиль (Python 3.9 и ниже)
from typing import Union
def func(value: Union[str, int]) -> Union[str, None]:
    pass

# Новый стиль (Python 3.10+)
def func(value: str | int) -> str | None:
    pass

# Также работают встроенные generic типы
from typing import List
data: List[str]  # Python 3.9
data: list[str]  # Python 3.10+

Как использовать type hints правильно?

# ХОРОШО
from typing import List, Dict, Optional

def get_user_posts(user_id: int) -> List[Dict[str, str]]:
    """Получает посты пользователя."""
    # Реализация
    pass

# ПЛОХО — без type hints
def get_user_posts(user_id):
    pass

# ПЛОХО — вся функция Any
from typing import Any
def process(data: Any) -> Any:
    pass

Инструменты для проверки типов

# mypy — самый популярный инструмент статического анализа
mypy your_file.py

# pyright — альтернатива от Microsoft
pyright your_file.py

# pydantic — валидация данных в runtime
from pydantic import BaseModel, ValidationError

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

User(id="invalid")  # Выбросит ValidationError

Типичные type hints для Django/FastAPI

from fastapi import FastAPI
from typing import List, Optional

app = FastAPI()

class User:
    id: int
    name: str
    email: str

@app.get("/users", response_model=List[User])
async def get_users(skip: int = 0, limit: int = 10) -> List[User]:
    pass

@app.post("/users", response_model=User)
async def create_user(user: User) -> User:
    pass

Вывод

Type hints — это не просто украшение кода, это инвестиция в качество. Они помогают:

• Находить ошибки раньше
• Писать более понятный код
• Облегчают рефакторинг
• Улучшают опыт работы в IDE

Для производственного кода type hints должны быть стандартом, а не исключением.