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

МЕНЮ

Искусственный интеллект
Поиск
Регистрация на сайте
Помощь проекту

ТЕМЫ

Новости ИИРазработка ИИВнедрение ИИРабота разума и сознаниеМодель мозгаРобототехника, БПЛАТрансгуманизмОбработка текстаТеория эволюцииДополненная реальностьЖелезоКиберугрозыНаучный мирИТ индустрияРазработка ПОТеория информацииМатематикаЦифровая экономика

Авторизация

RSS

RSS новости

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, а в качестве аргумента передать сам объект или строку с названием объекта.

Примеры

Shell

1

2

3

4

5

>>>help(ord)

Help on built-infunctionord inmodule builtins:

ord(c,/)

Returnthe Unicode code point foraone-character string.

(END)

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

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

Shell

1

2

3

4

>>>help(os)

Traceback(most recent call last):

File"<stdin>",line1,in<module>

NameError:name'os'isnotdefined

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

Docstring

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

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

Shell

1

2

>>>ord.__doc__

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

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

Shell

1

>>>help('os')

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

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

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

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

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

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

Shell

1

>>>help('modules')

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

Shell

1

2

>>>from keyword import kwlist

>>>print(*kwlist,sep=' ')

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

Shell

1

2

>>>import builtins

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

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

Shell

1

>>>dir(int)

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

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

Python

1

2

3

4

5

6

7

8

deffactorial(n):

   ifn<2:

       return1

   returnn*factorial(n—1)

if__name__=="__main__":

   n=int(input())

   print(factorial(n))

Добавим docstring.

Python

1

2

3

4

5

6

7

8

9

10

11

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

deffactorial(n):

    """ Вычисляет факториал числа n """

   ifn<2:

       return1

   returnn*factorial(n-1)

if__name__=="__main__":

   n=int(input())

   print(factorial(n))

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

1

2

3

4

5

>>>import factorial

>>>factorial.__doc__

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

>>>factorial.factorial.__doc__

' Вычисляет факториал числа n '

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

Shell

1

2

3

4

5

6

7

8

9

10

11

12

Help on module factorial:

NAME

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

FUNCTIONS

   factorial(n)

       Вычисляетфакториалчислаn

FILE

   /home/user/factorial.py

(END)

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

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

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

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

Shell

1

2

3

4

5

6

7

8

9

10

$pydoc sum

Help on built-infunctionsum inmodule __builtin__:

sum(...)

   sum(sequence[,start])->value

   Returnthe sum ofasequence of numbers(NOTstrings)plus the value

   of parameter'start'(which defaults to0).When the sequence is

   empty,returnstart.

(END)

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

Shell

1

2

3

4

5

6

7

8

9

10

11

12

13

$pydoc-wsum

wrote sum.html

$catsum.html

<!DOCTYPE html PUBLIC"-//W3C//DTD HTML 4.0 Transitional//EN">

<html><head><title>python:built-infunctionsum</title>

<meta charset="utf-8">

</head><body bgcolor="#f0f0f8">

<dl><dt><aname="-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 которых встречается ключевое слово.

Shell

1

2

3

4

5

6

7

8

$pydoc-kjson

json-JSON(JavaScript ObjectNotation)<http://json.org>isasubset of

json.decoder-Implementation of JSONDecoder

json.encoder-Implementation of JSONEncoder

json.scanner-JSON token scanner

json.tool-Command-line tool tovalidate andpretty-print JSON

_json

pbr.pbr_json

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

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

Shell

1

2

3

4

$pydoc3-p1234

Server ready athttp://localhost:1234/

Server commands:[b]rowser,[q]uit

server>

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

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

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

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

Shell

1

$pip install pydocstyle

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

Shell

1

2

3

4

5

6

7

8

9

$pydocstyle factorial.py

factorial.py:1atmodule level:

D400:First line should endwithaperiod(not'а')

factorial.py:1atmodule level:

D210:No whitespaces allowed surrounding docstring text

factorial.py:3inpublic function`factorial`:

D400:First line should endwithaperiod(not'n')

factorial.py:3inpublic function`factorial`:

D210:No whitespaces allowed surrounding docstring text

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

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


Источник: proglib.io

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