Как документировать код python

Документирование кода в Python

6 февраля 2013 г. Archy Python и запуск програм 1

Сегодня мы поговорим о том как документируется код в языке Python. Документация кода достаточно важный аспект, ведь от нее порой зависит читаемость и быстрота понимания вашего кода.

Как это делается?

Строки комментария можно оставлять используя символ # или открывающие «»» и закрывающие «»»

Документировать файлы модулей, функции и классы необходимо следующим образом. В модулях комментарий располагается в начале файла, в функциях и классах после объявления. Далее.

Docstrings: документирование кода в Python

В статье, опубликованной на сайте pythonist.ru, рассмотрены строки документации в Python. Давайте разберемся, как и зачем их использовать.

Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.

Пример 1: Строки документации.

def square(n): '''Принимает число n, возвращает квадрат числа n''' return n**2

Здесь строковый литерал:

Принимает число n, возвращает квадрат числа n

Внутри тройных кавычек находится строка документации функции square() , которая размещена сразу после ее определения.

Примечание. Вы можете использовать как тройные двойные кавычки «»» , так и тройные одинарные кавычки »’ для создания строк документации. Используйте r»»» , если вы применяете обратный слэш в ваших строках документации. Для строк документации Unicode используйте u»»» .

Комментарии vs строки документации Python

Комментарии Python

Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.

В Python мы используем символ # для написания однострочного комментария. Например,

# Программа для вывода на экран строки "Hello World" print("Hello World")

Комментарии Python с использованием строк

Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,

"Я однострочный комментарий" ''' Я многострочный комментарий! ''' print("Hello World")

Примечание. Мы используем тройные кавычки для многострочных строк.

Строки документации Python

Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.

Мы можем получить доступ к этим строкам документации, используя атрибут __doc__ .

Атрибут __doc__

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

Пример 2: Вывод на экран строки документации.

def square(n): '''Принимает число n, возвращает квадрат числа n''' return n**2 print(square.__doc__)

Принимает число n, возвращает квадрат числа n

Здесь мы получили доступ к документации нашей функции square() с помощью атрибута __doc__ .

Теперь давайте посмотрим на строки документации для встроенной функции print() :

Пример 3: строки документации для встроенной функции print().

print(print.__doc__)

print(value, …, sep=' ', end='\n', file=sys.stdout, flush=False) 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: Однострочная строка документации для функции.

def multiplier(a, b): """Принимает два числа, возвращает их произведение.""" return a*b

Многострочные строки документации в Python

Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.

Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.

Некоторые из них перечислены ниже:

1. Строки документации для модулей Python

• Строки документации для модулей Python должны содержать список всех доступных классов, функций, объектов и исключений, которые импортируются при импорте модуля.
• Они также должны содержать краткое пояснение (в одну строку) для каждого элемента из этого списка.

Строки документации пишутся в начале файла Python.

Давайте посмотрим на строки документации для встроенного модуля pickle .

Пример 4: строки документации модуля Python.

import pickle print(pickle.__doc__)

Create portable serialized representations of Python objects. See module copyreg for a mechanism for registering custom picklers. See module pickletools source for extensive comments. Classes: Pickler Unpickler Functions: dump(object, file) dumps(object) -> string load(file) -> object

Мы убедились, что строка документации, записанная в начале файла модуля pickle.py, может быть получена при помощи атрибута __doc__ .

2. Строки документации для функций Python

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

Пример 5: строки документации для функций Python.

def add_binary(a, b): ''' Возвращает сумму двух десятичных чисел в двоичном формате. Параметры: a (int): первое десятичное целое число b (int): второе десятичное целое число Возвращаемое значение: binary_sum (str): двоичная строка суммы a и b ''' binary_sum = bin(a+b)[2:] return binary_sum print(add_binary.__doc__)

Возвращает сумму двух десятичных чисел в двоичном формате. Параметры: a (int): первое десятичное целое число b (int): второе десятичное целое число Возвращаемое значение: binary_sum (str): двоичная строка суммы a и b

Как видите, мы добавили краткое описание того, что делает функция, параметры, которые она принимает, и значение, которое она возвращает. Строковый литерал добавляется в функцию add_binary как ее атрибут __doc__ .

3. Строки документации для классов Python

• Строки документации для класса должны обобщать его поведение и перечислять открытые (public) методы и переменные экземпляра.
• Подклассы, конструкторы и методы должны иметь свои собственные строки документации.

Пример 6: строки документации для класса Python.

Предположим, у нас есть файл Person.py со следующим кодом:

