Docstrings — строки документации в функциях Python
В этом руководстве вы узнаете, как сделать и использовать строки документации (docstrings) для добавления документации к функции в Python.
Введение в функцию help()
Python предоставляет встроенную функцию help(), которая позволяет отображать документацию по функции.
В следующем примере показана документация функции print():
help(print)
Выход:
print(...)
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.
Обратите внимание, что вы можете использовать функцию help() для отображения документации по модулям, классам, функциям и ключевым словам. В этом руководстве рассматривается только документация по функциям.
Использование docstrings для документирования функций
Для документирования ваших функций вы можете использовать строки документации. PEP 257 предоставляет соглашения о строках документации.
Если первая строка тела функции является строкой, Python интерпретирует ее как строку документации. Например:
def add(a, b):
"Return the sum of two arguments"
return a + b
И вы можете использовать функцию help(), чтобы найти документацию по функции add():
help(add)
Выход:
add(a, b)
Return the sum of two arguments
Обычно вы используете многострочные строки документации:
def add(a, b):
""" Add two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
"""
return a + b
Выход:
add(a, b)
Add the two arguments
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two arguments
Python хранит строки документации в свойстве __doc__ функции.
В следующем примере показано, как получить доступ к свойству __doc__ функции add():
add.__doc__
Заключение
- Используйте функцию help(), чтобы получить документацию по функции.
- Поместите строку (однострочную или многострочную) в качестве первой строки функции, чтобы добавить к ней документацию.