Pydoc python что это
Pydoc python что это
Работа с документацией является одной из важных составляющих деятельности разработчика. И это не только чтение документации к библиотекам и комментариев в коде, но и документирование собственного кода, а также поддержание его в актуальном состоянии. Качественно задокументированный код во многих случаях упрощает его поддержание и сокращает время на «вхождение» новых сотрудников в проект. Если же речь идет об изучении нового языка программирования, качество документации и поддержка сообщества могут сыграть решающую роль в освоении материала и снизить порог вхождения.
Документация к языку программирования Python обладает всеми качествами, которые отличают «хорошую» документацию от «плохой». Тем не менее, новички часто сталкиваются с рядом вопросов. Как быстро найти информацию о классе или функции? Как самому писать документацию к коду? Какие инструменты можно использовать при документировании кода? На эти вопросы мы и постараемся ответить в статье.
Безусловно, основным, наиболее полным и актуальным источником информации о Python является сайт c официальной документацией. Главная страница сайта предоставляет удобную навигацию по разделам.
Важные разделы сайта (полезно начинающим программистам):
Поиск по сайту с документацией
Для поиска по сайту имеются: окно быстрого поиска по ключевым словам и таблицы с индексами для поиска по названию модуля (класса, метода, переменной). Важно: Python динамично развивается, постоянно добавляются новые возможности и функционал. Если вы хотите работать с актуальной документацией — выберите необходимую вам версию Python в выпадающем меню в шапке сайта.
Создатели Python предусмотрели возможность установить документацию локально на компьютере. Для этого необходимо перейти на страницу загрузки, выбрать версию Python, формат файлов (доступны pdf, epub, html, txt) и способ архивирования. После скачивания и распаковки архива, вы можете пользоваться документацией в полном объеме.
pydoc — Documentation generator and online help system¶
Source code: Lib/pydoc.py
The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.
For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments() ).
The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. For example, running
at a shell prompt will display documentation on the sys module, in a style similar to the manual pages shown by the Unix man command. The argument to pydoc can be the name of a function, module, or package, or a dotted reference to a class, method, or function within a module or module in a package. If the argument to pydoc looks like a path (that is, it contains the path separator for your operating system, such as a slash in Unix), and refers to an existing Python source file, then documentation is produced for that file.
In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == ‘__main__’: guard to only execute code when a file is invoked as a script and not just imported.
When printing output to the console, pydoc attempts to paginate the output for easier reading. If the PAGER environment variable is set, pydoc will use its value as a pagination program.
Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.
Changed in version 3.4: pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.
В Python, что делает pydoc?
Новое в программировании и Python в целом. В книге, из которой я учусь, автор предложил мне выяснить цель Pydoc.
Я сделал поиск в Google и нашел совпадение (из Gnome Terminal), но для меня это не имело особого смысла. Кто-нибудь ум упрощает немного? Благодарю.
Используйте это на своем терминале Windows, чтобы понять, что делает функция в python:
Если документация для конкретной функции очень длинная, используйте ‘q’, чтобы выйти из нее.
Это инструмент для генерации документации в стиле Python, см. http://docs.python.org/2/library/pydoc.html
Вы можете посмотреть на Сфинкса тоже.
Модуль Pydoc в Python может быть использован для создания документации в виде HTML-страниц или даже на консоли
Я создал два примера файлов в каталоге file1.py и file2.py, который имеет простой код с одной строкой комментария.
Еще один способ увидеть комментарии на html-странице, набрав эту команду и экспортировав ее в html
Если у вас есть несколько файлов Python и вы хотите сгенерировать HTML в отдельной папке, то простые команды Shell могут сделать эту работу. Код ниже генерирует папку «htmldocs», а затем генерирует html и перемещает их в эту новую папку. Если вы откроете любой из них в правом верхнем углу, вы увидите индексную опцию, с помощью которой вы можете перемещаться по другим страницам.
Модуль pydoc автоматически генерирует документацию из модулей Python. Документация может быть представлена в виде текстовых страниц на консоли, подана в веб-браузер или сохранена в файлах HTML.
Для модулей, классов, функций и методов отображаемая документация является производной от строки документации (то есть атрибута doc) объекта и рекурсивно его документируемых членов. Если нет строки документации, pydoc пытается получить описание из блока строк комментариев чуть выше определения класса, функции или метода в исходном файле или в верхней части модуля.
Краткое описание, предоставленное Wikipedia: «Pydoc позволяет программистам Python получать доступ к файлам справки документации Python, генерировать текстовые и HTML-страницы со спецификой документации и находить подходящий модуль для конкретной работы».
Документирование кода в Python
Д окументирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speaker: «»»Это docstring класса Speaker»»» 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: поиск информации и соглашения
Python обладает великолепной документацией и предоставляет удобные способы для работы с ней: от официального сайта до встроенной справочной системы.
Работа с документацией является одной из важных составляющих деятельности разработчика. И это не только чтение документации к библиотекам и комментариев в коде, но и документирование собственного кода, а также поддержание его в актуальном состоянии. Качественно задокументированный код во многих случаях упрощает его поддержание и сокращает время на «вхождение» новых сотрудников в проект. Если же речь идет об изучении нового языка программирования, качество документации и поддержка сообщества могут сыграть решающую роль в освоении материала и снизить порог вхождения.
Документация к языку программирования Python обладает всеми качествами, которые отличают «хорошую» документацию от «плохой». Тем не менее, новички часто сталкиваются с рядом вопросов. Как быстро найти информацию о классе или функции? Как самому писать документацию к коду? Какие инструменты можно использовать при документировании кода? На эти вопросы мы и постараемся ответить в статье.
Основной источник информации о Python
Безусловно, основным, наиболее полным и актуальным источником информации о Python является сайт c официальной документацией. Главная страница сайта предоставляет удобную навигацию по разделам.
Важные разделы сайта (полезно начинающим программистам)
В остальных разделах вы можете найти информацию о сторонних модулях, их установке и распространении, информацию по написанию расширений для Python на языках С/С++, часто задаваемые вопросы и новости Python.
Поиск по сайту с документацией
Для поиска по сайту имеются: окно быстрого поиска по ключевым словам и таблицы с индексами для поиска по названию модуля (класса, метода, переменной). Важно: Python динамично развивается, постоянно добавляются новые возможности и функционал. Если вы хотите работать с актуальной документацией — выберите необходимую вам версию Python в выпадающем меню в шапке сайта.
Создатели Python предусмотрели возможность установить документацию локально на компьютере. Для этого необходимо перейти на страницу загрузки, выбрать версию Python, формат файлов (доступны pdf, epub, html, txt) и способ архивирования. После скачивания и распаковки архива, вы можете пользоваться документацией в полном объеме.
Встроенная справочная система
Чтение объемного справочного руководства полезно на этапе изучения языка. При работе с кодом чаще возникает необходимость получить небольшую справку о работе той или иной функции, получаемых аргументах, или о наличии у класса атрибутов и методов. В таких случаях информация из официальной документации, как правило, избыточна, а поиск по ней может может занять значительное время. В Python для таких случаев существует встроенная справочная система, позволяющая быстро получить краткую справку об объекте.
Небольшое уточнение: поскольку в Python все является объектом, в том числе методы и классы, далее мы будем часто употреблять термин «объект» применительно к целям получения информации.
Примеры
Почему вызов функции завершился выбросом исключения? Ведь модуль os входит в стандартную библиотеку и маловероятно, что справочная информация по нему не была включена.
Docstring
Посмотрим, что хранится в атрибуте __doc__ объекта ord.
Посмотрим на исходный код модуля os и убедимся в том, что docstring и содержимое атрибута os.__doc__ совпадают. Из приведенного кода видно, как определяются в коде docstring. Строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта.
Вы уже заметили, что вывод функции help отличается от вывода, полученного через обращение к атрибуту __doc__ объекта. Он более информативен и выводит информацию в виде форматированного текста. У функции help есть еще одна особенность, повышающая удобство работы со справочной системой. При вызове help без аргументов запускается интерактивный режим справочной системы. Для получения справки в нем достаточно набрать только название интересующего нас объекта. Запустив интерактивный режим в отдельном терминале, мы получаем удобный инструмент для работы с документацией.
Как вспомнить название модуля, класса или функции?
Стандартная библиотека Python весьма обширна и содержит большое количество модулей. Помнить их все, в том числе и заложенный функционал, невозможно. Что делать, если мы не помним (не знаем) название модуля, класса или функции? Ниже приведены несколько примеров, помогающих в таких ситуациях.
Получение списка доступных модулей:
Получение ключевых слов:
Получение списка названий встроенных функций:
Как задокументировать собственный код?
Убедимся в наличии документации по модулю factorial :
Вызов help(factorial) вернет справку:
При создании документации к коду стоит придерживаться правил и рекомендаций, описанных в PEP257 и PEP8. Ссылки на эти документы приведены в конце статьи.
О библиотеке pydoc
Команда pydoc позволяет вывести текст справки прямо в терминале (не интерпретаторе Python):
Соблюдение соглашений
Модуль pydocstyle — это инструмент статического анализа для проверки соответствия docstring соглашениям, принятым в Python. Установка модуля осуществляется с помощью менеджера пакетов pip:
По умолчанию pydocstyle проверяет docstring на соответствие официальному соглашению PEP257. Проверим созданный нами скрипт factorial.py:
Видим, что pydocstyle обнаружил ошибки — лишние пробелы вокруг текста и отсутствие точки в конце строк документации. Исправим эти ошибки и запустим pydocstyle еще раз.