class Person: """ Класс для представления человека. . Атрибуты -------- name : str имя человека surname : str фамилия человека age : int возраст человека Методы ------ info(additional=""): Печатает имя и возраст человека. """ def __init__(self, name, surname, age): """ Устанавливает все необходимые атрибуты для объекта person. Параметры --------- name : str имя человека surname : str фамилия человека age : int возраст человека """ self.name = name self.surname = surname self.age = age def info(self, additional=""): """ Печатает имя и возраст человека. Если аргумент 'additional' передан, то он добавляется после основной информации. Параметры --------- additional : str, optional Дополнительная информация для отображения (по умолчанию None) Возвращаемое значение --------------------- None """ print(f'My name is . I am years old.' + additional)

Мы можем использовать следующий код для доступа только к строкам документации класса Person :

print(Person.__doc__)

Класс для представления человека. . Атрибуты -------- name : str имя человека surname : str фамилия человека age : int возраст человека Методы ------ info(additional=""): Печатает имя и возраст человека.

Использование функции help() для строк документации

Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.

Пример 7: чтение строк документации с помощью функции help().

Мы можем использовать функцию help() для класса Person из Примера 6:

help(Person)

Help on class Person in module main: class Person(builtins.object) | Класс для представления человека. | | … | | Атрибуты | -------- | name : str | имя человека | surname : str | фамилия человека | age : int | возраст человека | | Методы | ------ | info(additional=""): | Печатает имя и возраст человека. | Methods defined here: | | init(self, name, surname, age) | Устанавливает все необходимые атрибуты для объекта person. | | Параметры | --------- | name : str | имя человека | surname : str | фамилия человека | age : int | возраст человека | | info(self, additional='') | Печатает имя и возраст человека. | | Если аргумент additional передан, то он добавляется после основной информации. | | Параметры | --------- | additional : str, optional | Дополнительная информация для отображения (по умолчанию None) | | Возвращаемое значение | --------------------- | None | | ---------------------------------------------------------------------- | Data descriptors defined here: | | dict | dictionary for instance variables (if defined) | | weakref | list of weak references to the object (if defined)

Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.

4. Строки документации для скриптов Python

• Строки документации для скрипта Python должны документировать функции скрипта и синтаксис командной строки, переменные среды и файлы.
• Строки документации скрипта должны использоваться в качестве «сообщения по использованию», которое выводится, когда скрипт вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией «-h», для «help»).
• Они должны служить краткой ссылкой на все функции и аргументы.

5. Строки документации для пакетов Python

Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.

Форматы строк документации

Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.

Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.

Документирование кода в Python

Документирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.

Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.

Docstring

Docstring — это строковый литерал, который расположен сразу за объявлением модуля, функции, класса или метода. О том, какие существуют соглашения в документировании Python кода описано в документации PEP257 .

Документация для классов

Документация класса создается для самого класса, а также для его методов.

class Speaker: «»»Это docstring класса Speaker»»» def say_something(self): «»»Это docstring метода»»» print(«something»)

После строки документации нужно оставлять пустую строку

Документация для класса может содержать следующую информацию:

• краткое описание класса (+ его поведение);
• описание атрибутов класса;
• описание публичных методов;
• все, что связано с интерфейсом для подклассов.

Для методов класса документация может содержать:

• краткое описание метода (+ его поведение);
• описание аргументов метода;
• побочные эффекты (если таковые возникают при выполнении метода);
• исключения.

Ниже — пример с более подробной документацией класса:

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.

Pydoc автоматически генерирует документацию из Python модулей. Информацию по доступным командам модуля pydoc можно получить набрав в терминале:

Разберем подробнее, что умеет pydoc.

Вывод текста документации

pydoc — покажет текст документации указанного модуля, пакета, функции, класса и т.д. Если содержит «\», Python будет искать документацию по указанному пути.

Для примера, посмотрим документацию встроенного модуля math:

python -m pydoc math Help on built-in module math: NAME math DESCRIPTION This module provides access to the mathematical functions defined by the C standard. FUNCTIONS acos(x, /) Return the arc cosine (measured in radians) of x. acosh(x, /) Return the inverse hyperbolic cosine of x. .

В консоль выведется название модуля, его описание и описание всех функций в модуле.

Поиск по документации

pydoc -k — найдет ключевое слово в документации всех доступных модулей.

Допустим, нам нужно распаковать gzip файл. Поищем слово » gzip «:

python -m pydoc -k gzip _compression — Internal classes used by the gzip, lzma and bz2 modules gzip — Functions that read and write gzipped files. test.test_gzip — Test script for the gzip module.

В списке мы видим модуль gzip . Теперь можно посмотреть его документацию:

python -m pydoc gzip Help on module gzip: NAME gzip — Functions that read and write gzipped files. DESCRIPTION The user of the file doesn’t have to worry about the compression, but random access is not allowed.

По описанию, данный модуль решит нашу задачу.

HTTP сервер с документацией

Для удобства просмотра документации, pydoc позволяет одной командой создать HTTP-сервер:

python -m pydoc -p 331 Server ready at http://localhost:331/ Server commands: [b]rowser, [q]uit server>

