Полное руководство по аннотациям параметров и возвращаемых значений

Как аннотировать функции, которые могут возвращать None или принимать разные типы?

Тип Optional обозначает возможность None, Union объединяет несколько типов, Any указывает на любой тип.

from typing import Optional, Union, Any

def find_user(user_id: int) -> Optional[str]:
    # возвращает имя пользователя или None
    return None

def process(value: Union[int, float, str]) -> str:
    return str(value)

def debug(message: Any) -> None:
    print(message)

абсолютное значение python (абсолютное значение в python)

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

Как аннотировать аргументы *args и **kwargs?

Для *args указывается тип элемента кортежа, для **kwargs - тип значения в словаре. Обычно это Tuple[Type, ...] и Dict[str, Type].

from typing import Tuple, Dict

def sum_all(*args: int) -> int:
    return sum(args)

def config(**kwargs: str) -> None:
    for key, value in kwargs.items():
        print(f'{key}: {value}')

вернуть значение функции python (возврат значения из функции в python)

Цель: описать, что args содержит только целые числа, а kwargs только строковые значения.

Как аннотировать функцию, принимающую другую функцию?

Тип Callable[[параметры], возвращаемый_тип] позволяет описать сигнатуру передаваемой функции.

from typing import Callable

def apply_twice(func: Callable[[int], int], value: int) -> int:
    return func(func(value))

def double(x: int) -> int:
    return x * 2

result = apply_twice(double, 5)  # 20

значения функции python (значения функции в python)

Цель: явно указать, что ожидается функция с определённой сигнатурой, что упрощает документацию и проверку.

Как создать обобщенную функцию, работающую с любым типом?

TypeVar используется для обозначения переменной типа, а затем функция аннотируется с его помощью. Для классов применяется Generic.

from typing import TypeVar, List

T = TypeVar('T')

def first_element(lst: List[T]) -> T:
    return lst[0]

print(first_element([1, 2, 3]))  # 1
print(first_element(['a', 'b']))  # 'a'

вывести значение функции python (вывести значение функции в python)

Цель: сохранить информацию о типе элемента внутри функции, чтобы возвращаемый тип соответствовал входному типу.

Как сделать код более читаемым с помощью псевдонимов типов?

TypeAlias (Python 3.10+) или простое присвоение типа переменной позволяет создавать псевдонимы.

from typing import TypeAlias, List, Tuple

Point: TypeAlias = Tuple[float, float]
Polygon: TypeAlias = List[Point]

def area(poly: Polygon) -> float:
    # вычисление площади
    return 0.0

вызов функции в python (вызов функции в python)

Цель: улучшение читаемости, особенно для сложных составных типов, и лёгкость изменения определения.

Как аннотировать функцию, ожидающую объект с определёнными методами, без наследования?

Protocol из модуля typing (Python 3.8+) определяет ожидаемые атрибуты и методы.

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: Drawable) -> None:
    obj.draw()

class Circle:
    def draw(self) -> None:
        print('Рисую круг')

render(Circle())  # OK

Python имена функций (имена функций в python)

Цель: реализация утиной типизации с возможностью статической проверки, не требуя явного наследования.

Как аннотировать функцию-декоратор, чтобы сохранить типы обёрнутой функции?

Callable и TypeVar применяются для обобщения, часто используется functools.wraps и модуль typing.

from typing import Callable, TypeVar
import functools

F = TypeVar('F', bound=Callable[..., Any])

def log_decorator(func: F) -> F:
    @functools.wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        print(f'Вызов {func.__name__}')
        return func(*args, **kwargs)
    return wrapper  # type: ignore

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