Автор оригинала: Pankaj Kumar.

Python Docstring – вещи, которые вы должны знать

Строка документов Python (DOCSTRING) – это строковый литерал, который является первым утверждением в модуле, функции, классе или способе.

Как определить Python Docstring?

Python Docstring окружен пара тройных двойных кавычек («»). Давайте посмотрим на некоторые примеры определения Docstrings.

1. Пример функции Python Docstring

def multiply(a, b):
    """This method multiplies the given two numbers.

    Input Arguments: a, b must be numbers.
    Returns: Multiplication of a and b.
    """
    return a * b

2. Пример DocString класса Python

class Employee:
    """Employee class is used to hold employee object data.

    Methods:
        __init__(self, emp_id, emp_name)
        print()
    """

    def __init__(self, emp_id, emp_name):
        """Employee Class Constructor to initialize the object.

        Input Arguments: emp_id must be int, emp_name must be str
        """
        self.id = emp_id
        self.name = emp_name

    def print(self):
        """This method prints the employee information in a user friendly way."""
        print(f'Employee[{self.id}, {self.name}]')

3. Пример Docstring модуль Python

Скажем, мы определили выше функцию и класс в DocStrings.py файл. Каждый сценарий Python также является модулем. Мы можем определить этот модуль DOCSTRING AS:

"""
This module shows some examples of Python Docstrings

Classes: Employee
Functions: multiply(a, b)
"""

Как получить доступ к Python Docstrings?

Мы можем получить доступ к значению DocString из специального атрибута __doc__. Давайте посмотрим, как получить доступ к значениям DOCSTRING, определенных выше.

1. Доступ к функции Python Docstring

print(multiply.__doc__)

Выход:

2. Доступ к классу Python и метод Docstrings

print(Employee.__doc__)

print(Employee.__init__.__doc__)

print(Employee.print.__doc__)

Выход:

3. Доступ к модулю Python Docstring

Нам придется импортировать модуль Docstrings. Затем мы можем получить доступ к его значению DOCSTRING, используя атрибут __doc__. Мы прокомментировали вышеперечисленные операторы печати, прежде чем импортировать модуль DocStrings, чтобы избежать выполнения операторов Print ().

$  python ls
docstrings.py
$  python 
$  python python3.7
Python 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 16:52:21) 
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 
>>> import docstrings
>>> 
>>> docstrings.__doc__
'\nThis module shows some examples of Python Docstrings\n\nClasses: Employee\nFunctions: multiply(a, b)\n'
>>> 
>>> docstrings.Employee.__doc__
'Employee class is used to hold employee object data.\n\n    Methods:\n        __init__(self, emp_id, emp_name)\n        print()\n    '
>>> 
>>> 
>>> docstrings.multiply.__doc__
'This method multiplies the given two numbers.\n\n    Input Arguments: a, b must be numbers.\n    Returns: Multiplication of a and b.\n    '
>>> 
>>> 
>>> docstrings.Employee.print.__doc__
'This method prints the employee information in a user friendly way.'
>>> 

Python One-LiLER DOCSTRING

• Когда Python Docstring определяется в одной строке, он называется одноклассником DOCSTRING.
• Открытие цитаты и закрывающие цитаты находятся на одной линии.
• Не существует пустой строки до или после значения DOCSTRING.
• Лучшая практика заключается в том, чтобы закончить докстрацию с периодом.
• Лучше всего подходит для небольших полезных функций, где нам не нужно указывать много вещей.
• Обеспечить значимую DOCSTRING, чтобы указать детали функции и вывод. Например:

def reverse_str(s):
    """Reverses the input string and returns it."""
    pass

Python Multi-Line Docstring

• Когда значение DOCSTRING SPANS в несколько строк, это называется многострочная DOCSTRING.
• Лучшая практика для многострочной DOCSTRING – это начать с сводной строки, а затем пустая строка, за которой следует более подробное объяснение.
• Сводная строка может быть в одной строке, что и открывающие кавычки или следующая строка.
• Вся многострочная DOCSTRING отступает так же, как цитаты на его первой строке.

Python Docstring лучшие практики

1. Docstring сценариев Python должен указать, как его использовать. Он должен быть напечатан, когда сценарий выполняется с отсутствующими или неправильными параметрами.
2. Модуль Python Docstring должен перечислить все классы, функции, исключения и зависимости от других модулей.
3. Функция Python Docstring должна указывать поведение, входные аргументы, типы возврата и исключения. Если существуют конкретные ограничения, когда функция может быть вызвана, она должна быть указана в функции DOCSTRING.
4. Docstring класса должен перечислить все методы и атрибуты. Если он наследует из суперкласса, детали должны быть предоставлены.
5. Если метод класса переопределяет метод SuperClass, его следует указать.
6. Python чувствителен к регистру. Таким образом, оставьте имена аргументов функций точно так же, как и в определении функции.

Почему вы должны следовать рекомендациям Python DocString?

Python Docstrings можно получить доступ к атрибуту __doc__. Очень легко построить систему для разбора DOCSTRING и генерировать документацию проектных модулей, классов и функций. Вот почему вы должны следовать рекомендациям DOCSTRING, выложенные в Pep-257 Отказ

Можем ли мы использовать DocString для многостроительного комментария?

Я видел много случаев, когда DOCSTRING злоупотребляет, обеспечивая многословные комментарии. Python не поддерживает многослойные комментарии. Если вы хотите, чтобы комментарий был распространен на несколько строк, начните каждую строку с помощью HASH HACKER. Не злоупотребляйте Python Docstrings.