Appearance
Документирование кода
В Python документация — это не просто комментарии для человека. Это структурированные строки (docstrings), которые формируют встроенную справку, отображаются в IDE при наведении на методы и могут автоматически превращаться в полноценные сайты.
Из этого урока вы узнаете, как оформлять документацию в самом читаемом Google Style, документировать уровни доступа (публичные, защищенные, приватные) и писать интерактивные примеры.
1. Стили Docstrings: Почему именно Google Style?
В Python-сообществе существует три основных стандарта:
- Google Style: Самый читаемый и популярный стиль. Использует понятные текстовые отступы и секции (Args:, Returns:, Attributes:).
- NumPy Style: Более развернутый стиль, где заголовки секций подчеркиваются дефисами. Часто применяется в data science.
- Sphinx / ReStructuredText (reST) Style: Стандартный стиль для генератора документации Sphinx. Использует синтаксис двоеточий (например, :param x:). Менее читаем в сыром виде, но отлично парсится.
Мы будем изучать Google Style, так как он признан самым сбалансированным: он легко читается человеком прямо в текстовом редакторе и при этом идеально парсится автоматическими генераторами.
Базовые секции Google Style:
Attributes:— для описания свойств класса.Args:— для аргументов функций и методов.Returns:— для возвращаемых значений.Raises:— для перечисления возможных ошибок (исключений).
py
class PaymentProcessor:
"""Процессор для управления финансовыми транзакциями пользователей.
Этот класс инкапсулирует логику работы с платежными шлюзами,
проверки баланса и безопасного списания средств.
Attributes:
is_active (bool): Публичный флаг доступности процессора.
_gateway_timeout (int): Защищенный (protected) таймаут соединения в секундах.
__encryption_key (str): Приватный (private) ключ для подписи транзакций.
"""
def __init__(self, gateway_timeout: int = 30) -> None:
"""Инициализирует процессор платежей.
Args:
gateway_timeout (int): Время ожидания ответа от шлюза.
"""
# 1. Публичный атрибут (доступен везде)
self.is_active: bool = True
# 2. Защищенный атрибут (на уровне соглашения: для подклассов и модуля)
self._gateway_timeout: int = gateway_timeout
# 3. Приватный атрибут (инкапсулирован внутри класса через Name Mangling)
self.__encryption_key: str = "SECRET_HEX_KEY_123"
def process_payment(self, account_id: str, amount: float) -> bool:
"""Публичный метод: Проводит транзакцию для указанного аккаунта.
Используется внешним кодом для инициации оплаты.
Args:
account_id (str): Уникальный идентификатор пользователя.
amount (float): Сумма списания (должна быть строго больше 0).
Returns:
bool: True, если платеж успешно проведен, иначе False.
Raises:
ValueError: Если сумма `amount` меньше или равна нулю.
"""
if amount <= 0:
raise ValueError("Сумма транзакции должна быть положительной.")
# Вызов защищенного метода
return self._connect_to_gateway(account_id, amount)
def _connect_to_gateway(self, account_id: str, amount: float) -> bool:
"""Защищенный метод: Устанавливает соединение со шлюзом.
Предназначен для внутреннего использования и переопределения в наследниках.
Args:
account_id (str): Идентификатор аккаунта.
amount (float): Сумма для отправки в шлюз.
Returns:
bool: Статус ответа сервера.
"""
# Логика подключения...
# Вызов приватного метода для подписи данных
signature = self.__sign_data(f"{account_id}:{amount}")
return True
def __sign_data(self, data: str) -> str:
"""Приватный метод: Шифрует данные перед отправкой.
Доступен строго внутри этого класса. Защищает критическую логику.
Args:
data (str): Строка сырых данных для подписи.
Returns:
str: Хэш-подпись в формате строки.
"""
# Логика шифрования с использованием self.__encryption_key
return f"signed_{data}"Основные правила оформления для Python:
• Где описывать свойства (Attributes): Публичные и защищенные атрибуты класса принято перечислять в блоке Attributes: внутри docstring самого класса, а не внутри __init__. • Приватные атрибуты и методы: Технически, писать подробную документацию к приватным элементам (с __) для внешних пользователей не нужно, так как они скрыты внутри класса. Однако для разработчиков, которые будут поддерживать ваш код, их документируют точно так же (через краткое описание аргументов и возвращаемого значения).
Какие еще секции могут быть в Docstrings?
Ниже представлены основные дополнительные секции, расположенные в логическом порядке их применения: • Raises: (или Yields: для генераторов) — перечень всех исключений, которые метод может намеренно выбросить, и условия, при которых это происходит. • Example: или Examples: — секция для демонстрации работы кода (здесь и размещаются примеры). • Note: — важные примечания, особенности поведения метода или скрытые нюансы, о которых должен знать разработчик. • Warning: — предупреждения о потенциально опасных действиях (например, «метод удаляет данные без возможности восстановления» или «метод не потокобезопасен»). • Todo: — временные метки для планирования будущих доработок (многие IDE подсвечивают их автоматически). • Deprecated: — указание на то, что метод устарел, с рекомендацией, чем его заменить.
Примеры кода оформляются в секции Examples:. Чтобы генераторы документации правильно их форматировали, а встроенный модуль Python doctest мог их тестировать, код записывают так, будто вы вводите его в интерактивной консоли Python (используя символы >>> для строк кода и следующую строку для ожидаемого вывода).
Полный пример класса со всеми секциями:
py
class Calculator:
"""Простой калькулятор для демонстрации расширенных секций документации.
Attributes:
precision (int): Количество знаков после запятой для округления.
"""
def __init__(self, precision: int = 2) -> None:
self.precision: int = precision
def divide(self, dividend: float, divisor: float) -> float:
"""Делит одно число на другое с заданным округлением.
Args:
dividend (float): Делимое число.
divisor (float): Делитель (не должен быть равен нулю).
Returns:
float: Результат деления, округленный до `precision` знаков.
Raises:
ZeroDivisionError: Если `divisor` равен 0.
Note:
В Python деление float может приводить к незначительным погрешностям
из-за специфики архитектуры процессора, поэтому применяется округление.
Warning:
Передача слишком больших чисел может замедлить вычисления
на некоторых старых платформах.
Examples:
>>> calc = Calculator(precision=2)
>>> calc.divide(10, 3)
3.33
>>> calc.divide(5, 2)
2.5
Todo:
* Добавить поддержку комплексных чисел в следующей версии.
* Интегрировать логирование ошибок деления на ноль.
"""
if divisor == 0:
raise ZeroDivisionError("Деление на ноль строго запрещено.")
return round(dividend / divisor, self.precision)2. Комплексный пример: Оформление класса
Давайте разберем класс, в котором задействованы все виды видимости атрибутов и методов, а также расширенные секции документации.
python
class SmartTermostat:
"""Управляющий модуль системы климат-контроля умного дома.
Этот класс инкапсулирует логику работы с датчиками температуры,
проверку пороговых значений и безопасное переключение режимов.
Attributes:
room_name (str): Публичное имя комнаты.
is_on (bool): Флаг активности термостата.
_target_temp (float): Защищенный (protected) целевой показатель температуры.
__hardware_id (str): Приватный (private) серийный номер устройства.
"""
def __init__(self, room_name: str, target_temp: float = 22.0) -> None:
"""Инициализирует термостат для конкретной комнаты.
Args:
room_name (str): Название помещения (например, 'Гостиная').
target_temp (float): Желаемая температура по умолчанию.
"""
self.room_name: str = room_name
self.is_on: bool = False
self._target_temp: float = target_temp
self.__hardware_id: str = "HW-9982X-BASE"
def set_temperature(self, temperature: float) -> bool:
"""Публичный метод: Безопасно изменяет целевую температуру.
Используется внешними контроллерами или интерфейсом пользователя.
Args:
temperature (float): Новое значение в градусах Цельсия.
Returns:
bool: True, если температура успешно изменена, иначе False.
Raises:
ValueError: Если температура выходит за рабочий диапазон (от 15 до 30 градусов).
Note:
Изменение температуры не сработает, если термостат выключен (`is_on = False`).
Examples:
>>> term = SmartTermostat("Спальня", target_temp=21.0)
>>> term.is_on = True
>>> term.set_temperature(24.5)
True
>>> term.set_temperature(45.0)
Traceback (most recent call last):
...
ValueError: Температура 45.0 выходит за рамки лимитов (15-30°C).
"""
if not self.is_on:
return False
if not (15.0 <= temperature <= 30.0):
raise ValueError(f"Температура {temperature} выходит за рамки лимитов (15-30°C).")
self._target_temp = temperature
self._log_change(f"Установлена температура: {temperature}")
return True
def _log_change(self, message: str) -> None:
"""Защищенный метод: Записывает изменения состояния в логи.
Предназначен для внутреннего использования и переопределения в подклассах.
Args:
message (str): Текст сообщения для лога.
"""
print(f"[LOG] [{self.room_name}] {message}")
def __generate_signature(self) -> str:
"""Приватный метод: Создает зашифрованную подпись устройства.
Используется строго внутри этого класса для синхронизации с сервером.
Returns:
str: Уникальный хэш устройства.
"""
return f"encrypted_{self.__hardware_id}"Свойства и уровни доступа
- Публичные и защищенные (
_) атрибуты выносятся в общую секциюAttributes:класса. Приватные (__) атрибуты чаще всего документируют там же, если они критически важны для понимания работы наследников, либо опускают (так как они скрыты внутри класса). - Методы документируются индивидуально. Полнота секций для защищенных и приватных методов определяется тем, насколько сложная у них внутренняя логика. Описание аргументов и возвращаемых типов строго обязательно для всех.
Пример: класс ParcelBox
Hero-класс модуля, оформленный в Google Style:
python
class ParcelBox:
"""Класс, представляющий почтовую коробку для отправки посылок.
Хранит размеры коробки и вес посылки, защищает значения
от некорректных изменений и предоставляет доступ к вычисленному объёму.
Attributes:
length (float): Длина коробки в сантиметрах.
width (float): Ширина коробки в сантиметрах.
height (float): Высота коробки в сантиметрах.
weight (float): Вес посылки в граммах.
"""
def __init__(self, length: float, width: float, height: float, weight: float = 0.0) -> None:
"""Инициализирует коробку.
Args:
length (float): Длина в сантиметрах.
width (float): Ширина в сантиметрах.
height (float): Высота в сантиметрах.
weight (float): Вес посылки в граммах.
Raises:
ValueError: Если любое измерение или вес отрицательно.
"""
for name, value in (('length', length), ('width', width), ('height', height), ('weight', weight)):
if value < 0:
raise ValueError(f'Параметр {name} не может быть отрицательным: {value}')
self.length: float = length
self.width: float = width
self.height: float = height
self.weight: float = weight
def get_volume(self) -> float:
"""Возвращает объём коробки в кубических сантиметрах.
Returns:
float: Объём коробки (length * width * height).
"""
return self.length * self.width * self.height
box = ParcelBox(10.0, 5.0, 2.0, weight=250.0)
print(box.get_volume()) # 100.0
# box = ParcelBox(-1, 5, 2) # ValueErrorОписание кода:
Attributes:— публичные атрибуты перечислены в docstring класса: тип и назначение в одном месте.Args:— аргументы__init__описаны с типами в скобках.Raises:— явно указано, когда поднимаетсяValueError.Returns:— уget_volumeописано возвращаемое значение и единицы измерения.- Аннотации
: float,-> None,-> floatуточняют типы и проверяются статическими анализаторами.
3. Интерактивные примеры: Модуль doctest
Обратите внимание на секцию Examples: в методе set_temperature. Строки, начинающиеся с >>>, имитируют консоль Python.
Вы можете автоматически тестировать эти примеры прямо во время разработки, чтобы документация всегда оставалась актуальной. Добавьте этот код внизу вашего файла:
python
if __name__ == "__main__":
import doctest
doctest.testmod(verbose=True)Тестирование исключений в Doctest
При написании примера, который должен выдать ошибку (как в примере выше с ValueError), используйте многоточие ... вместо вывода всего длинного стека вызовов (Traceback). doctest проверяет только первую строку ошибки и последнюю.
4. Документирование свойств с декоратором @property
Использование декоратора @property — стандартный способ реализации геттеров и сеттеров в Python. При работе с ними важно соблюдать два ключевых правила документирования:
- Где писать основную документацию: Вся подробная информация (описание, типы данных, секции
Raises:иExamples:) пишется внутри геттера (метода, над которым стоит просто@property). - Нужно ли документировать сеттер: Сеттер (
@property_name.setter) обычно не требует отдельной строки документации, если его поведение очевидно и совпадает с геттером. Документировать сеттер нужно только в том случае, если он выполняет сложную валидацию или выбрасывает специфические исключения, которые не упомянуты в геттере.
Пример документирования свойств
Рассмотрим класс SmartWindow, управляющий процентом открытия автоматического окна:
python
class SmartWindow:
"""Управление автоматическим окном умного дома.
Attributes:
room (str): Название комнаты.
"""
def __init__(self, room: str) -> None:
self.room: str = room
self._open_percentage: float = 0.0 # Защищенный атрибут
@property
def open_percentage(self) -> float:
"""float: Процент открытия окна (от 0.0 до 100.0).
Эта строка документации описывает само свойство. Обратите внимание,
что в начале строки принято указывать тип данных свойства.
Raises:
ValueError: Если при установке значения передан процент вне диапазона.
Examples:
>>> window = SmartWindow("Кухня")
>>> window.open_percentage
0.0
>>> window.open_percentage = 50.5
>>> window.open_percentage
50.5
"""
return self._open_percentage
@open_percentage.setter
def open_percentage(self, value: float) -> None:
# Отдельный docstring здесь не нужен, так как вся логика описана в геттере.
# Но если логика сеттера сложная, здесь документируют только специфику валидации.
if not (0.0 <= value <= 100.0):
raise ValueError("Процент открытия должен быть в диапазоне от 0.0 до 100.0")
self._open_percentage = valueСвойства в блоке Attributes: класса
Если вы подробно задокументировали свойство через @property, дублировать его в секции Attributes: в описании самого класса не нужно. Автоматические генераторы документации (например, Sphinx) сами найдут декоратор @property и вынесут его в правильный раздел на веб-странице.
Проверьте себя
Что такое docstring в Python?
Почему в уроке выбран именно Google Style?
Какая секция Google Style описывает атрибуты класса?
Как модуль `doctest` проверяет документацию?
Что писать в doctest-примере, который должен выбросить ошибку?
Где пишется основная документация свойства `@property`?
Упражнения
Выполните задания ниже, чтобы закрепить материал. Ссылки на решения вы найдете в конце блока.
Упражнение 1: Документирование класса "Банковский Аккаунт"
Создайте класс BankAccount со следующей структурой и полностью задокументируйте его в Google Style:
- Атрибуты:
owner(str, публичный)_balance(float, защищенный)__pin_code(int, приватный)
- Методы:
deposit(amount: float) -> None(публичный) — увеличивает баланс. ВыбрасываетValueError, если сумма отрицательная._validate_transaction(amount: float) -> bool(защищенный) — проверяет лимиты.
Обязательное условие
Класс должен содержать секции Attributes:, Args:, Raises: и Note: (объясните в примечании, почему баланс защищен от прямого изменения).
Упражнение 2: Написание "Живой" документации (Doctest)
Возьмите класс Calculator или любую простую функцию (например, вычисление факториала) и напишите для нее метод multiply(a, b).
- Добавьте секцию
Examples:с двумя успешными тестами. - Подключите модуль
doctestи запустите скрипт через терминал:python имя_файла.py. - Убедитесь, что тесты проходят успешно (
Test passed).
Упражнение 3: Документирование свойств (@property) и валидации
Создайте класс Product, представляющий товар в интернет-магазине. Задокументируйте его строго по стандартам Google Style.
- Внутреннее состояние:
_price(float, защищенный атрибут) — базовая цена товара.
- Свойства (
@property):price— геттер возвращает текущую цену. Добавьте подробное описание свойства, указав тип данных (float:) на первой строке docstring.- Сеттер
priceдолжен проверять, что устанавливаемая цена — положительное число (строго больше нуля). Если условие нарушено, выбрасываетсяValueError.
- Примеры кода (
Examples:):- Внутри геттера напишите интерактивный пример использования: создание товара с ценой
100.0, успешное изменение цены на120.0и попытку установить цену-50.0, которая должна приводить к ошибкеValueError.
- Внутри геттера напишите интерактивный пример использования: создание товара с ценой
Подсказка по оформлению
Помните, что подробное описание логики валидации и возможных ошибок пишется внутри геттера. Сеттер оставляйте без собственного docstring, так как вся информация уже содержится выше.
Упражнение 4: Комплексный финал — Класс "Умная Батарея"
Это продвинутое упражнение объединяет все изученные элементы: уровни доступа, секции Raises, Note, Warning и тестирование doctest.
Создайте класс SmartBattery, моделирующий аккумулятор мобильного устройства:
- Атрибуты класса:
capacity(int, публичный) — общая емкость в мАч._charge_level(int, защищенный) — текущий заряд в процентах (от 0 до 100).__cycle_count(int, приватный) — количество циклов перезарядки.
- Методы:
charge(amount: int) -> None(публичный) — увеличивает_charge_level.- Если уровень достигает 100,
__cycle_countувеличивается на 1. - Если передано отрицательное число, выбрасывает
ValueError.
- Если уровень достигает 100,
- Требования к документации:
- Задокументируйте класс полностью. В секцию
Attributes:вынесите публичный и защищенный атрибуты. - Для метода
chargeдобавьте секциюWarning:, предупреждающую, что частая зарядка до 100% ускоряет деградацию литий-ионного аккумулятора. - Добавьте секцию
Examples:, в которой сымитируйте зарядку аккумулятора со 95% до 100% и проверьте, как это влияет на логику.
- Задокументируйте класс полностью. В секцию
Шаблоны для самопроверки и решения (Ответы)
Вы можете развернуть блоки ниже, чтобы сверить свой код с эталонным решением.
Посмотреть решение Упражнения 3 (Product)
python
class Product:
"""Товарная единица торговой площадки."""
def __init__(self, initial_price: float) -> None:
if initial_price <= 0:
raise ValueError("Начальная цена должна быть больше нуля.")
self._price: float = initial_price
@property
def price(self) -> float:
"""float: Актуальная стоимость товара в валюте магазина.
Raises:
ValueError: Если совершена попытка установить цену, равную
или меньшую нуля.
Examples:
>>> prod = Product(100.0)
>>> prod.price
100.0
>>> prod.price = 120.5
>>> prod.price
120.5
>>> prod.price = -5.0
Traceback (most recent call last):
...
ValueError: Цена товара должна быть строго положительной.
"""
return self._price
@price.setter
def price(self, value: float) -> None:
if value <= 0:
raise ValueError("Цена товара должна быть строго положительной.")
self._price = valueПосмотреть решение Упражнения 4 (SmartBattery)
python
class SmartBattery:
"""Модель аккумуляторной батареи с контролем износа.
Attributes:
capacity (int): Номинальная емкость батареи в мАч.
_charge_level (int): Текущий уровень заряда в процентах (0-100).
"""
def __init__(self, capacity: int) -> None:
self.capacity: int = capacity
self._charge_level: int = 50
self.__cycle_count: int = 0
def charge(self, amount: int) -> None:
"""Заряжает аккумулятор на указанное количество процентов.
Args:
amount (int): Количество процентов для добавления.
Raises:
ValueError: Если передано отрицательное значение `amount`.
Warning:
Постоянное поддержание заряда на уровне 100% или глубокий разряд
до 0% ускоряют химическую деградацию ячеек.
Examples:
>>> battery = SmartBattery(4500)
>>> battery._charge_level = 95
>>> battery.charge(5)
>>> battery._charge_level
100
>>> battery.charge(-10)
Traceback (most recent call last):
...
ValueError: Значение зарядки не может быть отрицательным.
"""
if amount < 0:
raise ValueError("Значение зарядки не может быть отрицательным.")
self._charge_level = min(100, self._charge_level + amount)
if self._charge_level == 100:
self.__cycle_count += 1Чек-лист самопроверки
Перед отправкой кода на ревью проверьте себя:
- [ ] Описание класса начинается с заглавной буквы и точки на первой строке.
- [ ] Все публичные и защищенные атрибуты перечислены в
Attributes:класса. - [ ] Названия секций (
Args:,Returns:,Raises:) написаны с большой буквы и заканчиваются двоеточием. - [ ] Аргументы в секции
Args:содержат указание типа в скобках, напримерamount (float): ... - [ ] Интерактивные примеры используют префикс
>>>. Перед тем как завершить работу над этим модулем, убедитесь, что вы: - [ ] Понимаете разницу между описанием атрибутов в теле класса и описанием
@property. - [ ] Знаете, как запустить проверку
doctestчерез терминал вашего окружения. - [ ] Оформляете многострочные блоки исключений
Traceback (most recent call last):с использованием символов...для сокращения вывода.