pydoc.md

1> **Источник:** https://python-all.ru/3.4/library/pydoc.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 26.1. [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) – генератор документации и справочная система89**Исходный код:** [Lib/pydoc.py](https://python-all.ru/src/3.4/Lib/pydoc.py)1011---1213Модуль [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) автоматически создаёт документацию на основе Python-модулей. Документация может быть выведена в виде текстовых страниц на консоли, передана веб-браузеру или сохранена в HTML-файлы.1415Для модулей, классов, функций и методов показываемая документация берётся из docstring (то есть из атрибута `__doc__`) объекта, а также рекурсивно из его документируемых членов. Если docstring отсутствует, [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) пытается получить описание из блока строк комментариев, расположенных непосредственно перед определением класса, функции или метода в исходном файле, либо в начале модуля (см. [`inspect.getcomments()`](https://python-all.ru/3.4/library/inspect.html#inspect.getcomments)).1617Встроенная функция [`help()`](https://python-all.ru/3.4/library/functions.html#help) вызывает справочную систему в интерактивном интерпретаторе, которая использует [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) для вывода документации текстом на консоль. Эту же текстовую документацию можно просмотреть вне интерпретатора Python, запустив **pydoc** как скрипт из командной строки операционной системы. Например, выполнение1819```python20pydoc sys21```2223в командной строке отобразит документацию по модулю [`sys`](https://python-all.ru/3.4/library/sys.html#module-sys) в стиле, напоминающем страницы руководства Unix-команды **man**. Аргументом **pydoc** может быть имя функции, модуля или пакета, а также точечная ссылка на класс, метод или функцию внутри модуля или пакета. Если аргумент **pydoc** выглядит как путь (то есть содержит разделитель пути для вашей операционной системы, например, косую черту в Unix) и указывает на существующий файл исходного кода Python, то документация создаётся для этого файла.2425> **Примечание**26>27> Чтобы найти объекты и их документацию, [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) импортирует документируемый модуль (модули). Поэтому любой код на уровне модуля будет выполнен в этот момент. Используйте конструкцию `if __name__ == '__main__':`, чтобы выполнять код только при запуске файла как скрипта, а не при импорте.2829При выводе на консоль **pydoc** пытается разбить вывод на страницы для удобства чтения. Если задана переменная окружения `PAGER`, **pydoc** использует её значение в качестве программы постраничного вывода.3031Указание флага `-w` перед аргументом приведёт к записи HTML-документации в файл в текущем каталоге вместо вывода текста на консоль.3233Указание флага `-k` перед аргументом выполняет поиск по строкам-синопсисам всех доступных модулей для ключевого слова, заданного в качестве аргумента, снова в стиле, похожем на команду Unix **man**. Строка-синопсис модуля – это первая строка его строки документации.3435Можно также использовать **pydoc** для запуска HTTP-сервера на локальной машине, который будет выдавать документацию посещающим веб-браузерам. Команда **pydoc -p 1234** запустит HTTP-сервер на порту 1234, позволяя просматривать документацию по адресу `http://localhost:1234/` в вашем любимом веб-браузере. Если указать `0` в качестве номера порта, будет выбран произвольный свободный порт.3637**pydoc -b** запустит сервер и дополнительно откроет веб- браузер на странице индекса модулей. На каждой обслуживаемой странице вверху есть панель навигации, где можно *получить* справку по отдельному элементу, *выполнить поиск* по всем модулям с ключевым словом в строке аннотации, а также перейти на страницы *Module index*, *Topics* и *Keywords*.3839Когда **pydoc** создаёт документацию, он использует текущее окружение и путь для поиска модулей. Таким образом, вызов **pydoc spam** документирует именно ту версию модуля, которую вы получили бы, запустив интерпретатор Python и введя `import spam`.4041Подразумевается, что документация по основным модулям находится по адресу `https://docs.python.org/X.Y/library/`, где `X` и `Y` – номера старшей и младшей версии интерпретатора Python. Это можно переопределить, установив переменную окружения `PYTHONDOCS` на другой URL или локальный каталог, содержащий страницы справочного руководства по библиотеке.4243Изменено в версии 3.2: Добавлена опция `-b`.4445Изменено в версии 3.3: Опция командной строки `-g` была удалена.4647Изменено в версии 3.4: [`pydoc`](https://python-all.ru/3.4/library/pydoc.html#module-pydoc) теперь использует [`inspect.signature()`](https://python-all.ru/3.4/library/inspect.html#inspect.signature) вместо [`inspect.getfullargspec()`](https://python-all.ru/3.4/library/inspect.html#inspect.getfullargspec) для извлечения информации о сигнатуре вызываемых объектов.48