Строки документации в Python: их типы и форматы

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

- Даниэле Прочида

Что такое строки документации?

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults or readability

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

>>> str.__doc__ = "Йа стр0ка"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'str'

def say_hello(name):
    print(f"Привет, {name}, не меня ли ищещь?")

say_hello.__doc__ = "Просто функция, которая здоровается"

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    Просто функция, которая здоровается

def say_hello(name):
    """ Просто функция, которая здоровается """
    print(f"Привет, {name}, не меня ли ищещь?")

>>> help(say_hello)
Help on function say_hello in module __main__:
 
say_hello(name)
    Просто функция, которая здоровается

Типы докстрингов

Докстринги классов

class SimpleClass:
    """Здесь докстринг класса"""

    def say_hello(self, name: str):
        """Здесь докстринг метода класса"""

        print(f"Привет, {name}")

Докстринги пакетов и модулей

Докстринги скриптов

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

    * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "input_file",
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Форматы докстрингов

Google Dosctring

def google_docstrings(num1, num2) -> int:
    """Add up two integer numbers.  
    
    This function simply wraps the ``+`` operator, and does not 
    do anything interesting, except for illustrating what 
    the docstring of a very simple function looks like.  
    
    Args: 
        num1 (int) : First number to add. 
        num2 (int) : Second number to add.  
        
    Returns: 
        The sum of ``num1`` and ``num2``.  
        
    Raises: 
        AnyError: If anything bad happens.  
    """ 
    return num1 + num2

NumPy Docstring

def numpy_docstrings(num1, num2) -> int: 
    """ Add up two integer numbers.  
    
    This function simply wraps the ``+`` operator, and does not 
    do anything interesting, except for illustrating what 
    the docstring of a very simple function looks like.  
    
    Parameters 
    ---------- 
    num1 : 
        int First number to add. 
    num2 : int 
        Second number to add.  
    
    Returns 
    ------- 
    int 
        The sum of ``num1`` and ``num2``.  
        
    Raises 
    ====== 
     MyException 
        if anything bad happens  
        
    See Also 
    -------- 
    subtract : Subtract one integer from another.  
    
    Examples 
    -------- 
    >>> add(2, 2) 
    4 
    >>> add(25, 0) 
    25 
    >>> add(10, -10) 
    0 
    """ 
    return num1 + num2

Sphinx Docstring

def sphinx_docstrings(num1, num2) -> int:
    """Add up two integer numbers.  
    
    This function simply wraps the ``+`` operator, and does not 
    do anything interesting, except for illustrating what 
    the docstring of a very simple function looks like.  
    
    :param int num1: First number to add. 
    :param int num2: Second number to add. 
    :returns: The sum of ``num1`` and ``num2``. 
    :rtype: int 
    :raises AnyError: If anything bad happens. 
    """ 
    return num1 + num2

Заключение