Доступ к документации Python

При установке Python на локальный диск также устанавливается полная документация в формате CHM. Для ее открытия необходимо в меню Пуск активировать раздел Python и выбрать пункт  Python 3.10 Manuals.

Если в данном меню выбрать пункт Python 3.10 Module Docs, то будет запущен встроенный сервер документов pydoc. Модуль написан на Python и обеспечивает удобный просмотр документации при помощи стороннего обозревателя.

При запуске pydoc также запускается обозреватель, в котором будет выведен перечень всех доступных модулей. При клике на выбранный пункт откроется страница с более детальной информацией – описание функций, констант и классов данного модуля.

Для завершения работы pydoc необходимо перейти в его окно и активировать команду q (сокращение от quit) и подтвердить ввод при помощи клавиши Enter. Сервер будет автоматически закрыт, окно также будет деактивировано. Если ввести команду b (browser), то в обозреватель будет повторно выведена стартовая страница с перечнем всех модулей.

Документацию по отдельным языковым конструкциям также можно получить, вызвав функцию help(). При этом можно получить информацию не только по отдельной функции, но и по всему модулю. Однако его необходимо предварительно подключить.

>>> import builtins
>>> help(builtins)

Ранее упоминалось, что для комментирования кода можно использовать строки документирования. Такие элементы сохраняются в атрибуте __doc__  и в дальнейшем могут использоваться функцией help().

Для демонстрации работы необходимо создать файл test.py со следующим содержимым:

""" Это описание нашего модуля """
def func():
    """ Это описание функции"""
    Pass

Далее подключим созданный модуль и выведем строки документирования. Для этого можно использовать следующий код:

import test3 # Подключаем файл test3.py
help(test3)
input()

Если запустить приложение, то отобразится примерно такой результат:

Help on module test3:
NAME
    test3 - Это описание нашего модуля
FUNCTIONS
    func()
        Это описание функции
FILE
    d:\data\документы\работа\test3.py

Также можно получить строки документирования при помощи атрибута __doc__. Для этого используется следующий код:

import test3 #Подключаем файл
print(test3.__doc__)
print(test3.func.__doc__)
input()

Результат выполнения:

Это описание нашего модуля
Это описание функции

Атрибут __doc__ также можно успешно использовать в качестве альтернативы функции help(). Далее будет приведен пример получения документации от функции input():

>>> print(input.__doc__)

В ответ будет выведен следующий код:

Read a string from standard input. The trailing newline is stripped.

The prompt string, if given, is printed to standard output without a

trailing newline before reading input.

If the user hits EOF (*nix: Ctrl-D, Windows: Ctrl-Z+Return), raise EOFError.

On *nix systems, readline is used if available.

Для получения полного списка всех идентификаторов внутри нужного модуля можно использовать функцию dir(). Пример использования:

import test3 # Подключаем файл test3.py
print(dir(test3))
input()

Результат выполнения:

['__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'func']

Также предоставляется возможность получить список встроенных идентификаторов:

>>> import builtins
>>> print(dir(builtins))

Если вызвать dir() без параметров, будет выведен перечень идентификаторов из текущего модуля:

>>> print(dir())

Полученный результат:

['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', '__package__', '__spec__']