Документирование кода в Python. PEP 257
PEP 257 описывает соглашения, связанные со строками документации python, рассказывает о том, как нужно документировать python код.
Что такое строки документации?
Все модули должны, как правило, иметь строки документации, и все функции и классы, экспортируемые модулем также должны иметь строки документации. Публичные методы (в том числе __init__) также должны иметь строки документации. Пакет модулей может быть документирован в __init__.py.
Для согласованности, всегда используйте «»»triple double quotes»»» для строк документации. Используйте r»»»raw triple double quotes»»», если вы будете использовать обратную косую черту в строке документации.
Существует две формы строк документации: однострочная и многострочная.
Однострочные строки документации
Однострочники предназначены для действительно очевидных случаев. Они должны умещаться на одной строке. Например:
Используйте тройные кавычки, даже если документация умещается на одной строке. Потом будет проще её дополнить.
Закрывающие кавычки на той же строке. Это смотрится лучше.
Нет пустых строк перед или после документации.
Однострочная строка документации не должна быть «подписью» параметров функции / метода (которые могут быть получены с помощью интроспекции). Не делайте:
Этот тип строк документации подходит только для C функций (таких, как встроенные модули), где интроспекция не представляется возможной. Тем не менее, возвращаемое значение не может быть определено путем интроспекции. Предпочтительный вариант для такой строки документации будет что-то вроде:
(Конечно, «Do X» следует заменить полезным описанием!)
Многострочные строки документации
Многострочные строки документации состоят из однострочной строки документации с последующей пустой строкой, а затем более подробным описанием. Первая строка может быть использована автоматическими средствами индексации, поэтому важно, чтобы она находилась на одной строке и была отделена от остальной документации пустой строкой. Первая строка может быть на той же строке, где и открывающие кавычки, или на следующей строке. Вся документация должна иметь такой же отступ, как кавычки на первой строке (см. пример ниже).
Строки документации скрипта (самостоятельной программы) должны быть доступны в качестве «сообщения по использованию», напечатанной, когда программа вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией «-h», для помощи). Такая строка документации должна документировать функции программы и синтаксис командной строки, переменные окружения и файлы. Сообщение по использованию может быть довольно сложным (несколько экранов) и должно быть достаточным для нового пользователя для использования программы должным образом, а также полный справочник со всеми вариантами и аргументами для искушенного пользователя.
Строки документации модуля должны, как правило, перечислять классы, исключения, функции (и любые другие объекты), которые экспортируются модулем, с краткими пояснениями (в одну строчку) каждого из них. (Эти строки, как правило, дают меньше деталей, чем первая строка документации к объекту). Строки документации пакета модулей (т.е. строка документации в __init__.py) также должны включать модули и подпакеты.
Строки документации функции или метода должны обобщить его поведение и документировать свои аргументы, возвращаемые значения, побочные эффекты, исключения, дополнительные аргументы, именованные аргументы, и ограничения на вызов функции.
Строки документации класса обобщают его поведение и перечисляют открытые методы и переменные экземпляра. Если класс предназначен для подклассов, и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в документации метода __init__. Отдельные методы должны иметь свои строки документации.
И, напоследок, пример:
А ещё больше примеров можно посмотреть в стандартной библиотеке python (например, в папке Lib вашего интерпретатора python).
Учимся писать строки документации в Python
May 28, 2020 · 4 min read
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
М ы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.
Лучшие практики
Однострочные докстринги
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
Синтаксис Sphinx
Макет Sphynx
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
Учимся писать строки документации в Python
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.
Лучшие практики
Однострочные докстринги
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
Синтаксис Sphinx
Макет Sphynx
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
Docstrings: документирование кода в Python
В этой статье мы рассмотрим строки документации в Python, а также разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
Принимает число n, возвращает квадрат числа n
Теперь давайте посмотрим на строки документации для встроенной функции print() :
Пример 3: строки документации для встроенной функции print().
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.
Однострочные строки документации в Python
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
Строки документации пишутся в начале файла Python.
Пример 4: строки документации модуля Python.
Create portable serialized representations of Python objects.
See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.
2. Строки документации для функций Python
Пример 5: строки документации для функций Python.
Возвращает сумму двух десятичных чисел в двоичном формате.
a (int): первое десятичное целое число
b (int): второе десятичное целое число
binary_sum (str): двоичная строка суммы a и b
3. Строки документации для классов Python
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
Мы можем использовать следующий код для доступа только к строкам документации класса Person :
Класс для представления человека.
Печатает имя и возраст человека.
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
Результат:
Help on class Person in module __main__:
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Документирование кода в Python
Д окументирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speaker: «»»Это docstring класса Speaker»»» def say_something(self): «»»Это docstring метода»»» print(«something»)
После строки документации нужно оставлять пустую строку
Документация для класса может содержать следующую информацию:
Для методов класса документация может содержать:
Ниже — пример с более подробной документацией класса:
Документация для пакетов
Документация пакета размещается в файле __init__.py в верхней части файла (начиная с 1-й строки). В ней может быть указано:
Документация для модулей
Документация модулей аналогична документации классов. Вместо класса и методов в данном случае документируется модуль со всеми его функциями. Размещается в верхней части файла (начиная с 1-й строки).
Форматы Docstring
Строки документации могут иметь различное форматирование. В примере выше мы использовали стиль NumPy. Существуют и другие форматы:
Вывод документации на экран — help() и __doc__
Строки документации доступны:
Выведем документацию с помощью функции help()
Также можно выводить документацию отдельного объекта:
>>> import my_module >>> my_module.__doc__ >>> my_module.my_function.__doc__ >>> my_module.MyClass.__doc__ >>> my_module.MyClass.my_method.__doc__
Pydoc
Для более удобной работы с документацией, в Python существует встроенная библиотека pydoc.
Pydoc автоматически генерирует документацию из Python модулей. Информацию по доступным командам модуля pydoc можно получить набрав в терминале:
Разберем подробнее, что умеет pydoc.
Вывод текста документации
pydoc — покажет текст документации указанного модуля, пакета, функции, класса и т.д. Если содержит «\», Python будет искать документацию по указанному пути.
Для примера, посмотрим документацию встроенного модуля math:
В консоль выведется название модуля, его описание и описание всех функций в модуле.
Поиск по документации
Допустим, нам нужно распаковать gzip файл. Поищем слово » gzip «:
По описанию, данный модуль решит нашу задачу.
HTTP сервер с документацией
Для удобства просмотра документации, pydoc позволяет одной командой создать HTTP-сервер:
Теперь можно перейти в браузер и зайти на http://localhost:331/
Для остановки сервера введите » q » и нажмите » Enter «:
server> q Server stopped
Запись документации в файл
Автодокументирование кода
Pyment работает следующим образом:
Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.
pip install pyment
Для большинства IDE также существуют плагины, помогающие документировать код:
В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно: