Аннотации функций: возвращаемые значения

Как аннотировать функцию, которая может не возвращать значение (None)?

Для функций, которые завершаются без явного return или возвращают None, обычно указывают -> None.

def print_message(msg: str) -> None:
    print(msg)

Если функция иногда возвращает значение, а иногда None, используют Optional[Тип] или эквивалент Union[Тип, None]. Начиная с Python 3.10, можно писать Тип | None.

from typing import Optional, Union

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

# Эквивалентные записи:
# def find_user(user_id: int) -> Union[str, None]:
# def find_user(user_id: int) -> str | None:

Как указать, что функция возвращает значение одного из нескольких типов (Union)?

Когда функция может возвращать значения разных типов, применяют Union.

from typing import Union

def parse_number(value: str) -> Union[int, float]:
    try:
        return int(value)
    except ValueError:
        return float(value)

С Python 3.10 используется синтаксис int | float.

Когда стоит использовать Any для возврата?

Если возвращаемое значение действительно может быть любого типа (например, десериализация JSON), допустимо написать -> Any. Однако это отключает проверку типов, поэтому применяется редко.

from typing import Any

def load_json(data: str) -> Any:
    import json
    return json.loads(data)

Как аннотировать возврат функции, возвращающей другую функцию (Callable)?

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

from typing import Callable

def create_multiplier(factor: int) -> Callable[[float], float]:
    def multiply(x: float) -> float:
        return x * factor
    return multiply

Здесь Callable[[float], float] означает функция, принимающая float и возвращающая float.

Как обобщить возвращаемый тип с помощью TypeVar (дженерики)?

Когда функция возвращает значение, тип которого зависит от входных данных, применяют TypeVar.

from typing import TypeVar, List

T = TypeVar('T')

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

Теперь first_element([1,2,3]) выведет int, а first_element(['a','b']) - str.

Как задать разные возвращаемые типы для разных сценариев вызова (overload)?

Декоратор @typing.overload позволяет определить несколько сигнатур для одной функции. Полезно, когда тип возвращаемого значения зависит от типа аргумента или его присутствия.

from typing import overload, Union

@overload
def to_str(value: int) -> str: ...
@overload
def to_str(value: float) -> str: ...
@overload
def to_str(value: None) -> str: ...

def to_str(value: Union[int, float, None]) -> str:
    if value is None:
        return ""
    return str(value)

Реализация должна покрывать все перегруженные варианты. mypy использует перегрузки для точного вывода типов.

Как ограничить возвращаемое значение конкретными литералами (Literal)?

Если функция возвращает только фиксированный набор строк или чисел, применяют Literal.

from typing import Literal

def get_status() -> Literal['ok', 'error', 'pending']:
    # ...
    return 'ok'

Теперь mypy проверит, что возвращается только одно из этих значений.

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

Protocol позволяет определить структурный тип (утиная типизация) для возвращаемого объекта. Полезно, если нужно описать интерфейс без наследования.

from typing import Protocol

class Named(Protocol):
    name: str
    def greet(self) -> str: ...

def create_person(name: str) -> Named:
    class Person:
        def __init__(self, name: str):
            self.name = name
        def greet(self) -> str:
            return f"Hello, {self.name}"
    return Person(name)

Функция гарантирует, что возвращаемый объект имеет атрибут name и метод greet.