Автор оригинала: Frank Hofmann.

Python Docstrings

Как уже указывалось в предыдущей статье под названием Commenting Python Code вы узнали, что документация является важным и непрерывным шагом в процессе разработки программного обеспечения. В упомянутой выше статье кратко представлена концепция docstrings , которая представляет собой способ создания документации для вашего кода Python изнутри кода. Эта документация в коде работает для модулей, классов, методов и функций, и это предпочтительный способ документирования всего кода Python.

Это гораздо больше, и именно поэтому мы более подробно рассмотрим эту тему в этой статье. Мы рассмотрим соглашения о том, как правильно писать строки документов, а также различные форматы строк документов, которые используются на практике, с последующим доступом к строке документа из вашего скрипта Python. И, наконец, мы представим вам ряд инструментов для использования и оценки docstrings.

Погружение в Докстринги

Термин docstring является аббревиатурой для documentation string и описывает ваш исходный код – то есть то , что делает ваша функция, модуль или класс. Он добавляется как обычный комментарий прямо под заголовком функции, модуля, класса или метода.

Типичный пример выглядит следующим образом и взят из класса Python для работы с измерительным устройством, таким как мобильный датчик для измерения температуры, влажности и скорости ветра.

Листинг 1: Код Python с однострочной строкой docstring

class Device:
    def __init__(self, temp=0.0):
        "Initialize the Device object with the given temperature value."
        
        self.set_temperature(temp)
        return

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

Однострочная строка документа

Из-за простоты docstring, используемый в Листинге 1 , поставляется в виде однострочного комментария. Имейте в виду, что текст строки документа следует начинать с заглавной буквы, а заканчивать точкой. Исходя из того, что код обычно читается чаще, чем пишется, рекомендуется описывать то, что делает документированная структура, как своего рода команду, а не как это делается. Упоминание того, какое значение возвращается вызывающему объекту, помогает понять результат работы функции или метода.

Возможно, вы заметили, что строка документа метода из листинга 1 заключена в одинарные двойные кавычки. Ну, пока и начальные, и конечные кавычки похожи, Python вполне терпим, и вам также разрешено использовать три одинарные кавычки, а также три двойные кавычки:

    def get_temperature(self):
        '''Return the stored temperature value as a float value.'''

        return self.temperature
    
    def set_temperature(self, temp):
        """Set the temperature value."""

        self.temperature = float(temp)
        return

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

Многострочные док-строки

Кроме того, строка документа также может быть записана в виде многострочного комментария. При использовании многострочных комментариев меняются две вещи – инкапсуляция строки документа должна быть написана в тройных одинарных или двойных кавычках, а сама структура строки документа имеет более глубокий смысл, который присваивается всему тексту.

Первая строка строки документа интерпретируется как абстрактное или краткое описание и рекомендуется писать так же, как и однострочная строка документа. Следующая пустая строка интерпретируется как разделитель между абстрактным и полным описанием ниже. Листинг 2 расширяет Листинг 1 и не использует конкретный формат для описания, как указано ниже.

Листинг 2: Многострочная строка документа

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.
    """

    self.temperature = float(temp)
    return

Настоятельно рекомендуется следовать структуре docstring для многострочных строк, поскольку автоматизированные инструменты индексирования оценивают эти тексты и поэтому полагаются на соответствие порядку блоков.

Форматы Docstring

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

• Реструктурированный текст (reST)/|/Sphinx : Это официальный стандарт документации Python. Он использует синтаксис облегченного языка разметки reStructuredText (reST), который аналогичен по использованию Markdown . Google Docstrings
• : Стиль Google docstring NumPy/
• SciPy Docstrings: Комбинация реструктурированного текста (reST) и Google Docstrings. Пригодный и для Сфинкса, и довольно многословный.

В листинге 3 показано, как написать строку документа с помощью reST. Ключевые слова, которые вы можете использовать, следующие:

• param и type : Параметр и его переменный тип
• return и type : Укажите как возвращаемое значение, так и тип функции или метода
• .... см. Также:: : Дальнейшее чтение
• .. примечания:: : Добавить заметку
• .. warning:: : Добавить предупреждение

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

Листинг 3: Многострочная строка документа с данными reST

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    :param temp: the temperature value
    :type temp: float
    :return: no value
    :rtype: none
    """

    self.temperature = float(temp)
    return

Чтобы понять, что такое docstrings Google, вы можете взглянуть на Листинг 4 . Формат менее плотный и использует больше горизонтального пространства.

Листинг 4: Многострочная строка документа (формат Google)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Args:
        temp (float): the temperature value

    Returns:
        no value
    """

    self.temperature = float(temp)
    return

Наконец, Листинг 5 показывает тот же метод в формате NumPy docstring. Он использует больше вертикального пространства и выглядит легче читаемым, чем исходный формат.

Листинг 5: Многострочная строка документа (формат NumPy)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Parameters
    ----------
    temp : float
        the temperature value

    Returns
    -------
    no value
    """

    self.temperature = float(temp)
    return

Доступ к Строкам документов

В интерактивной справочной системе Python строка docstring доступна через атрибут __doc__ . Листинг 6 показывает, как использовать код для доступа к строке документации, которая в нашем примере основана на Листинге 1 .

Листинг 6: Доступ к значению docstring

>>> def set_temperature (self, temp):
...     """Set the temperature value."""
...     temperature = float(temp)
...     return
... 
>>> print(set_temperature.__doc__)
Set the temperature value.

Инструменты для использования строк документов

Существует ряд инструментов, которые автоматически генерируют документацию из строк документов, таких как Sphinx, Epydoc , Doxygen , PyDoc , pydoc и расширение autodoc для Sphinx. Большинство из них генерируют HTML-документы для локального использования.

Pydoc является частью дистрибутива Python и получает информацию о модуле для консоли, веб-браузера или в виде HTML-документа. Внутри оболочки Python используйте функцию help () , чтобы узнать больше о модуле, функции, классе или методе. На рис. 1 показана строка документа из Листинга 1 через справочную систему Python .

Рис. 1: Извлеченная строка документа

Чтобы увидеть встроенную документацию для всех модулей Python, установленных локально, вы можете запустить pydoc как локальный веб-сервер. С помощью параметра -p , за которым следует номер порта, запускается небольшой веб-сервер, доступный с помощью данного порта. Листинг 7 запускает сервер pydoc через порт 1234, а Рисунок 2 показывает информацию, извлеченную и доступную pydoc.

Листинг 7: Запуск pydoc в качестве веб-сервера

$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
...

Рис. 2: Извлеченная строка документа на локальном веб-сервере

Вывод

Следование рекомендациям по документации поможет вам и другим понять исходный код сегодня и позже. Строки документов используются не только для этого, например, для создания руководств. Эта идея позволяет реализовывать проекты большего масштаба.