pydoc
— Генератор документации и система интерактивной помощи¶
Источник: Lib/pydoc.py
Модуль pydoc
автоматически генерирует документацию по модулям Python. Документация может быть представлена в виде страниц текста на консоли, передана в веб-браузер или сохранена в HTML-файлах.
Для модулей, классов, функций и методов отображаемая документация берется из docstring (т.е. атрибута __doc__
) объекта и рекурсивно из его документируемых членов. Если docstring отсутствует, pydoc
пытается получить описание из блока строк комментариев непосредственно над определением класса, функции или метода в исходном файле или в верхней части модуля (см. inspect.getcomments()
).
Встроенная функция help()
вызывает систему интерактивной справки в интерактивном интерпретаторе, который использует pydoc
для генерации документации в виде текста на консоли. Эту же текстовую документацию можно просмотреть и вне интерпретатора Python, запустив pydoc как скрипт в командной строке операционной системы. Например, выполнив
python -m pydoc sys
в приглашении оболочки выведет документацию по модулю sys
в стиле, похожем на страницы руководства, показываемые командой Unix man. Аргументом команды pydoc может быть имя функции, модуля или пакета или точечная ссылка на класс, метод или функцию в модуле или модуле в пакете. Если аргумент pydoc выглядит как путь (то есть содержит разделитель путей для вашей операционной системы, например, косую черту в Unix) и ссылается на существующий файл с исходным кодом Python, то документация будет создана для этого файла.
Примечание
Чтобы найти объекты и документацию к ним, pydoc
импортирует модуль(ы), который(ые) нужно документировать. Таким образом, любой код на уровне модуля будет выполнен в этом случае. Используйте защиту if __name__ == '__main__':
, чтобы выполнять код только тогда, когда файл вызывается как сценарий, а не просто импортируется.
При печати вывода на консоль pydoc пытается распечатать вывод на страницы для удобства чтения. Если установлена переменная окружения PAGER
, pydoc будет использовать ее значение в качестве программы пагинации.
Указание флага -w
перед аргументом приведет к тому, что HTML-документация будет записываться в файл в текущем каталоге, а не выводиться на консоль.
Указание флага -k
перед аргументом приведет к поиску строк синопсиса всех доступных модулей по ключевому слову, указанному в качестве аргумента, что аналогично команде Unix man. Строка синопсиса модуля - это первая строка его документации.
Вы также можете использовать pydoc для запуска HTTP-сервера на локальной машине, который будет обслуживать документацию в браузерах. python -m pydoc -p 1234 запустит HTTP-сервер на порту 1234, что позволит вам просматривать документацию по адресу http://localhost:1234/
в выбранном вами веб-браузере. Указав в качестве номера порта 0
, вы выберете произвольный неиспользуемый порт.
python -m pydoc -n <hostname> запустит сервер, слушающий указанное имя хоста. По умолчанию имя хоста - „localhost“, но если вы хотите, чтобы к серверу можно было обращаться с других машин, вы можете изменить имя хоста, на которое отвечает сервер. В процессе разработки это особенно полезно, если вы хотите запускать pydoc из контейнера.
python -m pydoc -b запустит сервер и дополнительно откроет веб-браузер на странице индекса модуля. Каждая обслуживаемая страница имеет навигационную панель в верхней части, где вы можете Получить справку по отдельному элементу, Поиск по всем модулям с ключевым словом в строке синопсиса, а также перейти на страницы Индекс модуля, Топики и Ключевые слова.
Когда pydoc генерирует документацию, она использует текущее окружение и путь для поиска модулей. Таким образом, вызов pydoc spam документирует именно ту версию модуля, которую вы получили бы, если бы запустили интерпретатор Python и набрали import spam
.
Предполагается, что документация по модулям для основных модулей находится в каталоге https://docs.python.org/X.Y/library/
, где X
и Y
- номера мажорной и минорной версий интерпретатора Python. Это можно отменить, установив переменную окружения PYTHONDOCS
на другой URL или на локальный каталог, содержащий страницы справочного руководства библиотеки.
Изменено в версии 3.2: Добавлена опция -b
.
Изменено в версии 3.3: Опция командной строки -g
была удалена.
Изменено в версии 3.4: pydoc
теперь использует inspect.signature()
, а не inspect.getfullargspec()
для извлечения информации о подписи из вызываемых файлов.
Изменено в версии 3.7: Добавлена опция -n
.