ФРОО 24 сентября 2018

Работа с документацией в Python: поиск информации и соглашения

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

Основы работы с документацией в Python: поиск информации и соглашения

Работа с документацией является одной из важных составляющих деятельности разработчика. И это не только чтение документации к библиотекам и комментариев в коде, но и документирование собственного кода, а также поддержание его в актуальном состоянии. Качественно задокументированный код во многих случаях упрощает его поддержание и сокращает время на «вхождение» новых сотрудников в проект. Если же речь идет об изучении нового языка программирования, качество документации и поддержка сообщества могут сыграть решающую роль в освоении материала и снизить порог вхождения.

Документация к языку программирования Python обладает всеми качествами, которые отличают «хорошую» документацию от «плохой». Тем не менее, новички часто сталкиваются с рядом вопросов. Как быстро найти информацию о классе или функции? Как самому писать документацию к коду? Какие инструменты можно использовать при документировании кода? На эти вопросы мы и постараемся ответить в статье.

Основной источник информации о Python

Безусловно, основным, наиболее полным и актуальным источником информации о Python является сайт c официальной документацией. Главная страница сайта предоставляет удобную навигацию по разделам.

Важные разделы сайта (полезно начинающим программистам)

  • Setup and Usage — содержит информацию об установке и настройке Python на разных платформах;
  • Tutorial — учебное пособие для новичков, с которого и рекомендуется начинать свой путь в мир Python;
  • Library Reference — подробное описание стандартной библиотеки Python;
  • Python HOWTO — различные руководства по конкретным темам;
  • Language Reference — раздел для тех кто, хочет знать подробности реализации СPython.

В остальных разделах вы можете найти информацию о сторонних модулях, их установке и распространении, информацию по написанию расширений для Python на языках С/С++, часто задаваемые вопросы и новости Python.

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

Для поиска по сайту имеются: окно быстрого поиска по ключевым словам и таблицы с индексами для поиска по названию модуля (класса, метода, переменной). Важно: Python динамично развивается, постоянно добавляются новые возможности и функционал. Если вы хотите работать с актуальной документацией — выберите необходимую вам версию Python в выпадающем меню в шапке сайта.

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

Встроенная справочная система

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

Небольшое уточнение: поскольку в Python все является объектом, в том числе методы и классы, далее мы будем часто употреблять термин «объект» применительно к целям получения информации.

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

Примеры

>>> help(ord)
Help on built-in function ord in module builtins:
ord(c, /)
    Return the Unicode code point for a one-character string.
(END)

В приведенном выше примере, мы вызвали справку по функции ord. В тексте сообщения содержится информация о том, что делает функция и к какому модулю она относится.

Теперь попробуем получить информацию о модуле стандартной библиотеки os.

>>> help(os)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'os' is not defined

Почему вызов функции завершился выбросом исключения? Ведь модуль os входит в стандартную библиотеку и маловероятно, что справочная информация по нему не была включена.

Docstring

Чтобы ответить на этот вопрос, давайте разберемся, где хранится справочная информация и как работает функция help. Как уже говорилось выше, все в Python является объектом. Все объекты в Python имеют специальный атрибут __doc__, предназначенный для хранения строки документации — docstring. Вот как определено понятие docstring в официальной документации: «Docstring — строковый литерал, который встречается как первый оператор в определении модуля, функции, класса или метода. Такой docstring становится специальным атрибутом __doc__ этого объекта».

Посмотрим, что хранится в атрибуте __doc__ объекта ord.

>>> ord.__doc__
'Return the Unicode code point for a one-character string.'

Размещение справки об объекте в исходном коде самого объекта позволяет элегантно решить вопрос хранения информации и доступа к ней. Функция help при передаче ей в качестве аргумента объекта для получения информации о нем, обращается к атрибуту __doc__ этого объекта. Поскольку модуль os не импортирован, он отсутствует в глобальной области видимости и не доступен при вызове функции help. Именно по этой причине мы получаем ошибку. Для решения проблемы достаточно импортировать модуль. Есть еще один способ избежать ошибки и не связанный с импортом объекта — передать в качестве аргумента в функцию help строку с именем объекта.

>>> help('os')

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

Посмотрим на исходный код модуля os и убедимся в том, что docstring и содержимое атрибута os.__doc__ совпадают. Из приведенного кода видно, как определяются в коде docstring. Строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта.

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

Как вспомнить название модуля, класса или функции?

Стандартная библиотека Python весьма обширна и содержит большое количество модулей. Помнить их все, в том числе и заложенный функционал, невозможно. Что делать, если мы не помним (не знаем) название модуля, класса или функции? Ниже приведены несколько примеров, помогающих в таких ситуациях.

Получение списка доступных модулей:

>>> help('modules')

Получение ключевых слов:

>>> from keyword import kwlist
>>> print(*kwlist, sep='\n')

Получение списка названий встроенных функций:

>>> import builtins
>>> print(*builtins.__dict__.keys(), sep='\n')

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

>>> dir(int)

Как задокументировать собственный код?

Теперь, когда мы знаем о docstring и работе функции help, мы можем задокументировать свой код. В качестве примера возьмем скрипт factorial.py:

def factorial(n):
   if n < 2:
       return 1
   return n * factorial(n — 1)

if __name__ == "__main__":
   n = int(input())
   print(factorial(n))

Добавим docstring.

""" Скрипт для нахождения факториала """

def factorial(n):
    """ Вычисляет факториал числа n """
   if n < 2:
       return 1
   return n * factorial(n - 1)

if __name__ == "__main__":
   n = int(input())
   print(factorial(n))

Убедимся в наличии документации по модулю factorial:

>>> import factorial
>>> factorial.__doc__
' Скрипт для нахождения факториала '
>>> factorial.factorial.__doc__
' Вычисляет факториал числа n '

Вызов help(factorial) вернет справку:

Help on module factorial:

NAME
   factorial - Скрипт для нахождения факториала

FUNCTIONS
   factorial(n)
       Вычисляет факториал числа n

FILE
   /home/user/factorial.py
(END)

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

О библиотеке pydoc

Мы уже упоминали модуль стандартной библиотеки pydoc. Он автоматически генерирует документацию из модулей Python. Документация может быть представлена ​​в виде страниц текста на консоли, отображаться в браузере или сохраняться в HTML-файлах.

Команда pydoc позволяет вывести текст справки прямо в терминале (не интерпретаторе Python):

$ pydoc sum

Help on built-in function sum in module __builtin__:

sum(...)
   sum(sequence[, start]) -> value
   Return the sum of a sequence of numbers (NOT strings) plus the value
   of parameter 'start' (which defaults to 0). When the sequence is
   empty, return start.
(END)

Для создания документации в виде HTML-страниц используется ключ -w. Это позволяет организовать хранение документации отдельно от кода.

$ pydoc -w sum
wrote sum.html
$ cat sum.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><title>python: built-in function sum</title>
<meta charset="utf-8">
</head><body bgcolor="#f0f0f8">
<dl><dt><a name="-sum"><strong>sum</strong></a>(...)</dt><dd><tt>sum(sequence[,&nbsp;start])&nbsp;-&gt;&nbsp;value<br>
&nbsp;<br>
Return&nbsp;the&nbsp;sum&nbsp;of&nbsp;a&nbsp;sequence&nbsp;of&nbsp;numbers&nbsp;(NOT&nbsp;strings)&nbsp;plus&nbsp;the&nbsp;value<br>
of&nbsp;parameter&nbsp;'start'&nbsp;(which&nbsp;defaults&nbsp;to&nbsp;0).&nbsp;&nbsp;When&nbsp;the&nbsp;sequence&nbsp;is<br>
empty,&nbsp;return&nbsp;start.</tt></dd></dl>

Для поиска по docstring модулей используется ключ -k. В качестве аргумента в этом случае передается ключевое слово. В результате будут выведены названия всех модулей в docstring которых встречается ключевое слово.

$ pydoc -k json
json - JSON (JavaScript Object Notation) <http://json.org> is a subset of
json.decoder - Implementation of JSONDecoder
json.encoder - Implementation of JSONEncoder
json.scanner - JSON token scanner
json.tool - Command-line tool to validate and pretty-print JSON
_json
pbr.pbr_json

Обратим ваше внимание на одну особенность поиска по документации при использовании ключа -k. Поиск производится только по первым строкам документации модулей. Тем не менее, данный функционал может быть весьма полезным в некоторых случаях.

Для любителей работать в браузере, предусмотрена возможность запуска HTTP-сервера документации, который будет доступен по порту, указанному после ключа -p.

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

В третьей версии Python для управления сервером добавлена пара команд: b — открытие страницы документации в браузере, q — завершения работы сервера. При вызове команды pydoc3 с ключом -b произойдет запуск сервера и автоматическое открытие страницы в браузере. В документацию также будут включены модули, расположенные в директории из которой был запущен сервер.

Соблюдение соглашений

При документировании кода важно соблюдать принятые в языке программирования соглашения. Для решения этих задач существуют различные инструменты. В этой статье мы становимся на одном из них — модуле pydocstyle.

Модуль pydocstyle — это инструмент статического анализа для проверки соответствия docstring соглашениям, принятым в Python. Установка модуля осуществляется с помощью менеджера пакетов pip:

$ pip install pydocstyle

По умолчанию pydocstyle проверяет docstring на соответствие официальному соглашению PEP257. Проверим созданный нами скрипт factorial.py:

$ pydocstyle factorial.py
factorial.py:1 at module level:
  D400: First line should end with a period (not 'а')
factorial.py:1 at module level:
  D210: No whitespaces allowed surrounding docstring text
factorial.py:3 in public function `factorial`:
  D400: First line should end with a period (not 'n')
factorial.py:3 in public function `factorial`:
  D210: No whitespaces allowed surrounding docstring text

Видим, что pydocstyle обнаружил ошибки — лишние пробелы вокруг текста и отсутствие точки в конце строк документации. Исправим эти ошибки и запустим pydocstyle еще раз.

Модуль pydocstyle имеет более широкие возможности, чем в приведенном выше примере, и гибкую систему настроек под требования по оформлению документации. Ознакомится с их полным списком можно вызвав pydocstyle -h или в разделе «документация» на сайте проекта.

Полезные ссылки

Еще статьи по Python

МЕРОПРИЯТИЯ

Комментарии

ВАКАНСИИ

Добавить вакансию
Vue.js Frontend Разработчик
по итогам собеседования
IT recruiter
от 1500 USD

ЛУЧШИЕ СТАТЬИ ПО ТЕМЕ