Как писать docstrings

Докстринги (буквально «строки документации») — это встроенная в код документация (обычно после инициализации функции / класса и прочих объектов между двумя '''), которую могут читать люди и инструменты (help(), pydoc, автогенераторы). В этом лонгриде мы разберемся, где и как их писать.


Зачем нужны docstrings — и чем они отличаются от комментариев

🔘Комментарии (#) объясняют реализацию и помогают разработчикам; интерпретатор их игнорирует.
🔘Докстринги — это строковые литералы (обычно в """`), помещённые сразу после определения модуля / функции / класса / метода; они сохраняются в атрибуте .__doc__` и доступны в рантайме (через .__doc__, help() и инструментах вроде pydoc.

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

Многострочные докстринги используются когда нужно подробнее описать параметры, поведение, побочные эффекты, примеры использования. По PEP 257 закрывающие кавычки обычно ставят на отдельной строке в многострочном docstring:

def get_book(publication_year, title):
    """
    Retrieve a Harry Potter book by its publication year and name.

    Parameters:
        publication_year (int): The year the book was published.
        title (str): The title of the book.

    Returns:
        str: A sentence describing the book and its publication year.
    """

Чтобы получить доступ к docstring в коде и терминале, вызываем:

🔘 obj.__doc__ — возвращает сырой docstring (часто краткий);
🔘 help(obj) — даёт структурированный вывод, полезный для модулей и классов;
🔘 python -m pydoc module — позволяет просматривать документацию из терминала и генерировать статичные страницы.


Что писать в docstring для модулей, функций и классов

Модуль:
🔘 Краткое описание назначения модуля.
🔘 При необходимости — описание экспортируемых переменных/классов/функций, примеры использования.

Функция / метод:
🔘 Краткое резюме (1–2 предложения).
🔘 Секция Parameters`/`Args: имена параметров, типы, краткое описание.
🔘 Секция Returns / Yields: что возвращается, тип.
🔘 Исключения: какие ошибки может выбросить функция (опционально, но полезно).
🔘 Пример использования или заметки о поведении (если нужно).

Класс:
🔘 Краткое описание назначения класса.
🔘 Описание атрибутов (публичных), краткая информация о методах (если интерфейс не очевиден).
🔘 Для сложных иерархий — примеры создания/использования. ([realpython.com][1])

#основы
@zen_of_python

Python митап от Авито 27 октября в Москве! ☄

Вечером 27 октября вас ждут в офисе на Лесной, чтобы обсудить:

➡ кейс оптимизации GC в Python от Саши Федосеева, backend-инженера из команды Main Page Tech Авито;
➡ как mypy укрощает Python в большой компании вместе с Сергеем Яхницким из Яндекса.

После докладов спикеры в формате круглого стола вместе с участниками обсудят, подходит ли Python для запуска больших нагруженных решений.

Для тех, кто не успевает вырваться из офиса или дома, будет онлайн-трансляция.

Так что не откладывайте, регистрируйтесь и зовите коллег — все подробности по ссылке.

Это #партнёрский пост

Зачем нужны «ленивые» (lazy) импорты

Когда модуль импортируется, интерпретатор выполняет весь код на глобальном уровне этого модуля, включая все его собственные импорты и инициализации. В больших приложениях и тестовых наборах это может заметно замедлять запуск и фазу сбора тестов. Поэтому идея «ленивого импорта» — откладывать импорт «тяжёлых» зависимостей до момента, когда они действительно понадобятся — помогает улучшить отзывчивость приложения и сократить время тестирования.


Переносим import внутрь функции

Самый очевидный и безопасный способ сделать импорт ленивым — переместить import из глобальной области видимости внутрь функции или метода, где ресурс реально используется. При таком подходе импорт произойдёт только при первом вызове этой функции (и далее кешируется в sys.modules, поэтому реальной «повторной» загрузки не происходит). Это даёт быстрый выигрыш для модулей, которые редко используются или инициализируют тяжёлые зависимости:

def do_heavy_task():
    import heavy_lib
    heavy_lib.run()

Плюсы: простота. Минусы: если импорт нужен во многих местах, придётся либо дублировать import (что допустимо), либо устанавливать глобальную переменную после первого импорта.


Вариант с importlib — когда нужно контролировать пространство имён

Если хочется более явного контроля (например, избежать появления имени в локальной области каждой функции), можно использовать importlib.import_module() и присваивать результат в переменную (глобальную или локальную). Это зачастую полезно при динамическом импорте по имени строки:

Пример:

from importlib import import_module

def use_feature():
    mod = import_module("heavy_lib")
    mod.do()

Как найти «тяжёлые» импорты — инструмент `python -X importtime

Прежде чем делать импорты ленивыми, полезно понять, что именно тормозит загрузку. Для этого есть встроенная опция: python -X importtime your_program.py — она выводит дерево импорта с временами, позволяя увидеть самые затратные узлы. Это особенно полезно при оптимизации большого проекта или ускорении фазы сбора тестов.


Особая зона внимания — pytest и фаза collection

Pytest во время collection импортирует все тестовые файлы — следовательно, импорты в глобальной области тестов будут исполнены на этапе collection, даже если сам тест не будет запущен. Это распространённый источник задержек в больших тестовых наборах. Решение — переносить импорты внутрь тестовых функций, использовать importlib внутри тестов.


«Глобальный» трюк

Если модуль содержит множество функций, которые все используют одну и ту же тяжёлую библиотеку, имеет смысл импортировать её при первом нужном вызове и сохранить в глобальной переменной модуля (через `global`).
Короткая иллюстрация:

# module.py
heavy = None

def first_use():
    global heavy
    if heavy is None:
        import heavy_lib
        heavy = heavy_lib
    heavy.do()

Когда ленивые импорты — плохая идея

🔘 Если импорт жизненно важен для модуля и должен бросать ошибки во время старта (fail fast), откладывание импорта может скрыть проблему до момента выполнения, что усложнит отладку.
🔘 Когда импорт идёт с побочными эффектами, которые вы ожидаете увидеть при импортировании модуля — откладывая импорт, вы меняете поведение.

#основы
@zen_of_python