Документирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Docstring — это строковый литерал, который расположен сразу за объявлением модуля, функции, класса или метода. О том, какие существуют соглашения в документировании Python кода описано в документации PEP257 .
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speaker: «»»Это docstring класса Speaker»»» def say_something(self): «»»Это docstring метода»»» print(«something»)
После строки документации нужно оставлять пустую строку
Python для начинающих: работа с документацией и справочниками.
Документация для класса может содержать следующую информацию:
- краткое описание класса (+ его поведение);
- описание атрибутов класса;
- описание публичных методов;
- все, что связано с интерфейсом для подклассов.
Для методов класса документация может содержать:
- краткое описание метода (+ его поведение);
- описание аргументов метода;
- побочные эффекты (если таковые возникают при выполнении метода);
- исключения.
Ниже — пример с более подробной документацией класса:
class TextSplitter: «»»Класс TextSplitter используется для разбивки текста на слова Основное применение — парсинг логов на отдельные элементы по указанному разделителю. Note: Возможны проблемы с кодировкой в Windows Attributes ———- file_path : str полный путь до текстового файла lines : list список строк исходного файла Methods ——- load() Читает файл и сохраняет его в виде списка строк в lines get_splitted(split_symbol=» «) Разделяет строки списка по указанному разделителю и возвращает результат в виде списка «»» def __init__(self, file_path: str): self.file_path = file_path.strip() self.lines = [] def load(self) -> None: «»»Метод для загрузки файла в список строк lines Raises —— Exception Если файл пустой вызовется исключение «»» with open(self.file_path, encoding=»utf-8″) as f: for line in f: self.lines.append(line.rstrip(‘n’)) if len(self.lines) == 0: raise Exception(f»file is empty») def get_splitted(self, split_symbol: str = » «) -> list: «»»Разбивает текстовые строки lines, преобразуя строку в список слов по разделителю Если аргумент split_symbol не задан, в качестве разделителя используется пробел Parameters ———- split_symbol : str, optional разделитель «»» split_list = [] for str_line in self.lines: split_list.append(str_line.split(split_symbol)) return split_list
Читай документацию! | Вы сломали программирование
Документация для пакетов
Документация пакета размещается в файле __init__.py в верхней части файла (начиная с 1-й строки). В ней может быть указано:
- описание пакета;
- список модулей и пакетов, экспортируемых этим модулем;
- автор;
- контактные данные;
- лицензия.
Документация для модулей
Документация модулей аналогична документации классов. Вместо класса и методов в данном случае документируется модуль со всеми его функциями. Размещается в верхней части файла (начиная с 1-й строки).
Форматы Docstring
Строки документации могут иметь различное форматирование. В примере выше мы использовали стиль NumPy. Существуют и другие форматы:
- Google styleguide ->Comments and Docstrings
- Numpydoc docstring guide
- Epydoc
- reStructuredText (reST)
Вывод документации на экран — help() и __doc__
Строки документации доступны:
- из атрибута __doc__ для любого объекта;
- с помощью встроенной функции help().
Выведем документацию с помощью функции help()
>>> import my_module >>> help(my_module) Help on module test: NAME test — Это docstring модуля, он однострочный. FILE /var/www/test.py CLASSES MyClass class MyClass | Это docstring класса. | | Methods defined here: | | my_method(self) | Это docstring метода FUNCTIONS my_function(a) Это многострочный docstring для функции my_function. В многострочном docstring первое предложение кратко описывает работу функции.
Также можно выводить документацию отдельного объекта:
>>> import my_module >>> my_module.__doc__ >>> my_module.my_function.__doc__ >>> my_module.MyClass.__doc__ >>> my_module.MyClass.my_method.__doc__
Pydoc
Для более удобной работы с документацией, в Python существует встроенная библиотека pydoc.
Теперь можно перейти в браузер и зайти на http://localhost:331/
Для остановки сервера введите » q » и нажмите » Enter «:
server> q Server stopped
Также HTTP-сервер доступен через python -m pydoc -b – эта команда создаст сервер на свободном порту, откроет браузер и перейдет на нужную страницу.
Запись документации в файл
python -m pydoc -w sqlite3 — запишем файл с документацией по модулю sqlite3 в html файл.
Автодокументирование кода
Для того чтобы облегчить написание документации и улучшить ее в целом, существуют различные Python-пакеты. Один из них — pyment .
Pyment работает следующим образом:
- Анализирует один или несколько скриптов.
- Получает существующие строки документации.
- Генерирует отформатированные строки документации со всеми параметрами, значениями по умолчанию и т.д.
- Далее вы можете применить сгенерированные строки к своим файлам.
Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.
pip install pyment
pyment myfile.py # для файла pyment -w myfile.py # для файла + запись в файл pyment my/folder/ # для всех файлов в папке
Для большинства IDE также существуют плагины, помогающие документировать код:
- AutoDocstring – для VS Code.
- AutoDocstring – для SublimeText.
- Python DocBlock Package – для Atom.
- Autodoc – для PyCharm.
В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно:
- Переместить курсор под объявление функции.
- Написать тройные кавычки «»» и нажмите » Enter» .
Источник: pythonchik.ru
Документирование кода в Python. PEP 257
Документирование кода в python — достаточно важный аспект, ведь от нее порой зависит читаемость и быстрота понимания вашего кода, как другими людьми, так и вами через полгода.
PEP 257 описывает соглашения, связанные со строками документации python, рассказывает о том, как нужно документировать python код.
Цель этого PEP — стандартизировать структуру строк документации: что они должны в себя включать, и как это написать (не касаясь вопроса синтаксиса строк документации). Этот PEP описывает соглашения, а не правила или синтаксис.
При нарушении этих соглашений, самое худшее, чего можно ожидать — некоторых неодобрительных взглядов. Но некоторые программы (например, docutils), знают о соглашениях, поэтому следование им даст вам лучшие результаты.
Что такое строки документации?
Строки документации — строковые литералы, которые являются первым оператором в модуле, функции, классе или определении метода. Такая строка документации становится специальным атрибутом __doc__ этого объекта.
Все модули должны, как правило, иметь строки документации, и все функции и классы, экспортируемые модулем также должны иметь строки документации. Публичные методы (в том числе __init__) также должны иметь строки документации. Пакет модулей может быть документирован в __init__.py.
Для согласованности, всегда используйте «»»triple double quotes»»» для строк документации. Используйте r»»»raw triple double quotes»»», если вы будете использовать обратную косую черту в строке документации.
Существует две формы строк документации: однострочная и многострочная.
Однострочные строки документации
Однострочники предназначены для действительно очевидных случаев. Они должны умещаться на одной строке. Например:
Этот тип строк документации подходит только для C функций (таких, как встроенные модули), где интроспекция не представляется возможной. Тем не менее, возвращаемое значение не может быть определено путем интроспекции. Предпочтительный вариант для такой строки документации будет что-то вроде:
(Конечно, «Do X» следует заменить полезным описанием!)
Многострочные строки документации
Многострочные строки документации состоят из однострочной строки документации с последующей пустой строкой, а затем более подробным описанием. Первая строка может быть использована автоматическими средствами индексации, поэтому важно, чтобы она находилась на одной строке и была отделена от остальной документации пустой строкой. Первая строка может быть на той же строке, где и открывающие кавычки, или на следующей строке. Вся документация должна иметь такой же отступ, как кавычки на первой строке (см. пример ниже).
Вставляйте пустую строку до и после всех строк документации (однострочных или многострочных), которые документируют класс — вообще говоря, методы класса разделены друг от друга одной пустой строкой, а строка документации должна быть смещена от первого метода пустой строкой; для симметрии, поставьте пустую строку между заголовком класса и строкой документации. Строки документации функций и методов, как правило, не имеют этого требования.
Строки документации скрипта (самостоятельной программы) должны быть доступны в качестве «сообщения по использованию», напечатанной, когда программа вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией «-h», для помощи). Такая строка документации должна документировать функции программы и синтаксис командной строки, переменные окружения и файлы. Сообщение по использованию может быть довольно сложным (несколько экранов) и должно быть достаточным для нового пользователя для использования программы должным образом, а также полный справочник со всеми вариантами и аргументами для искушенного пользователя.
Строки документации модуля должны, как правило, перечислять классы, исключения, функции (и любые другие объекты), которые экспортируются модулем, с краткими пояснениями (в одну строчку) каждого из них. (Эти строки, как правило, дают меньше деталей, чем первая строка документации к объекту). Строки документации пакета модулей (т.е. строка документации в __init__.py) также должны включать модули и подпакеты.
Строки документации функции или метода должны обобщить его поведение и документировать свои аргументы, возвращаемые значения, побочные эффекты, исключения, дополнительные аргументы, именованные аргументы, и ограничения на вызов функции.
Строки документации класса обобщают его поведение и перечисляют открытые методы и переменные экземпляра. Если класс предназначен для подклассов, и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в документации метода __init__. Отдельные методы должны иметь свои строки документации.
Если класс — подкласс другого класса, и его поведение в основном унаследовано от этого класса, строки документации должны отмечать это и обобщить различия. Используйте глагол «override», чтобы указать, что метод подкласса заменяет метод суперкласса и не вызывает его; используйте глагол «extend», чтобы указать, что метод подкласса вызывает метод суперкласса (в дополнение к собственному поведению).
И, напоследок, пример:
list»»»
Этот вид документаций подходит только для функций, написанных на языке C (таких как встроенные), где самоанализ невозможен. Также стоит упомянуть о природе возвращаемого значения. Предпочтительной формой для такой документационной строки будет что-то вроде:
def function(a, b): def function(a, b): «»»Сделай X и верни список.»»»
(И конечно-же, «Сделай X» дожно быть заменено полезным описанием!)
Примечание переводчика
Да, я только что писал выше: «Документация не является простым описанием», но в оригинале Гвидо и Дэвид действительно используют одинаковое слово «description» в этих двух местах. Думаю, что не стоит слишком придираться к этому, ведь посыл и так ясен.
Многострочные документационные строки
Многострочные документации состоят из сводной строки (summary line) имеющей такую же структуру, как и однострочный docstring, после которой следует пустая линия, а затем более сложное описание. «Summary line» может быть использована средствами автоматического документирования; поэтому так важно располагать её на одной строке и после делать пропуск в одну линию. Сводная строка пишется сразу после открывающихся кавычек, но допускается сделать перенос и начать со следующей строки. [прим. после этого предложения я был счастлив, ведь находились люди, которые упорно пытались мне доказать, что делать перенос ни в коем случае нельзя 🙂 ] При этом, весь docstring должен иметь такой же отступ, как и открывающие кавычки первой строки (см. пример ниже).
Оставляйте пустую строку после всех документаций (однострочных или многострочных), которые используются в классе; вообще говоря, методы класса должны быть отделены друг от друга одной пустой линией, поэтому документационная строка класса также должна быть отделена этим способом от первого метода.
Документация скрипта (автономной программы) представляет из себя сообщение «о правильном использовании» и возможно будет напечатано, когда скрипт вызовется с неверными или отсутствующими аргументами (или же с опцией «-h», для получения «help»). Такая документационная строка должна описывать функционал и синтаксис параметров скрипта, а также переменные среды и используемые файлы. Данное сообщение может оказаться довольно сложным (мануал длиной в несколько полных экранов), но при этом оно должно быть удобным для новых пользователей, чтобы они смогли использовать команду правильно. Также мануал должен давать чёткое описание всех параметров и аргументов для более опытных пользователей.
Документация функции или метода должна описывать их поведение, аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда они могут быть вызваны (если это вообще предусмотрено). Также необходимо указать необязательные аргументы. Должно быть уточнено, являются ли ключевые аргументы частью интерфейса.
Документация класса должна обобщать его поведение и перечислять открытые методы, а также переменные экземпляра. Если класс будет иметь подклассы с дополнительный интерфейсом, то этот интерфейс должен быть указан отдельно (но всё также в этой документации). Конструктор класса должен иметь свою отдельную документационную строку для метода __init__. Независимые (индивидуальные) методы должны иметь собственную документацию.
Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия. Используйте глагол «override» («переопределить»), чтобы указать факт подмены метода и что вследствие этого метод суперкласса вызываться не будет. Используйте глагол «extends» («расширяет»), если метод подкласса вызывает метод суперкласса (в дополнение к его собственному поведению).
Не используйте соглашение Emacs об упоминании аргументов функций или методов в верхнем регистре. Python чувствителен к регистру, а имена аргументов могут порой использоваться при их передаче по ключам, поэтому документация должна содержать реальные имена переменных. Лучше всего перечислять каждый аргумент в отдельной строке. Например:
def complex(real=0.0, imag=0.0): «»»Сформировать комплексное число. Ключевые аргументы: real — действительная часть (по умолчанию 0.0) imag — мнимая часть (по умолчанию 0.0) «»» if imag == 0.0 and real == 0.0: return complex_zero .
Если весь docstring не помещается в строку, вы можете вынести закрывающие кавычки на отдельную линию. Таким образом, можно будет использовать Emacs команду: fill-paragraph
Обработка Docstring
Инструменты обработки документационных строк должны удалять одинаковое количество отступов, равное минимальному отступу всех не пустых строк, начиная со второй. Любые отступы в первой строке документации несущественны и будут удалены. Относительный отступ более поздних строк в строке документа сохраняется. Пустые строки должны быть удалены из начала и конца строки документа.
Поскольку код гораздо точнее слов, здесь приведена реализация алгоритма:
def trim(docstring): if not docstring: return » # Конвертирует табы в пробелы (согласно нормам Python) # и разбивает в список из строк: lines = docstring.expandtabs().splitlines() # Высчитывает наименьший отступ (первая линия не считается): indent = sys.maxsize for line in lines[1:]: stripped = line.lstrip() if stripped: indent = min(indent, len(line) — len(stripped)) # Убираем отступ (особенность первой линии документации): trimmed = [lines[0].strip()] if indent < sys.maxsize: for line in lines[1:]: trimmed.append(line[indent:].rstrip()) # Убираем пустые строки из начала и конца: while trimmed and not trimmed[-1]: trimmed.pop() while trimmed and not trimmed[0]: trimmed.pop(0) # Возвращаем итоговую строку документации: return ‘n’.join(trimmed)
Примечание переводчика
По сравнению с оригинальным кодом, в python3 атрибут sys.maxint был переименован в sys.maxsize, поэтому в коде это сразу исправлено.
Документация в следующем примере содержит два символа новой строки и поэтому имеет длину равную трём. Первая и последняя строки пусты:
def foo (): «»» Это вторая строка документации. «»»
>>> print repr(foo.__doc__) ‘n Это вторая строка документации.n ‘ >>> foo.__doc__.splitlines() [», ‘ Это вторая строка документации.’, ‘ ‘] >>> trim(foo.__doc__) ‘ Это вторая строка документации.’
Таким образом, после обработки следующие документационные строки будут эквивалентны:
def foo(): «»»Документация на несколько линий. «»» def bar(): «»» Документация на несколько линий. «»»
Примечание переводчика
Также не стоит забывать и про модуль inspect, где лежит уже готовая реализация функции форматирования документаций, поэтому с таким же успехом можно было написать: inspect.cleandoc(function.__doc__)
Только зарегистрированные пользователи могут участвовать в опросе. Войдите, пожалуйста.
Стоит ли продолжить переводить наиболее важные и интересные статьи PEP? Например, по одному разделу в неделю
68.27% Да, стоит переводить, ведь это поможет новичкам 142
5.29% Нет, новички могут сами смогут разобраться с PEP, если захотят 11
26.44% Лучше делать статьи, основанные на PEP, где просто указаны главные моменты и привести побольше примеров 55
Источник: habr.com