pydoc.md

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