Аннотации типов Python: полное практическое пособие

1. Аннотации с использованием Literal (Python 3.8+)

Тип Literal позволяет ограничить значение конкретными литералами (строками, числами, булевыми).

from typing import Literal

def set_mode(mode: Literal["read", "write", "append"]) -> str:
    if mode == "read":
        return "Opening file for reading"
    elif mode == "write":
        return "Opening file for writing"
    else:
        return "Opening file for appending"

print(set_mode("read"))

Opening file for reading

Если передать недопустимое значение, статический анализатор выдаст ошибку.

2. TypedDict для строгой типизации словарей

TypedDict определяет структуру словаря с конкретными ключами и типами значений.

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int
    email: str | None

def process_person(p: Person) -> str:
    return f"{p['name']} (age {p['age']})"

data: Person = {"name": "Alice", "age": 30, "email": None}
print(process_person(data))

Alice (age 30)

Примечание:

TypedDict не проверяется во время выполнения, только статически. Для проверки во время выполнения можно использовать dataclass.

3. ParamSpec и Concatenate для декораторов, сохраняющих сигнатуру (Python 3.10+)

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

from typing import Callable, ParamSpec, TypeVar

P = ParamSpec('P')
T = TypeVar('T')

def log_call(func: Callable[P, T]) -> Callable[P, T]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

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

result = add(2, 3)
print(result)

Calling add
5

4. Аннотации с использованием Self (Python 3.11+) для возврата текущего класса

Self упрощает паттерн builder и цепочки методов.

from typing import Self

class Builder:
    def __init__(self):
        self._items: list[str] = []

    def add(self, item: str) -> Self:
        self._items.append(item)
        return self

    def build(self) -> str:
        return ', '.join(self._items)

b = Builder().add("apple").add("banana")
print(b.build())

apple, banana

5. Аннотации для асинхронных функций (async/await)

Асинхронные функции аннотируются как обычные, но возвращаемый тип обычно Coroutine или конкретный тип с обёрткой.

import asyncio
from typing import Coroutine

async def fetch_data(url: str) -> dict:
    # имитация запроса
    await asyncio.sleep(1)
    return {"status": 200, "data": "ok"}

async def main() -> None:
    result = await fetch_data("http://example.com")
    print(result)

asyncio.run(main())

{'status': 200, 'data': 'ok'}

Если функция возвращает Coroutine, можно указать типы передаваемых и возвращаемых значений: Coroutine[Any, Any, dict].

6. Аннотации с использованием TypeGuard (Python 3.10+)

TypeGuard позволяет пользовательской функции проверки типа сужать тип переменной для анализатора.

from typing import TypeGuard

def is_string_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> None:
    if is_string_list(items):
        # теперь items считается list[str]
        print(' '.join(items))
    else:
        print("Not all strings")

process(["hello", "world"])

hello world

7. Аннотации для исключений (raise/except) с помощью Never (Python 3.11+)

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

from typing import Never

def abort(message: str) -> Never:
    raise SystemExit(message)

def risky() -> int:
    abort("Fatal error")
    return 0  # этот код недостижим

8. Аннотации с использованием overload (перегрузка функций)

Декоратор @overload позволяет описать несколько сигнатур одной функции для разных типов аргументов.

from typing import overload

@overload
def process(data: int) -> str: ...

@overload
def process(data: str) -> int: ...

def process(data: int | str) -> str | int:
    if isinstance(data, int):
        return str(data)
    else:
        return len(data)

print(process(42))   # str
print(process("hi")) # int

42
2

Перегрузки улучшают автодополнение и проверку типов.