Использование docstring в Python

Подробное руководство по применению docstring в языке программирования Python.

Введение

Docstring — это аннотация к вашему коду. Она может быть как в виде одной строки, так и многострочной.

Так же docstring используется для формирования справочных элементов в средах разработки.

Использование docstring в функциях

Рассмотрим на примере. У нас есть функция под названием «get_hypotenuse»:

from math import sqrt


def get_hypotenuse(a, b):
    """Return right triangle hypotenuse, given its other two sides."""
    return sqrt(a**2 + b**2)

Запросим помощь по данной функции:

>>>> help(get_hypotenus)

Увидим следующее сообщение:

get_hypotenuse(a, b)
     Return right triangle hypotenuse, given its other two sides.

Именно так выглядит строка dosctring в справочной информации по указанной функции.

Расположение

Самый первый оператор в функции «get_hypotenuse» — это многострочная строка:

def get_hypotenuse(a, b):
    """Return right triangle hypotenuse, given its other two sides."""
    return sqrt(a2 + b2)

Я думаю, вы заметили, что эта строка каким-то образом отображается как документация.

Обратите внимание, что это не комментарий.

Комментарии в Python выглядят по-другому:

def get_hypotenuse(a, b):
     # A comment

Более подробно ознакомиться с использованием комментариев можно в моей публикации.

Вернемся к docstring, перед нами многострочная строка, которую мы написали и она используется для документирования функции:

"""
Return right triangle hypotenuse, given its other two sides.
"""

Эта строка называется docstring. Он действует как документация для этой функции, исходя от того, где она находится и что она из себя представляет.

Если я перемещу эту строку ниже нашего оператора return:

def get_hypotenuse(a, b):
    return sqrt(a2 + b2)
    "Return right triangle hypotenuse, given its other two sides."

А потом я снова обращусь за помощью к нашей функции «get_hypotenuse»:

>>> help(get_hypotenuse)

Мы видим, что сейчас нет никакой документации для этой функции.

Строка документации должна быть самым первым оператором внутри функции. Она не может быть частью какого-то выражения. Например, строка документации не может быть оператором присваивания:

from math import sqrt

def get_hypotenuse(a, b):
    z = """Return right triangle hypotenuse, given its other two sides."""
    return sqrt(a2 + b2)

Строка документации должна быть прописана отдельно и в самом начале функции.

Использование тройных кавычек

Что, если я возьму эту многострочную строку и удалю тройные кавычки, превратив ее в однострочную строку:

def get_hypotenuse(a, b):
    "Return right triangle hypotenuse, given its other two sides."
    return sqrt(a2 + b2)

А если я сейчас попрошу помощи у функции «get_hypotenuse», я все равно увижу нашу строку документа?

>>> help(get_hypotenuse)

Мы её увидим!

get_hypotenuse(a, b)
     Return right triangle hypotenuse, given its other two sides.

Руководство по стилю

Очень часто можно увидеть тройные кавычки, используемые для строк документации, но использование тройных кавычек для строк документов — это просто условность. Это соглашение, которое продиктовано PEP 257.

PEP 257 говорит, что вы должны использовать тройные кавычки, чтобы их было легко превратить в многострочные строки.

Еще одна причина, по которой я предпочитаю использовать многострочные строки для docstring, заключается в том, что они выделяются немного больше: эти тройные кавычки бросаются мне в глаза.

PEP 257 также отмечает: чтобы начать свои строки с заглавной буквы, используйте императивное время (что означает «return», вместо «returns»).

Взгляните на PEP 257, если вы пытаетесь найти какую-то лучшую практику для написания собственных строк документов на Python.

Атрибут __doc__

Итак, если самый первый оператор в любой функции — это строка то это docstring. Python будет читать строки документации и отображать их всякий раз, когда вам понадобиться помощь по этой функции.

На самом деле, в Python существует аттрибут функции __doc__ который позволяет прочитать вашу строку документации:

>>> get_hypotenuse.__doc__
Return right triangle hypotenuse, given its other two sides.

Использование docstring в классах

Строки документации используются точно так же и в классах.

У нас есть класс под названием «Point»:

class Point:
     """A 3-dimensional point."""
     def init(self, x, y, z):
         self.x, self.y, self.z = x, y, z

Самый первый оператор в классе «Point» — это строка.

Если я запрошу помощь по этому классу, то я увижу эту строку документа:

>>> help(Point)

class Point(builtins.object)
| Point(x, y, z)
|
| A 3-dimensional point.
|
| Methods defined here:
|
| __init__(self, x, y, z)
|   Initialize self. See help (type(self)) for accurate signature.
|

Фактически, именно так работает функция HELP в целом.

Если вы обратитесь за помощью к объекту, Python будет искать строку документации этого объекта.

Использование docstring в модулях

Даже модули могут иметь строки документов.

У нас есть модуль под названием «hi.py», он начинается со строки:

"""Hi there!"""

name = "Trey" 
x = 4

Если мы импортируем этот модуль «hi» и попросим о помощи по нему, то увидим строку docstring для этого модуля:

import hi

help(hi)
NAME
    hi - Hi there!
DATA
    name = 'Trey'
    x = 4
FILE
    /home/trey/hi.py

Заключение

Теперь вы знаете, что, если самый первый оператор в функции, модуле или классе — это строка, независимо от того, является ли она многострочной строкой или нет, это строка docstring.

Эта строка документации будет прочитана Python, проанализирована Python и присоединена к объекту, чтобы действовать как документация для этого объекта.

Рекомендуется использовать docstring для документирования кода, а не комментирования. Комментарии игнорируются Python, а строки документов — нет.

И если видите строку docstring в коде, обратите внимание, что она имеет особое значение: не перемещайте ее ко второму оператору функции, потому что это ее сломает.

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