В этой статье мы рассмотрим строки документации в Python, а также разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
def square(n):
'''Принимает число n, возвращает квадрат числа n'''
return n**2
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Внутри тройных кавычек находится строка документации функции square(), которая размещена сразу после ее определения.
Примечание. Вы можете использовать как тройные двойные кавычки """, так и тройные одинарные кавычки ''' для создания строк документации. Используйте r""", если вы применяете обратный слэш в ваших строках документации. Для строк документации Unicode используйте u""".
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
# Программа для вывода на экран строки "Hello World"
print("Hello World")
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
"Я однострочный комментарий"
'''
Я
многострочный
комментарий!
'''
print("Hello World")
Примечание. Мы используем тройные кавычки для многострочных строк.
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Мы можем получить доступ к этим строкам документации, используя атрибут __doc__.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
def square(n):
'''Принимает число n, возвращает квадрат числа n'''
return n**2
print(square.__doc__)
Результат:
Принимает число n, возвращает квадрат числа n
Здесь мы получили доступ к документации нашей функции square() с помощью атрибута __doc__.
Теперь давайте посмотрим на строки документации для встроенной функции print():
Пример 3: строки документации для встроенной функции print().
print(print.__doc__)
Результат:
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.
Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.
Однострочные строки документации в Python
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
- Несмотря на то, что они однострочные, мы по-прежнему используем тройные кавычки вокруг этих строк документации, тогда их можно будет легко расширить позже.
- Закрывающие кавычки находятся на той же строке, что и открывающие кавычки.
- Не нужно добавлять пустую строку ни перед, ни после строки документации.
- Они не должны быть описательными, скорее они должны следовать структуре «Делает это, возвращает это», заканчивающейся точкой.
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
def multiplier(a, b):
"""Принимает два числа, возвращает их произведение."""
return a*b
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
- Строки документации для модулей Python должны содержать список всех доступных классов, функций, объектов и исключений, которые импортируются при импорте модуля.
- Они также должны содержать краткое пояснение (в одну строку) для каждого элемента из этого списка.
Строки документации пишутся в начале файла Python.
Давайте посмотрим на строки документации для встроенного модуля pickle.
Пример 4: строки документации модуля Python.
import pickle print(pickle.__doc__)
Результат:
Create portable serialized representations of Python objects.
See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.
Classes:
Pickler
Unpickler
Functions:
dump(object, file)
dumps(object) -> string
load(file) -> object
Мы убедились, что строка документации, записанная в начале файла модуля pickle.py, может быть получена при помощи атрибута __doc__.
2. Строки документации для функций Python
- Строки документации для функции или метода должны обобщать их поведение и документировать их аргументы и возвращаемые значения.
- Следует также перечислить все исключения, которые могут быть возбуждены методом/функцией и другие необязательные аргументы.
Пример 5: строки документации для функций Python.
def add_binary(a, b):
'''
Возвращает сумму двух десятичных чисел в двоичном формате.
Параметры:
a (int): первое десятичное целое число
b (int): второе десятичное целое число
Возвращаемое значение:
binary_sum (str): двоичная строка суммы a и b
'''
binary_sum = bin(a+b)[2:]
return binary_sum
print(add_binary.__doc__)
Результат:
Возвращает сумму двух десятичных чисел в двоичном формате.
Параметры:
a (int): первое десятичное целое число
b (int): второе десятичное целое число
Возвращаемое значение:
binary_sum (str): двоичная строка суммы a и b
Как видите, мы добавили краткое описание того, что делает функция, параметры, которые она принимает, и значение, которое она возвращает. Строковый литерал добавляется в функцию add_binary как ее атрибут __doc__.
3. Строки документации для классов Python
- Строки документации для класса должны обобщать его поведение и перечислять открытые (public) методы и переменные экземпляра.
- Подклассы, конструкторы и методы должны иметь свои собственные строки документации.
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
class Person:
"""
Класс для представления человека.
...
Атрибуты
--------
name : str
имя человека
surname : str
фамилия человека
age : int
возраст человека
Методы
------
info(additional=""):
Печатает имя и возраст человека.
"""
def __init__(self, name, surname, age):
"""
Устанавливает все необходимые атрибуты для объекта person.
Параметры
---------
name : str
имя человека
surname : str
фамилия человека
age : int
возраст человека
"""
self.name = name
self.surname = surname
self.age = age
def info(self, additional=""):
"""
Печатает имя и возраст человека.
Если аргумент 'additional' передан, то он добавляется после основной информации.
Параметры
---------
additional : str, optional
Дополнительная информация для отображения (по умолчанию None)
Возвращаемое значение
---------------------
None
"""
print(f'My name is {self.name} {self.surname}. I am {self.age} years old.' + additional)
Мы можем использовать следующий код для доступа только к строкам документации класса Person:
print(Person.__doc__)
Результат:
Класс для представления человека.
...
Атрибуты
--------
name : str
имя человека
surname : str
фамилия человека
age : int
возраст человека
Методы
------
info(additional=""):
Печатает имя и возраст человека.
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
help(Person)
Результат:Help on class Person in module __main__: class Person(builtins.object) | Класс для представления человека. | | ... | | Атрибуты | -------- | name : str | имя человека | surname : str | фамилия человека | age : int | возраст человека | | Методы | ------ | info(additional=""): | Печатает имя и возраст человека. | Methods defined here: | | __init__(self, name, surname, age) | Устанавливает все необходимые атрибуты для объекта person. | | Параметры | --------- | name : str | имя человека | surname : str | фамилия человека | age : int | возраст человека | | info(self, additional='') | Печатает имя и возраст человека. | | Если аргумент additional передан, то он добавляется после основной информации.| | Параметры | --------- | additional : str, optional | Дополнительная информация для отображения (по умолчанию None) | | Возвращаемое значение | --------------------- | None | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined)
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
Друзья, подписывайтесь на наш телеграм канал Pythonist. Там еще больше туториалов, задач и книг по Python.
- Строки документации для скрипта Python должны документировать функции скрипта и синтаксис командной строки, переменные среды и файлы.
- Строки документации скрипта должны использоваться в качестве «сообщения по использованию», которое выводится, когда скрипт вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией «-h», для «help»).
- Они должны служить краткой ссылкой на все функции и аргументы.
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
