документирование кода на python
Документирование кода в Python
Д окументирование кода – неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speak(): «»»Это docstring класса Speak.»»» 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 существует встроенный функционал добавления документации к коду. Для этого нужно:
Документирование кода в 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).
Docstrings: документирование кода в Python
Хочешь знать больше о Python?
Подпишись на наш канал о Python в Telegram!
В статье, опубликованной на сайте pythonist.ru, рассмотрены строки документации в Python. Давайте разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
Примечание. Мы используем тройные кавычки для многострочных строк.
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
Принимает число n, возвращает квадрат числа n
Теперь давайте посмотрим на строки документации для встроенной функции print() :
Пример 3: строки документации для встроенной функции print().
Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.
Однострочные строки документации в Python
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
Строки документации пишутся в начале файла Python.
Пример 4: строки документации модуля Python.
2. Строки документации для функций Python
Пример 5: строки документации для функций Python.
3. Строки документации для классов Python
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
Мы можем использовать следующий код для доступа только к строкам документации класса Person :
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Учимся писать строки документации в 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
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
PEP 257 на русском. (Соглашение о Docstrings)
Аннотация
Данный PEP документирует семантику и соглашения, связанные с использованием Python docstrings.
Обоснование
«Общепринятые соглашения обеспечивают ясность, логичность, удобство сопровождения и воспитывают хорошие программистские привычки. Но они не заставляет вас действовать против своей воли. Это Python!»
Тим Питерс на comp.lang.python, 2001-06-16
Если вы избегаете общепринятых соглашений, в худшем случае на вас посмотрят искоса. Но существуют некоторые приложения (Например, системы документирования, подобные Docutils), которые позволят вам добиться более качественного результата, если вы знаете о договорённостях и будете им следовать.
Спецификация
Что такое Docstring?
Документационная строка — это строковый литерал, являющийся первой инструкцией в определении модуля, функции, класса или метода. Такая строка становится доступна при обращении с специальному атрибуту __doc__ этого объекта.
Все библиотеки, а также функции и классы, экспортируемые ими, должны иметь docstring. Публичные методы (включая конструктор __ init__) также должны иметь документацию. Сам же пакет может быть задокументирован внутри файла __init__.py, находящегося в соответствующей ему директории.
Строковые литералы, встречающиеся в других местах кода, также могут играть роль документации. Они не распознаются Python компилятором байт-кода и недоступны в качестве атрибутов объекта во время выполнения программы (т. е. у них отсутствует информация в __ doc__ ). Но существуют два дополнительных типа документационных строк, которые извлекаются с помощью других программных средств:
Для согласованности всегда используйте «»»тройные двойные кавычки»»» вокруг документационной строки. Если вы используете символы обратной косой черты («\»), то воспользуйтесь r»»»сырая строка с двойными кавычками»»» в ваших документациях. Для docstring, содержащих Unicode символы, используйте u»»»Юникод строка в тройных двойных кавычках»»». [прим. unicode строки потеряли смысл в python 3.x]
Существует две формы docstring: однострочные и многострочный.
Однострочные документационные строки
Однострочные строки используются для очевидных случаев и они должны действительно находится на одной строке. Например:
Значение фразы «командный тон» в английском языке можно пояснить на примере словосочетаний «Return pathname» и «Returns pathname». PEP-257 просит придерживаться первого стиля, потому что он более строгий.
Этот вид документаций подходит только для функций, написанных на языке C (таких как встроенные), где самоанализ невозможен. Также стоит упомянуть о природе возвращаемого значения. Предпочтительной формой для такой документационной строки будет что-то вроде:
(И конечно-же, «Сделай X» дожно быть заменено полезным описанием!)
Да, я только что писал выше: «Документация не является простым описанием», но в оригинале Гвидо и Дэвид действительно используют одинаковое слово «description» в этих двух местах. Думаю, что не стоит слишком придираться к этому, ведь посыл и так ясен.
Многострочные документационные строки
Многострочные документации состоят из сводной строки (summary line) имеющей такую же структуру, как и однострочный docstring, после которой следует пустая линия, а затем более сложное описание. «Summary line» может быть использована средствами автоматического документирования; поэтому так важно располагать её на одной строке и после делать пропуск в одну линию. Сводная строка пишется сразу после открывающихся кавычек, но допускается сделать перенос и начать со следующей строки. [прим. после этого предложения я был счастлив, ведь находились люди, которые упорно пытались мне доказать, что делать перенос ни в коем случае нельзя 🙂 ] При этом, весь docstring должен иметь такой же отступ, как и открывающие кавычки первой строки (см. пример ниже).
Оставляйте пустую строку после всех документаций (однострочных или многострочных), которые используются в классе; вообще говоря, методы класса должны быть отделены друг от друга одной пустой линией, поэтому документационная строка класса также должна быть отделена этим способом от первого метода.
Документация скрипта (автономной программы) представляет из себя сообщение «о правильном использовании» и возможно будет напечатано, когда скрипт вызовется с неверными или отсутствующими аргументами (или же с опцией «-h», для получения «help»). Такая документационная строка должна описывать функционал и синтаксис параметров скрипта, а также переменные среды и используемые файлы. Данное сообщение может оказаться довольно сложным (мануал длиной в несколько полных экранов), но при этом оно должно быть удобным для новых пользователей, чтобы они смогли использовать команду правильно. Также мануал должен давать чёткое описание всех параметров и аргументов для более опытных пользователей.
Документация модуля должна обычно содержать список классов, исключений и функций (и любых других важных объектов), которые экспортируются при помощи библиотеки, а также однострочное пояснение для каждого из них. (Это резюме, как правило, даёт меньше деталей, чем summary line в docstring самого объекта). В документации пакета (т. е. docstring модуля в __init__.py ) следует также описать и перечислить модули и подпакеты, экспортируемые главным.
Документация функции или метода должна описывать их поведение, аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда они могут быть вызваны (если это вообще предусмотрено). Также необходимо указать необязательные аргументы. Должно быть уточнено, являются ли ключевые аргументы частью интерфейса.
Документация класса должна обобщать его поведение и перечислять открытые методы, а также переменные экземпляра. Если класс будет иметь подклассы с дополнительный интерфейсом, то этот интерфейс должен быть указан отдельно (но всё также в этой документации). Конструктор класса должен иметь свою отдельную документационную строку для метода __init__. Независимые (индивидуальные) методы должны иметь собственную документацию.
Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия. Используйте глагол «override» («переопределить»), чтобы указать факт подмены метода и что вследствие этого метод суперкласса вызываться не будет. Используйте глагол «extends» («расширяет»), если метод подкласса вызывает метод суперкласса (в дополнение к его собственному поведению).
Не используйте соглашение Emacs об упоминании аргументов функций или методов в верхнем регистре. Python чувствителен к регистру, а имена аргументов могут порой использоваться при их передаче по ключам, поэтому документация должна содержать реальные имена переменных. Лучше всего перечислять каждый аргумент в отдельной строке. Например:
Если весь docstring не помещается в строку, вы можете вынести закрывающие кавычки на отдельную линию. Таким образом, можно будет использовать Emacs команду: fill-paragraph
Обработка Docstring
Инструменты обработки документационных строк должны удалять одинаковое количество отступов, равное минимальному отступу всех не пустых строк, начиная со второй. Любые отступы в первой строке документации несущественны и будут удалены. Относительный отступ более поздних строк в строке документа сохраняется. Пустые строки должны быть удалены из начала и конца строки документа.
Поскольку код гораздо точнее слов, здесь приведена реализация алгоритма:
По сравнению с оригинальным кодом, в python3 атрибут sys.maxint был переименован в sys.maxsize, поэтому в коде это сразу исправлено.
Документация в следующем примере содержит два символа новой строки и поэтому имеет длину равную трём. Первая и последняя строки пусты:
Таким образом, после обработки следующие документационные строки будут эквивалентны: