Зачем применять typing при разработке на Python

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

В этой части перечислены дополнительные сценарии применения typing. Каждый пример содержит код и результат его выполнения.

Пример 1. TypeVar с ограничением

from typing import TypeVar

Number = TypeVar('Number', int, float)

def square(value: Number) -> Number:
    return value * value

print(square(3))
print(square(2.5))

9
6.25

TypeVar с двумя ограничениями разрешает только int и float. Функция возвращает значение того же типа. Если передать строку, mypy сообщит об ошибке.

Пример 2. Перегрузка функций

from typing import overload, Union

@overload
def convert(value: str) -> int: ...

@overload
def convert(value: int) -> str: ...

def convert(value: Union[str, int]) -> Union[str, int]:
    if isinstance(value, str):
        return int(value)
    return str(value)

print(convert('42'))
print(convert(42))

42
42

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

Пример 3. Протокол и структурная совместимость

from typing import Protocol

class Named(Protocol):
    name: str

def greeting(obj: Named) -> str:
    return 'Hello, ' + obj.name

class Person:
    def __init__(self, name: str) -> None:
        self.name = name

class Robot:
    def __init__(self, model: str) -> None:
        self.model = model

    @property
    def name(self) -> str:
        return self.model

print(greeting(Person('Alice')))
print(greeting(Robot('R2D2')))

Hello, Alice
Hello, R2D2

Protocol не требует явного наследования. Достаточно совпадения атрибутов.

Пример 4. Annotated с метаданными

from typing import Annotated

def connect(host: Annotated[str, 'ip or domain name']) -> None:
    print(host)

connect('example.com')

example.com

Annotated добавляет дополнительную информацию о типе. Она не участвует в проверке, но доступна через __metadata__.

Пример 5. TypedDict с необязательными полями

from typing import TypedDict

class Settings(TypedDict, total=False):
    width: int
    height: int
    title: str

def apply_settings(settings: Settings) -> int:
    return settings.get('width', 0) * settings.get('height', 0)

print(apply_settings({'width': 3, 'height': 4}))
print(apply_settings({}))

12
0

total=False означает, что ключи можно опускать. Указание других ключей не допускается.

Пример 6. NewType для разграничения смысловых типов

from typing import NewType

UserId = NewType('UserId', int)
ProductId = NewType('ProductId', int)

def find_user(user_id: UserId) -> str:
    return 'user ' + str(user_id)

user = UserId(7)
print(find_user(user))
product = ProductId(3)
# print(find_user(product))  # mypy: incompatible type

user 7

NewType создаёт подтип int. Анализатор не позволяет передать ProductId в аргумент UserId, хотя во время выполнения это обычное число.

Пример 7. get_type_hints для чтения аннотаций

from typing import get_type_hints, List, Optional

def process(items: List[Optional[int]]) -> Optional[int]:
    return items[0] if items else None

print(get_type_hints(process))

{'items': typing.List[typing.Optional[int]], 'return': typing.Optional[int]}

get_type_hints возвращает словарь с аннотациями. Это удобно для библиотек, которые анализируют сигнатуры.

Пример 8. Literal и Final

from typing import Final, Literal

MAX_ATTEMPTS: Final = 3

def retry(count: Literal[1, 2, 3]) -> str:
    return 'attempts: ' + str(count)

print(retry(2))

attempts: 2

Literal разрешает только перечисленные значения. Final запрещает повторное присваивание при проверке.

Пример 9. Generic класс

from typing import Generic, TypeVar, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: List[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

stack = Stack[int]()
stack.push(1)
print(stack.pop())

1

Generic класс позволяет переиспользовать логику для разных типов. При создании Stack[int] параметр T замещается int.