В этой статье мы рассмотрим строки документации в Python, а также разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
def square(n): '''Принимает число n, возвращает квадрат числа n''' return n**2
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Внутри тройных кавычек находится строка документации функции square()
, которая размещена сразу после ее определения.
Примечание. Вы можете использовать как тройные двойные кавычки """
, так и тройные одинарные кавычки '''
для создания строк документации. Используйте r"""
, если вы применяете обратный слэш в ваших строках документации. Для строк документации Unicode используйте u"""
.
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ #
для написания однострочного комментария. Например,
# Программа для вывода на экран строки "Hello World" print("Hello World")
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
"Я однострочный комментарий" ''' Я многострочный комментарий! ''' print("Hello World")
Примечание. Мы используем тройные кавычки для многострочных строк.
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Мы можем получить доступ к этим строкам документации, используя атрибут __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__
этой функции.
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
def multiplier(a, b): """Принимает два числа, возвращает их произведение.""" return a*b
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
Строки документации пишутся в начале файла 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__
.
Пример 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__
.
Пример 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()
для чтения строк документации, связанных с различными объектами.
Пример 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 вместе с методами, связанными с этим классом.
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Python предлагает набор библиотек, удовлетворяющих различные потребности в визуализации, будь то академические исследования, бизнес-аналитика или…
В Python для представления данных в двоичной форме можно использовать байты. Из этой статьи вы…
В этой статье рассказывается о том, что такое Werkzeug и как Flask использует его для…
При работе с датами часто возникает необходимость прибавлять к дате или вычитать из нее различные…
В этом руководстве мы рассмотрим, как добавить социальную аутентификацию с помощью GitHub и Google в…
В этой статье мы рассмотрим, что такое подсказки типов и чем они могут быть полезны.…