Строки документации (Docstrings) в Python
Docstrings в Python — это строковые литералы, которые появляются сразу после определения функции, метода, класса или модуля. Рассмотрим пример.
Пример 1: Docstrings
def square(n):
'''Take a number n and return the square of n.'''
return n**2
Строковый литерал внутри тройных кавычек — это docstring функции square(), так как он находится сразу после её определения.
Примечание
Мы также можем использовать тройные """ кавычки для создания docstrings.
Комментарии vs Docstrings
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять намерения и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python для написания однострочного комментария мы используем символ #. Например,
# Program to print "Hello World"
print("Hello World")
Python-комментарии с использованием строк
Если мы не присваиваем строки никакой переменной, они действуют как комментарии. Например,
"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print("Hello World")
Python docstrings
Docstrings Python используются сразу после определения функции, метода, класса или модуля. Они используются для документирования кода. Мы можем получить доступ к этим docstrings через атрибут __doc__.
Атрибут __doc__ в Python
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они связываются с объектом как его атрибут __doc__. Позже мы можем использовать этот атрибут для получения этой docstring.
Пример 2: Печать docstring
def square(n):
'''Take a number n and return the square of n.'''
return n**2
print(square.__doc__)
Вывод
Take a number n and return the square of n.
Здесь документация нашей функции square() доступна через атрибут __doc__.
Пример 3: Docstrings для встроенной функции 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__ этой функции.
Однострочные docstrings в Python
Однострочные docstrings — это документы, которые помещаются на одной строке.
Стандартные соглашения для написания однострочных docstrings:
Даже если они однострочные, мы по-прежнему используем тройные кавычки вокруг этих docstrings, так как их можно легко расширить позже.
Закрывающие кавычки находятся на той же строке, что и открывающие.
Нет пустой строки ни до, ни после docstring.
Они не должны быть описательными, а должны следовать структуре «Сделай это, верни то», заканчиваясь точкой.
Пример 4: Однострочные docstrings для функции
def multiplier(a, b):
"""Take two numbers and return their product."""
return a*b
Многострочные Docstrings в Python
Многострочные docstrings состоят из строки-сводки, как и однострочная docstring, за которой следует пустая строка, за которой следует более подробное описание.
Документ PEP 257 содержит стандартные соглашения для написания многострочных docstrings для различных объектов.
1. Docstrings для модулей Python
Docstrings для модулей Python должны перечислять все доступные классы, функции, объекты и исключения, которые импортируются при импорте модуля.
Они также должны иметь однострочную сводку для каждого элемента.
Они пишутся в начале файла Python.
Пример 4: Docstrings модуля Python
import pickle
print(pickle.__doc__)
Вывод — будет напечатано описание модуля, его классов (Pickler, Unpickler), функций (dump, dumps, load, loads) и переменных, заданное в начале файла модуля.
2. Docstrings для функций Python
Docstring для функции или метода должна обобщать её поведение и документировать её аргументы и возвращаемые значения.
Она также должна перечислять все исключения, которые могут быть подняты, и другие необязательные аргументы.
Пример 5: Docstrings для функций Python
def add_binary(a, b):
'''
Return the sum of two decimal numbers in binary digits.
Parameters:
a (int): A decimal integer
b (int): Another decimal integer
Returns:
binary_sum (str): Binary string of the sum of a and b
'''
binary_sum = bin(a+b)[2:]
return binary_sum
print(add_binary.__doc__)
Как видите, мы включили краткое описание того, что делает функция, параметры, которые она принимает, и значение, которое она возвращает. Строковый литерал внедрён в функцию add_binary как её атрибут __doc__.
3. Docstrings для классов Python
Docstrings для классов должны обобщать его поведение и перечислять публичные методы и переменные экземпляра.
Подклассы, конструкторы и методы должны иметь свои собственные docstrings.
Пример 6: Docstrings для класса Python
class Person:
"""
A class to represent a person.
Attributes
----------
name : str
first name of the person
surname : str
family name of the person
age : int
age of the person
Methods
-------
info(additional=""):
Prints the person's name and age.
"""
def __init__(self, name, surname, age):
"""
Constructs all the necessary attributes for the person object.
"""
self.name = name
self.surname = surname
self.age = age
def info(self, additional=""):
"""
Prints the person's name and age.
"""
print(f'My name is {self.name} {self.surname}. I am {self.age} years old.' + additional)
Мы можем получить доступ только к docstring класса:
print(Person.__doc__)
Использование функции help() для Docstrings
Мы также можем использовать функцию help() для чтения docstrings, связанных с различными объектами.
help(Person)
Функция help() извлекает docstrings класса вместе с методами, связанными с этим классом.
4. Docstrings для скриптов Python
Docstring для скрипта Python должна документировать функции скрипта и синтаксис командной строки как пригодное для использования сообщение.
Она должна служить быстрым справочником ко всем функциям и аргументам.
5. Docstrings для пакетов Python
Docstrings для пакета Python пишется в файле __init__.py пакета.
Она должна содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы Docstring
Мы можем писать docstring во многих форматах, таких как формат reStructured text (reST), формат Google или формат документации NumPy. Мы также можем генерировать документацию из docstrings с помощью инструментов вроде Sphinx.