Теперь можно перейти в браузер и зайти на http://localhost:331/

Для остановки сервера введите » q » и нажмите » Enter «:

server> q Server stopped

Также HTTP-сервер доступен через python -m pydoc -b – эта команда создаст сервер на свободном порту, откроет браузер и перейдет на нужную страницу.

Запись документации в файл

python -m pydoc -w sqlite3 — запишем файл с документацией по модулю sqlite3 в html файл.

Автодокументирование кода

Для того чтобы облегчить написание документации и улучшить ее в целом, существуют различные Python-пакеты. Один из них — pyment .

Pyment работает следующим образом:

1. Анализирует один или несколько скриптов.
2. Получает существующие строки документации.
3. Генерирует отформатированные строки документации со всеми параметрами, значениями по умолчанию и т.д.
4. Далее вы можете применить сгенерированные строки к своим файлам.

Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.

pip install pyment

pyment myfile.py # для файла pyment -w myfile.py # для файла + запись в файл pyment my/folder/ # для всех файлов в папке

Для большинства IDE также существуют плагины, помогающие документировать код:

• AutoDocstring – для VS Code.
• Auto​Docstring – для SublimeText.
• Python DocBlock Package – для Atom.
• Autodoc – для PyCharm.

В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно:

1. Переместить курсор под объявление функции.
2. Написать тройные кавычки «»» и нажмите » Enter» .

Учимся писать строки документации в Python

Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.

Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.

Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.

Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.

Что такое докстринг?

Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»»»»» в начале модуля, класса, метода или функции, который описывает, что делает функция.

Только в случае, если это первый оператор в функции, он может быть распознан компилятором байт-кода Python и доступен как атрибуты объекта времени выполнения с помощью метода __doc__ или функции help() .

def show_docstring(): """Print function description to user""" print("Using __doc__ method:") print(show_docstring.__doc__) print("Using help() function:") help(show_docstring) $ show_docstring(); "Using __doc__ method:" "Print function description to user" "Using help() function:" "Print function description to user"

Лучшие практики

1. Все модули, классы, методы и функции, включая конструктор __init__ в пакетах, должны иметь строки документации.
2. Описания пишутся с заглавной буквы и включают пунктуацию в конце предложения.
3. Всегда окружайте строки документации двойными кавычками по три раза, как показано тут: «»»Triple double quotes.»»» .
4. В конце докстринга пустая строка не ставится.

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

def power(a, b): """Returns arg1 raised to power arg2.""" return a**b

1. Однострочный докстринг прописывает функцию или действие метода как команду, а не как описание функции: «»»Do this, return that»»» .
2. Однострочный докстринг не является “подписью” function(a, b) -> list , повторяющей параметры функции/метода.

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

def suggest_places(auth_key, city): """Returns longitude and latitude of first suggested location in the Netherlands from Postcode API. :param auth_key: authorization key for Postcode API :type auth_key: str :param city: textual input for city names to match in Postcode API :type city: str :rtype: (str, str), str, str :return: (longitude, latitude), Postcode API status code, Postcode API error message

Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.

Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.

Стиль Sphinx

Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.

Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:

1. Обработки специальным программным обеспечением, таким как Docutils.
2. Легкого чтения программистами, которые читают и пишут исходный код Python.

def multiply(a, b, c=0): """Return sum of multiplication of all arguments. :param a: arg1 :type a: int :param b: arg2 :type b: int :param c: arg3, defaults to 0 :type c: int, optional :raises ValueError: if arg1 is equal to arg2 :rtype: int :return: multiplication of all arguments """ if a == b: raise ValueError('arg1 must not be equal to arg2') return a*b*c

Синтаксис Sphinx

В Sphinx используется такой же, как и в большинстве языков программирования синтаксис: keyword(reserved word) . Наиболее важные ключевые слова:

• param и type : значение параметра и тип его переменной;
• return и rtype : возвращаемое значение и его тип;
• :raises : описывает любые ошибки, которые возникают в коде;
• .. seealso:: : информация для дальнейшего чтения;
• .. notes:: : добавление заметки;
• .. warning:: : добавление предупреждения.

Хотя порядок этих ключевых слов не является фиксированным, (опять же) принято придерживаться вышеуказанного порядка на протяжении всего проекта. Записи seealso , notes и warning не являются обязательными.

Например, вы можете связывать параметры с помощью знака | , как показано тут:

:param x: An integer, defaults to None :type x: int:param y: An integer or string :param y: An integer or string :type y: int|string

Макет Sphynx

Общий макет этой строки документации показан ниже.

""" < Summary. >:param : , defaults to :type : (, optional) :raises :  :rtype: :return: """

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

• Топ-10 магических команд в Python, которые повысят вашу продуктивность
• Nota Bene для программиста Python
• Почему Python не станет языком программирования будущего