Тип возвращаемого значения функции: инструкция по аннотациям

Как обозначить, что функция не возвращает значение?

Указывается тип None после стрелки. Это явно говорит о том, что функция выполняется ради побочных эффектов.

def write_file(path: str, data: str) -> None:
    with open(path, 'w') as f:
        f.write(data)

Python 3.12 type (новые возможности типов в python 3.12)

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

Используется Union из модуля typing или оператор | в Python 3.10+.

from typing import Union

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

Python typing type checking (проверка типов с помощью typing в python)

В Python 3.10+ можно писать короче:

def parse_number(text: str) -> int | float:
    ...

Python type dict (тип dict в python)

Как показать, что функция может вернуть None или значение определённого типа?

Специальная конструкция Optional[тип] (эквивалент Union[тип, None]). Рекомендуется использовать тип | None в Python 3.10+.

from typing import Optional

def find_user(user_id: int) -> Optional[dict]:
    if user_id in database:
        return database[user_id]
    return None

Python return type (тип возврата функции в python)

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

Используется тип Any из typing. Однако это снижает эффективность статической проверки.

from typing import Any

def get_data(source: str) -> Any:
    if source == 'config':
        return {'key': 'value'}
    elif source == 'list':
        return [1, 2, 3]
    return None

Как указать, что функция возвращает другую функцию?

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

from typing import Callable

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

Как описать тип возврата генератора?

Генераторы возвращают объекты, реализующие протокол итерации. Чаще всего используют Iterator[тип] или Generator[тип_yield, тип_send, тип_return].

from typing import Iterator

def count_to(n: int) -> Iterator[int]:
    for i in range(1, n + 1):
        yield i

Если генератор использует send и return, нужен полный Generator:

from typing import Generator

def controlled_counter() -> Generator[int, str, bool]:
    total = 0
    cmd = yield total
    if cmd == 'stop':
        return True
    return False

Как аннотировать асинхронную функцию?

Асинхронная функция (async def) возвращает корутину. Тип возврата – Coroutine[Any, Any, тип] из модуля typing или его упрощение – просто указать возвращаемый тип без обёртки, но это менее точно.

from typing import Coroutine
import asyncio

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

Современные анализаторы (mypy) часто принимают упрощённый вариант:

async def fetch_data(url: str) -> dict:
    ...

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

Используется TypeVar для связывания типов входа и выхода.

from typing import TypeVar

T = TypeVar('T')

def identity(value: T) -> T:
    return value

Можно ограничить TypeVar с помощью bound или указать несколько TypeVar для разных позиций.

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

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

from typing import overload

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

@overload
def parse(data: bytes) -> str: ...

def parse(data: str | bytes) -> int | str:
    if isinstance(data, str):
        return int(data)
    return data.decode()