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

Аннотация возвращаемого типа в Python

Аннотация возвращаемого типа (return type annotation) — это синтаксис, который позволяет указать, какой тип данных возвращает функция. Это улучшает читаемость кода, помогает IDE и инструментам статического анализа найти ошибки.

Базовый синтаксис

def function_name(param1: type1, param2: type2) -> return_type:
    """Описание функции"""
    return value

Стрелка -> указывает на тип возвращаемого значения.

Простые примеры

# Функция возвращает строку
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Функция возвращает число
def add(a: int, b: int) -> int:
    return a + b

# Функция возвращает булево значение
def is_even(num: int) -> bool:
    return num % 2 == 0

# Функция ничего не возвращает
def print_message(message: str) -> None:
    print(message)

# Функция возвращает float
def calculate_average(numbers: list) -> float:
    return sum(numbers) / len(numbers)

Аннотация для коллекций

from typing import List, Dict, Tuple, Set

# Возвращает список целых чисел
def get_numbers() -> List[int]:
    return [1, 2, 3, 4, 5]

# Возвращает словарь
def get_user_data() -> Dict[str, str]:
    return {"name": "John", "email": "john@example.com"}

# Возвращает кортеж
def get_coordinates() -> Tuple[float, float]:
    return (10.5, 20.3)

# Возвращает множество
def get_unique_ids() -> Set[int]:
    return {1, 2, 3, 4, 5}

Объединение типов (Union)

from typing import Union, Optional

# Функция может вернуть int или str
def process_data(data: str) -> Union[int, str]:
    try:
        return int(data)
    except ValueError:
        return data

# Функция может вернуть значение или None
def find_user(user_id: int) -> Optional[Dict[str, str]]:
    users = {1: {"name": "John"}, 2: {"name": "Jane"}}
    return users.get(user_id)  # Возвращает dict или None

# С Python 3.10+ можно использовать | (pipe)
def get_value(key: str) -> int | str | None:
    return None

Аннотация для классов

# Функция возвращает объект класса
class User:
    def __init__(self, name: str):
        self.name = name

def create_user(name: str) -> User:
    return User(name)

# Самовозвращаемый тип (для методов)
class Calculator:
    def add(self, x: int) -> "Calculator":
        print(f"Добавление {x}")
        return self  # Возвращает себя для chain методов

# Использование
calc = Calculator().add(5).add(10)

Сложные типы

from typing import Callable, Iterator, Generator

# Функция возвращает другую функцию
def make_multiplier(n: int) -> Callable[[int], int]:
    def multiplier(x: int) -> int:
        return x * n
    return multiplier

multiply_by_3 = make_multiplier(3)
print(multiply_by_3(5))  # 15

# Функция возвращает генератор
def count_up_to(n: int) -> Generator[int, None, None]:
    i = 0
    while i < n:
        yield i
        i += 1

# Функция возвращает итератор
def iterate_data(data: list) -> Iterator[int]:
    for item in data:
        yield item

Списки с типами элементов

from typing import List, Dict, List

# Список с элементами определённого типа
def get_user_names() -> List[str]:
    return ["Alice", "Bob", "Charlie"]

# Список словарей
def get_users() -> List[Dict[str, str]]:
    return [
        {"id": "1", "name": "Alice"},
        {"id": "2", "name": "Bob"}
    ]

# Вложенные списки
def get_matrix() -> List[List[int]]:
    return [
        [1, 2, 3],
        [4, 5, 6],
        [7, 8, 9]
    ]

Практический пример: API функции

from typing import List, Optional, Dict
from dataclasses import dataclass

@dataclass
class UserResponse:
    id: int
    name: str
    email: str

class UserService:
    def get_users(self, page: int = 1) -> List[UserResponse]:
        """Получить список пользователей"""
        return [
            UserResponse(1, "John", "john@example.com"),
            UserResponse(2, "Jane", "jane@example.com")
        ]
    
    def get_user(self, user_id: int) -> Optional[UserResponse]:
        """Получить пользователя или None"""
        if user_id == 1:
            return UserResponse(1, "John", "john@example.com")
        return None
    
    def update_user(self, user_id: int, data: Dict[str, str]) -> UserResponse:
        """Обновить пользователя"""
        return UserResponse(user_id, data["name"], data["email"])
    
    def delete_user(self, user_id: int) -> None:
        """Удалить пользователя"""
        print(f"Пользователь {user_id} удалён")

Аннотация с несколькими возвращаемыми значениями

from typing import Tuple

# Функция возвращает кортеж
def split_name(full_name: str) -> Tuple[str, str]:
    first, last = full_name.split()
    return first, last

# Использование
first, last = split_name("John Doe")

# Кортеж с именованными элементами (Python 3.6+)
from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

def get_location() -> Point:
    return Point(10.5, 20.3)

point = get_location()
print(point.x, point.y)

Использование аннотаций с mypy

# Статическая проверка типов
def add(a: int, b: int) -> int:
    return a + b

# Это вызовет ошибку при проверке mypy
result: str = add(5, 10)  # Error: Incompatible types

# Правильное использование
result: int = add(5, 10)  # OK

IDE помощь благодаря аннотациям

from typing import List

def get_user_ids() -> List[int]:
    return [1, 2, 3, 4, 5]

# IDE автоматически подскажет методы список
ids = get_user_ids()
ids.append(6)  # IDE поймёт, что это список и подскажет методы
ids.sort()      # IDE покажет методы списка

# Без аннотации IDE не сможет помочь
def get_data():
    return [1, 2, 3]  # IDE не знает, что это список

Проверка аннотаций в runtime

from typing import get_type_hints

def greet(name: str) -> str:
    return f"Hello, {name}!"

# Получить аннотации функции
hints = get_type_hints(greet)
print(hints)  # {'name': <class 'str'>, 'return': <class 'str'>}

# Проверить тип возврата
if hints.get('return') == str:
    print("Функция возвращает строку")

Лучшие практики

# ✓ ХОРОШО - явно указаны все типы
def calculate(data: List[int]) -> float:
    return sum(data) / len(data)

# ✗ ПЛОХО - использование Any (избегать)
from typing import Any
def process(data: Any) -> Any:
    return data

# ✓ ХОРОШО - используй Optional вместо None
def find_item(items: List[str], target: str) -> Optional[str]:
    return target if target in items else None

# ✓ ХОРОШО - документируй сложные типы
def transform_users(users: List[Dict[str, str]]) -> Dict[int, str]:
    """Преобразовать список пользователей в словарь ID->имя"""
    return {i: user["name"] for i, user in enumerate(users)}

Вывод

Аннотация возвращаемого типа — это лучшая практика в Python, которая:

• Улучшает читаемость кода
• Помогает IDE подсказывать правильные методы
• Позволяет инструментам (mypy) находить ошибки типов
• Упрощает поддержку и рефакторинг кода
• Документирует ожидаемое поведение функции

Использование аннотаций типов — это стандарт в современной Python разработке.