Документирование функций Python с помощью Docstrings

Введение

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

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

Доступ к документации с помощью help()

Строковая документация (docstring) — это строковый литерал, который является первым оператором в определении модуля, функции, класса или метода. Он используется для документирования того, что делает код. Встроенная функция Python help() — это превосходный инструмент для просмотра этой документации в чистом, удобочитаемом формате. Функция help() предназначена для интерактивного использования.

Начнем с просмотра документации для встроенной функции print().

Сначала откройте терминал в WebIDE. Вы можете сделать это, нажав меню Terminal в верхней части экрана и выбрав New Terminal.

В терминале запустите интерактивную оболочку Python, введя следующую команду и нажав Enter:

python

Вы увидите приглашение Python (>>>). Теперь используйте функцию help(), чтобы получить информацию о print():

help(print)

В терминале будет отображена документация для функции print.

Help on built-in function print in module builtins:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    Prints the values to a stream, or to sys.stdout by default.

    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

(END)

Этот вывод объясняет, что делает функция, какие параметры она принимает и их значения по умолчанию. Нажмите клавишу q, чтобы выйти из средства просмотра справки и вернуться к приглашению Python.

Теперь выйдите из интерактивной оболочки Python, введя:

exit()

Доступ к необработанным Docstrings с помощью __doc__

Хотя help() отлично подходит для интерактивного использования, вы также можете программно получить доступ к необработанной строковой документации объекта, используя его специальный атрибут __doc__. Этот атрибут хранит docstring в виде простой строки.

Посмотрим, как это работает. В проводнике файлов WebIDE слева найдите и откройте файл с именем access_docstring.py.

Добавьте следующий код на Python в файл. Этот код выведет строковую документацию встроенной функции len().

## This script prints the docstring of the len() function.
print(len.__doc__)

Сохраните файл (вы можете использовать сочетание клавиш Ctrl+S).

Теперь вернитесь в терминал и запустите скрипт следующей командой:

python access_docstring.py

В результате будет выведена необработанная строковая документация для функции len.

Return the number of items in a container.

Как видите, __doc__ предоставляет вам прямое строковое содержимое документации, что может быть полезно для пользовательских инструментов или скриптов, обрабатывающих документацию.

Написание пользовательского Docstring для функции

Документирование собственных функций является фундаментальной практикой для написания чистого и поддерживаемого кода. Хорошая docstring объясняет назначение функции, ее параметры и то, что она возвращает.

Давайте напишем функцию и задокументируем ее. Откройте файл my_function.py в проводнике файлов.

Сначала добавьте следующее определение функции в файл:

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Теперь добавим docstring. Docstring должен располагаться сразу после строки def и иметь тот же уровень отступа, что и код функции. Мы будем использовать тройные кавычки ("""...""") для многострочной docstring.

Измените my_function.py, чтобы включить docstring. Мы также добавим строку для вывода docstring, чтобы убедиться, что все работает.

def greet(name, greeting="Hello"):
    """Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".
    """
    print(f"{greeting}, {name}!")

## Print the docstring of our greet function
print(greet.__doc__)

Сохраните файл. Теперь запустите скрипт из терминала:

python my_function.py

Вы увидите, как ваша пользовательская docstring будет выведена в консоль.

Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

Это подтверждает, что вы успешно задокументировали свою функцию и можете получить доступ к ее docstring с помощью атрибута __doc__.

Использование help() с вашей пользовательской функцией

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

Мы импортируем нашу функцию greet в интерактивную оболочку Python, чтобы использовать help().

В терминале снова запустите оболочку Python:

python

Как только вы увидите приглашение >>>, импортируйте функцию greet из вашего модуля my_function (имя файла my_function.py рассматривается как модуль с именем my_function).

from my_function import greet

Теперь используйте help() для просмотра документации вашей функции greet:

help(greet)

Вы увидите красиво отформатированный вывод, сгенерированный из вашей docstring.

Help on function greet in module my_function:

greet(name, greeting='Hello')
    Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

(END)

Обратите внимание, как help() автоматически включает сигнатуру функции (greet(name, greeting='Hello')) и форматирует docstring для удобства чтения. Вот почему написание хороших docstrings так ценно — оно напрямую интегрируется со встроенной системой помощи Python.

Нажмите q, чтобы выйти из средства просмотра справки, а затем введите exit(), чтобы покинуть оболочку Python.

Резюме

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