Docstrings python что это
Docstrings: документирование кода в Python
Хочешь знать больше о Python?
Подпишись на наш канал о Python в Telegram!
В статье, опубликованной на сайте pythonist.ru, рассмотрены строки документации в Python. Давайте разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
Примечание. Мы используем тройные кавычки для многострочных строк.
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
Принимает число n, возвращает квадрат числа n
Теперь давайте посмотрим на строки документации для встроенной функции print() :
Пример 3: строки документации для встроенной функции print().
Здесь мы можем видеть, что документация функции print() представлена как атрибут __doc__ этой функции.
Однострочные строки документации в Python
Однострочные строки документации должны помещаться на одной строке.
Стандартные соглашения для написания однострочных строк документации:
Давайте посмотрим на пример ниже.
Пример 4: Однострочная строка документации для функции.
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
Строки документации пишутся в начале файла Python.
Пример 4: строки документации модуля Python.
2. Строки документации для функций Python
Пример 5: строки документации для функций Python.
3. Строки документации для классов Python
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
Мы можем использовать следующий код для доступа только к строкам документации класса Person :
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Docstrings: документирование кода в Python
В этой статье мы рассмотрим строки документации в Python, а также разберемся, как и зачем их использовать.
Строки документации (docstrings) в Python — это строковые литералы, которые пишутся сразу после определения функции, метода, класса или модуля. Давайте рассмотрим пример.
Пример 1: Строки документации.
Здесь строковый литерал:
Принимает число n, возвращает квадрат числа n
Комментарии vs строки документации Python
Комментарии Python
Комментарии — это описания, которые помогают программистам лучше понять назначение и функциональность программы. Они полностью игнорируются интерпретатором Python.
В Python мы используем символ # для написания однострочного комментария. Например,
Комментарии Python с использованием строк
Если мы не присваиваем строки какой-либо переменной, они ведут себя как комментарии. Например,
Строки документации Python
Как упоминалось выше, строки документации в Python — это строки, которые пишутся сразу после определения функции, метода, класса или модуля (как в примере 1). Они используются для документирования нашего кода.
Атрибут __doc__
Всякий раз, когда строковые литералы присутствуют сразу после определения функции, модуля, класса или метода, они становятся специальным атрибутом __doc__ этого объекта. Позже мы можем использовать этот атрибут для получения этой строки документации.
Пример 2: Вывод на экран строки документации.
Принимает число n, возвращает квадрат числа n
Теперь давайте посмотрим на строки документации для встроенной функции print() :
Пример 3: строки документации для встроенной функции print().
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: Однострочная строка документации для функции.
Многострочные строки документации в Python
Многострочные строки документации состоят из резюмирующей однострочной строки документации, за которой следует пустая строка, а затем более подробное описание.
Документ PEP 257 предоставляет стандартные соглашения для написания многострочных строк документации для различных объектов.
Некоторые из них перечислены ниже:
1. Строки документации для модулей Python
Строки документации пишутся в начале файла Python.
Пример 4: строки документации модуля Python.
Create portable serialized representations of Python objects.
See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.
2. Строки документации для функций Python
Пример 5: строки документации для функций Python.
Возвращает сумму двух десятичных чисел в двоичном формате.
a (int): первое десятичное целое число
b (int): второе десятичное целое число
binary_sum (str): двоичная строка суммы a и b
3. Строки документации для классов Python
Пример 6: строки документации для класса Python.
Предположим, у нас есть файл Person.py со следующим кодом:
Мы можем использовать следующий код для доступа только к строкам документации класса Person :
Класс для представления человека.
Печатает имя и возраст человека.
Использование функции help() для строк документации
Мы также можем использовать функцию help() для чтения строк документации, связанных с различными объектами.
Пример 7: чтение строк документации с помощью функции help().
Мы можем использовать функцию help() для класса Person из Примера 6:
Результат:
Help on class Person in module __main__:
Здесь мы видим, что функция help() получает строки документации класса Person вместе с методами, связанными с этим классом.
4. Строки документации для скриптов Python
5. Строки документации для пакетов Python
Строки документации для пакета Python записываются в файл __init__.py пакета. Они должны содержать все доступные модули и подпакеты, экспортируемые пакетом.
Форматы строк документации
Мы можем писать строки документации во многих форматах, таких как reStructured text (reST), формат Google или формат документации NumPy. Чтобы узнать больше, перейдите по ссылке.
Мы также можем генерировать документацию из строк документации, используя такие инструменты, как Sphinx. Чтобы узнать больше, смотрите официальную документацию Sphinx.
Учимся писать строки документации в Python
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.
Лучшие практики
Однострочные докстринги
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
Синтаксис Sphinx
Макет Sphynx
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
Python Docstring – вещи, которые вы должны знать
Python Docstring окружен пара тройных двойных кавычек («»). Давайте посмотрим на некоторые примеры определения Docstrings.
Python Docstring – вещи, которые вы должны знать
Строка документов Python (DOCSTRING) – это строковый литерал, который является первым утверждением в модуле, функции, классе или способе.
Как определить Python Docstring?
Python Docstring окружен пара тройных двойных кавычек («»). Давайте посмотрим на некоторые примеры определения Docstrings.
1. Пример функции Python Docstring
2. Пример DocString класса Python
3. Пример Docstring модуль Python
Скажем, мы определили выше функцию и класс в DocStrings.py файл. Каждый сценарий Python также является модулем. Мы можем определить этот модуль DOCSTRING AS:
Как получить доступ к Python Docstrings?
Мы можем получить доступ к значению DocString из специального атрибута __doc__. Давайте посмотрим, как получить доступ к значениям DOCSTRING, определенных выше.
1. Доступ к функции Python Docstring
2. Доступ к классу Python и метод Docstrings
3. Доступ к модулю Python Docstring
Нам придется импортировать модуль Docstrings. Затем мы можем получить доступ к его значению DOCSTRING, используя атрибут __doc__. Мы прокомментировали вышеперечисленные операторы печати, прежде чем импортировать модуль DocStrings, чтобы избежать выполнения операторов Print ().
Python One-LiLER DOCSTRING
Python Multi-Line Docstring
Python Docstring лучшие практики
Почему вы должны следовать рекомендациям Python DocString?
Python Docstrings можно получить доступ к атрибуту __doc__. Очень легко построить систему для разбора DOCSTRING и генерировать документацию проектных модулей, классов и функций. Вот почему вы должны следовать рекомендациям DOCSTRING, выложенные в Pep-257 Отказ
Можем ли мы использовать DocString для многостроительного комментария?
Я видел много случаев, когда DOCSTRING злоупотребляет, обеспечивая многословные комментарии. Python не поддерживает многослойные комментарии. Если вы хотите, чтобы комментарий был распространен на несколько строк, начните каждую строку с помощью HASH HACKER. Не злоупотребляйте Python Docstrings.
Использование docstring в Python
Подробное руководство по применению docstring в языке программирования Python.
Введение
Docstring — это аннотация к вашему коду. Она может быть как в виде одной строки, так и многострочной.
Так же docstring используется для формирования справочных элементов в средах разработки.
Использование docstring в функциях
Рассмотрим на примере. У нас есть функция под названием «get_hypotenuse»:
Запросим помощь по данной функции:
Увидим следующее сообщение:
Именно так выглядит строка dosctring в справочной информации по указанной функции.
Расположение
Самый первый оператор в функции «get_hypotenuse» — это многострочная строка:
Я думаю, вы заметили, что эта строка каким-то образом отображается как документация.
Обратите внимание, что это не комментарий.
Комментарии в Python выглядят по-другому:
Более подробно ознакомиться с использованием комментариев можно в моей публикации.
Вернемся к docstring, перед нами многострочная строка, которую мы написали и она используется для документирования функции:
Эта строка называется docstring. Он действует как документация для этой функции, исходя от того, где она находится и что она из себя представляет.
Если я перемещу эту строку ниже нашего оператора return:
А потом я снова обращусь за помощью к нашей функции «get_hypotenuse»:
Мы видим, что сейчас нет никакой документации для этой функции.
Строка документации должна быть самым первым оператором внутри функции. Она не может быть частью какого-то выражения. Например, строка документации не может быть оператором присваивания:
Строка документации должна быть прописана отдельно и в самом начале функции.
Использование тройных кавычек
Что, если я возьму эту многострочную строку и удалю тройные кавычки, превратив ее в однострочную строку:
А если я сейчас попрошу помощи у функции «get_hypotenuse», я все равно увижу нашу строку документа?
Руководство по стилю
Очень часто можно увидеть тройные кавычки, используемые для строк документации, но использование тройных кавычек для строк документов — это просто условность. Это соглашение, которое продиктовано PEP 257.
PEP 257 говорит, что вы должны использовать тройные кавычки, чтобы их было легко превратить в многострочные строки.
Еще одна причина, по которой я предпочитаю использовать многострочные строки для docstring, заключается в том, что они выделяются немного больше: эти тройные кавычки бросаются мне в глаза.
PEP 257 также отмечает: чтобы начать свои строки с заглавной буквы, используйте императивное время (что означает «return», вместо «returns»).
Взгляните на PEP 257, если вы пытаетесь найти какую-то лучшую практику для написания собственных строк документов на Python.
Атрибут __doc__
Итак, если самый первый оператор в любой функции — это строка то это docstring. Python будет читать строки документации и отображать их всякий раз, когда вам понадобиться помощь по этой функции.
На самом деле, в Python существует аттрибут функции __doc__ который позволяет прочитать вашу строку документации:
Использование docstring в классах
Строки документации используются точно так же и в классах.
У нас есть класс под названием «Point»:
Самый первый оператор в классе «Point» — это строка.
Если я запрошу помощь по этому классу, то я увижу эту строку документа:
Фактически, именно так работает функция HELP в целом.
Если вы обратитесь за помощью к объекту, Python будет искать строку документации этого объекта.
Использование docstring в модулях
Даже модули могут иметь строки документов.
У нас есть модуль под названием «hi.py», он начинается со строки:
Если мы импортируем этот модуль «hi» и попросим о помощи по нему, то увидим строку docstring для этого модуля:
Заключение
Теперь вы знаете, что, если самый первый оператор в функции, модуле или классе — это строка, независимо от того, является ли она многострочной строкой или нет, это строка docstring.
Эта строка документации будет прочитана Python, проанализирована Python и присоединена к объекту, чтобы действовать как документация для этого объекта.
Рекомендуется использовать docstring для документирования кода, а не комментирования. Комментарии игнорируются Python, а строки документов — нет.
И если видите строку docstring в коде, обратите внимание, что она имеет особое значение: не перемещайте ее ко второму оператору функции, потому что это ее сломает.
Храните свои строки документов в качестве первого оператора в ваших классах, модулях и функциях, чтобы Python мог их прочитать.