Documentos de funções Python

Resumo : neste tutorial, você aprenderá como usar docstrings para adicionar documentação a uma função.

Introdução à função help()

Python fornece uma função integrada chamada help()que permite mostrar a documentação de uma função .

O exemplo a seguir mostra a documentação da print()função:

help(print)Linguagem de código:  Python  ( python )

Saída:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    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.
Linguagem de código:  Python  ( python )

Observe que você pode usar a help()função para mostrar a documentação de módulos , classes , funções e palavras-chave. Este tutorial se concentra apenas na documentação de funções.

Usando docstrings para documentar funções

Para documentar suas funções, você pode usar docstrings. O PEP 257 fornece as convenções docstring.

Quando a primeira linha no corpo da função for uma string, o Python irá interpretá-la como uma docstring. Por exemplo:

def add(a, b):
    "Return the sum of two arguments"
    return a + bLinguagem de código:  Python  ( python )

E você pode usar a help()função para encontrar a documentação da add()função:

help(add)Linguagem de código:  Python  ( python )

Saída:

add(a, b)
    Return the sum of two argumentsLinguagem de código:  Python  ( python )

Normalmente, você usa docstrings multilinhas:

def add(a, b):
    """ Add two arguments
    Arguments:
        a: an integer
        b: an integer
    Returns:
        The sum of the two arguments
    """
    return a + bLinguagem de código:  Python  ( python )

Saída:

add(a, b)
    Add the two arguments
    Arguments:
            a: an integer
            b: an integer
        Returns:
            The sum of the two arguments        Linguagem de código:  Sessão Shell  ( shell )

Python armazena os docstrings na __doc__propriedade da função.

O exemplo a seguir mostra como acessar a __doc__propriedade da add()função:

add.__doc__Linguagem de código:  Python  ( python )

Resumo

• Use a help()função para obter a documentação de uma função.
• Coloque uma string, seja de linha única ou de múltiplas linhas, como a primeira linha na função para adicionar documentação a ela.