Что такое docstring в 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.
Использование 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 мог их прочитать.
Учимся писать строки документации в Python
May 28, 2020 · 4 min read
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.
Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.
М ы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.
Что такое докстринг?
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками «»» «»» в начале модуля, класса, метода или функции, который описывает, что делает функция.
Лучшие практики
Однострочные докстринги
Многострочные докстринги
Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Стиль Sphinx
Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter.
Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:
Синтаксис Sphinx
Макет Sphynx
Общий макет этой строки документации показан ниже.
Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.
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.
PEP 257 на русском. (Соглашение о Docstrings)
Аннотация
Данный PEP документирует семантику и соглашения, связанные с использованием Python docstrings.
Обоснование
«Общепринятые соглашения обеспечивают ясность, логичность, удобство сопровождения и воспитывают хорошие программистские привычки. Но они не заставляет вас действовать против своей воли. Это Python!»
Тим Питерс на comp.lang.python, 2001-06-16
Если вы избегаете общепринятых соглашений, в худшем случае на вас посмотрят искоса. Но существуют некоторые приложения (Например, системы документирования, подобные Docutils), которые позволят вам добиться более качественного результата, если вы знаете о договорённостях и будете им следовать.
Спецификация
Что такое Docstring?
Документационная строка — это строковый литерал, являющийся первой инструкцией в определении модуля, функции, класса или метода. Такая строка становится доступна при обращении с специальному атрибуту __doc__ этого объекта.
Все библиотеки, а также функции и классы, экспортируемые ими, должны иметь docstring. Публичные методы (включая конструктор __ init__) также должны иметь документацию. Сам же пакет может быть задокументирован внутри файла __init__.py, находящегося в соответствующей ему директории.
Строковые литералы, встречающиеся в других местах кода, также могут играть роль документации. Они не распознаются Python компилятором байт-кода и недоступны в качестве атрибутов объекта во время выполнения программы (т. е. у них отсутствует информация в __ doc__ ). Но существуют два дополнительных типа документационных строк, которые извлекаются с помощью других программных средств:
Для согласованности всегда используйте «»»тройные двойные кавычки»»» вокруг документационной строки. Если вы используете символы обратной косой черты («\»), то воспользуйтесь r»»»сырая строка с двойными кавычками»»» в ваших документациях. Для docstring, содержащих Unicode символы, используйте u»»»Юникод строка в тройных двойных кавычках»»». [прим. unicode строки потеряли смысл в python 3.x]
Существует две формы docstring: однострочные и многострочный.
Однострочные документационные строки
Однострочные строки используются для очевидных случаев и они должны действительно находится на одной строке. Например:
Значение фразы «командный тон» в английском языке можно пояснить на примере словосочетаний «Return pathname» и «Returns pathname». PEP-257 просит придерживаться первого стиля, потому что он более строгий.
Этот вид документаций подходит только для функций, написанных на языке C (таких как встроенные), где самоанализ невозможен. Также стоит упомянуть о природе возвращаемого значения. Предпочтительной формой для такой документационной строки будет что-то вроде:
(И конечно-же, «Сделай X» дожно быть заменено полезным описанием!)
Да, я только что писал выше: «Документация не является простым описанием», но в оригинале Гвидо и Дэвид действительно используют одинаковое слово «description» в этих двух местах. Думаю, что не стоит слишком придираться к этому, ведь посыл и так ясен.
Многострочные документационные строки
Многострочные документации состоят из сводной строки (summary line) имеющей такую же структуру, как и однострочный docstring, после которой следует пустая линия, а затем более сложное описание. «Summary line» может быть использована средствами автоматического документирования; поэтому так важно располагать её на одной строке и после делать пропуск в одну линию. Сводная строка пишется сразу после открывающихся кавычек, но допускается сделать перенос и начать со следующей строки. [прим. после этого предложения я был счастлив, ведь находились люди, которые упорно пытались мне доказать, что делать перенос ни в коем случае нельзя 🙂 ] При этом, весь docstring должен иметь такой же отступ, как и открывающие кавычки первой строки (см. пример ниже).
Оставляйте пустую строку после всех документаций (однострочных или многострочных), которые используются в классе; вообще говоря, методы класса должны быть отделены друг от друга одной пустой линией, поэтому документационная строка класса также должна быть отделена этим способом от первого метода.
Документация скрипта (автономной программы) представляет из себя сообщение «о правильном использовании» и возможно будет напечатано, когда скрипт вызовется с неверными или отсутствующими аргументами (или же с опцией «-h», для получения «help»). Такая документационная строка должна описывать функционал и синтаксис параметров скрипта, а также переменные среды и используемые файлы. Данное сообщение может оказаться довольно сложным (мануал длиной в несколько полных экранов), но при этом оно должно быть удобным для новых пользователей, чтобы они смогли использовать команду правильно. Также мануал должен давать чёткое описание всех параметров и аргументов для более опытных пользователей.
Документация модуля должна обычно содержать список классов, исключений и функций (и любых других важных объектов), которые экспортируются при помощи библиотеки, а также однострочное пояснение для каждого из них. (Это резюме, как правило, даёт меньше деталей, чем summary line в docstring самого объекта). В документации пакета (т. е. docstring модуля в __init__.py ) следует также описать и перечислить модули и подпакеты, экспортируемые главным.
Документация функции или метода должна описывать их поведение, аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда они могут быть вызваны (если это вообще предусмотрено). Также необходимо указать необязательные аргументы. Должно быть уточнено, являются ли ключевые аргументы частью интерфейса.
Документация класса должна обобщать его поведение и перечислять открытые методы, а также переменные экземпляра. Если класс будет иметь подклассы с дополнительный интерфейсом, то этот интерфейс должен быть указан отдельно (но всё также в этой документации). Конструктор класса должен иметь свою отдельную документационную строку для метода __init__. Независимые (индивидуальные) методы должны иметь собственную документацию.
Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия. Используйте глагол «override» («переопределить»), чтобы указать факт подмены метода и что вследствие этого метод суперкласса вызываться не будет. Используйте глагол «extends» («расширяет»), если метод подкласса вызывает метод суперкласса (в дополнение к его собственному поведению).
Не используйте соглашение Emacs об упоминании аргументов функций или методов в верхнем регистре. Python чувствителен к регистру, а имена аргументов могут порой использоваться при их передаче по ключам, поэтому документация должна содержать реальные имена переменных. Лучше всего перечислять каждый аргумент в отдельной строке. Например:
Если весь docstring не помещается в строку, вы можете вынести закрывающие кавычки на отдельную линию. Таким образом, можно будет использовать Emacs команду: fill-paragraph
Обработка Docstring
Инструменты обработки документационных строк должны удалять одинаковое количество отступов, равное минимальному отступу всех не пустых строк, начиная со второй. Любые отступы в первой строке документации несущественны и будут удалены. Относительный отступ более поздних строк в строке документа сохраняется. Пустые строки должны быть удалены из начала и конца строки документа.
Поскольку код гораздо точнее слов, здесь приведена реализация алгоритма:
По сравнению с оригинальным кодом, в python3 атрибут sys.maxint был переименован в sys.maxsize, поэтому в коде это сразу исправлено.
Документация в следующем примере содержит два символа новой строки и поэтому имеет длину равную трём. Первая и последняя строки пусты:
Таким образом, после обработки следующие документационные строки будут эквивалентны: