Глава 13 · Автоматизация с помощью функций

Докстринги и подсказки типов

Профессиональная привычка, которую стоит выработать рано: документировать функцию так, чтобы её можно было понять, не читая реализацию.

Докстринг — документация функции

docstring.py

def rectangle_area(width, height):
    """Возвращает площадь прямоугольника."""
    return width * height

	Комментарий (# ...)	Докстринг ("""...""")
Объясняет	почему код написан именно так	что делает функция — как API
Виден снаружи?	нет, только в исходнике	да, через help() и __doc__

help() показывает докстринг во время работы программы

help_primer.py

help(rectangle_area)
print(rectangle_area.__doc__)

Help on function rectangle_area in module __main__:

rectangle_area(width, height)
    Возвращает площадь прямоугольника.

help() достаёт докстринг прямо из объекта функции — та же идея, что мы уже видели у встроенных функций

Type hints — подсказки типов

type_hints.py

def rectangle_area(width: float, height: float) -> float:
    return width * height

Часть	Значение
`width: float`	ожидаемый тип параметра
`-> float`	ожидаемый тип возвращаемого значения

Подсказки типов не проверяются автоматически во время выполнения

def add(a: int, b: int) -> int: НЕ помешает вызвать add("2", "3") — Python не станет автоматически приводить строки к числам и не выбросит ошибку сам по себе. Аннотации типов — это документация и подсказка для инструментов разработки, а не runtime-проверка.

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

annotacii_kollekcij.py

def average(scores: list[float]) -> float:
    return sum(scores) / len(scores)

def count_words(text: str) -> dict[str, int]:
    ...

Необязательное значение в аннотации

optional_annotation.py

def find_user(name: str) -> str | None:
    ...

str | None читается как «строка или None»

Такая аннотация говорит: функция либо вернёт строку, либо None, если ничего не найдено. Это не отдельная тема — просто способ явно описать словами то, что мы уже видели на практике (например, у dict.get()).

Аннотации не отменяют ловушку изменяемого умолчания

annotacii_ne_spasayut.py

def add(item: str, items: list[str] = []):
    ...
    # всё ещё та же ловушка из §13.7!

Аннотации типов — это документация, а не защита от ошибок времени выполнения

Даже с полными аннотациями items: list[str] = [] остаётся тем же изменяемым значением по умолчанию, что и раньше — аннотация ничего не меняет в реальном поведении функции.

Практика: докстринги и подсказки типов

Интерактивный ноутбук прямо в браузере — Python 3.14 через Pyodide, без установки

Открыть практику →

← Назад

Проектируем хорошую функцию

Функции как объекты