Tutorial de docstrings em Python

Se você está apenas começando a usar Python e gostaria de saber mais, faça o curso Introdução à ciência de dados em Python do DataCamp.

Pratique Docstrings em Python com este exercício prático.

A string de documentação do Python, ou comumente conhecida como docstring, é um literal de string e é usada na definição de classe, módulo, função ou método. Você pode acessar os docstrings no atributo doc (__doc__) para qualquer um dos objetos Python e também com a função integrada help(). A docstring de um objeto é definida pela inclusão de uma constante de string como a primeira instrução na definição do objeto.

Os docstrings são ótimos para você entender a funcionalidade da maior parte do código, ou seja, a finalidade geral de qualquer classe, módulo ou função, enquanto os comentários são usados para códigos, declarações e expressões, que tendem a ser pequenos. São textos descritivos escritos por um programador, principalmente para que ele próprio saiba o que a linha de código ou expressão faz e também para o desenvolvedor que deseja contribuir com esse projeto. É essencial que você documente seu código Python para que possa escrever um código limpo e programas bem escritos.

Os docstrings ajudam você a entender os recursos de um módulo ou de uma função. Por exemplo, digamos que você tenha instalado a biblioteca scikit-learn e queira saber tudo sobre o pacote sklearn, como descrição, módulos do pacote etc., você pode simplesmente usar a função help para obter todas as informações.

Vamos importar o pacote rapidamente.

import sklearn

help(sklearn)

Você verá um resultado semelhante ao mostrado abaixo:

Docstrings Python versus Docstrings Python. Comentários

Os docstrings são semelhantes em espírito aos comentários, mas são versões aprimoradas, mais lógicas e úteis dos comentários. As docstrings funcionam como documentação para a classe, o módulo e os pacotes.

Por outro lado, os comentários são usados principalmente para explicar partes não óbvias do código e podem ser úteis para comentários sobre a correção de erros e tarefas que precisam ser feitas.

Os docstrings são representados com aspas de fechamento e abertura, enquanto os comentários começam com um # no início.

Observe que os comentários não podem ser acessados com o atributo doc e a função help incorporados. Vamos ver o que acontece se você tentar fazer isso:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Há duas maneiras de escrever ou usar uma Docstring, ou seja, one-line docstring e multi-line docstring. Vamos aprendê-las uma a uma.

Docstring de uma linha

Os Docstrings de uma linha são os Docstrings que cabem todos em uma linha. Você pode usar uma das aspas, ou seja, aspas simples triplas ou aspas duplas triplas, e as aspas de abertura e de fechamento precisam ser as mesmas. Nas Docstrings de uma linha, as aspas de fechamento estão na mesma linha que as aspas de abertura. Além disso, a convenção padrão é usar aspas triplas duplas.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)

Returned argument a is squared.

help(square)

Help on function square in module __main__:

square(a)
    Returned argument a is squared.

Na saída do Docstring acima, você pode observar que:

• Nesse caso, a linha começa com uma letra maiúscula, ou seja, R, e termina com um ponto (.).
• As aspas de fechamento estão na mesma linha que as aspas de abertura. Isso é melhor para frases de efeito.
• Uma boa prática a ser seguida é não ter nenhuma linha em branco antes ou depois do Docstring, conforme mostrado no exemplo acima.
• A saída do atributo __doc__ é menos detalhada em comparação com a função help().

Docstring de várias linhas

Os Docstrings de várias linhas também contêm a mesma linha de literais de cadeia de caracteres que os Docstrings de uma linha, mas ela é seguida por um único espaço em branco junto com o texto descritivo.

O formato geral para escrever uma Docstring de várias linhas é o seguinte:

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Vamos dar uma olhada no exemplo que mostra como as cadeias de caracteres de várias linhas podem ser usadas em detalhes:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Você pode ver acima que a linha de resumo está em uma linha e também está separada do outro conteúdo por uma única linha em branco. Essa convenção precisa ser seguida, o que é útil para as ferramentas de indexação automática.

Docstring incorporada do Python

Vamos ver as Docstrings do Python incorporadas.

Todas as funções, classes e métodos internos têm a descrição humana real anexada a eles. Você pode acessá-lo de duas maneiras.

• atributo doc
• A função de ajuda

Você perceberá que a saída da função help é mais detalhada do que o atributo __doc__.

Por exemplo:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Da mesma forma, você pode usar a função de ajuda:

help(math)

Python Docstring em classes

Em uma definição de classe, uma docstring pode ser usada para fornecer documentação para a classe como um todo. Normalmente, você o coloca imediatamente após a definição da classe e ele é colocado entre aspas triplas ("""). Por exemplo:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Os docstrings podem ser acessados usando o atributo __doc__ da classe ou do método. Por exemplo, você pode acessar o docstring de MyClass usando MyClass.__doc__.

Vamos dar uma olhada em alguns formatos populares de Docstring e entendê-los em detalhes.

Formatos de docstring do Python

Há muitos formatos de Docstrings disponíveis, mas é sempre melhor usar os formatos que são facilmente reconhecidos pelo analisador de Docstring e também por outros programadores/cientistas de dados. Não há regras e normas para a seleção de um formato Docstring, mas a consistência da escolha do mesmo formato no projeto é necessária. Além disso, é preferível que você use o tipo de formatação, que é mais compatível com o Sphinx.

Os formatos mais comuns usados estão listados abaixo.

Pode haver diferentes cadeias de documentação disponíveis. Você não precisa se preocupar com o fato de ter que reinventar a roda para estudar tudo. Os formatos de todas as cadeias de documentação são quase semelhantes. Os padrões são semelhantes, mas há apenas alterações mínimas em cada formato. Você verá o exemplo de um formato popular de cadeia de documentação disponível com seu uso.

Inicialmente, você verá o estilo Sphinx em detalhes e, em seguida, poderá acompanhar facilmente outros formatos também.

Estilo Sphinx

O Sphinx é o estilo fácil e tradicional, detalhado, e foi inicialmente criado especificamente para a documentação do Python. O Sphinx usa um texto reestruturado, que é semelhante em uso ao Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

O Sphinx usa o endereço keyword(reserved word); a maioria das linguagens de programação usa. Mas ele é explicitamente chamado de role no Sphinx. No código acima, o Sphinx tem param como uma função e type é uma função, que é o tipo de dados do Sphinx para param. A função type é opcional, mas param é obrigatória. As funções de retorno documentam o objeto retornado. É diferente da função param. A função de retorno não depende do rtype e vice-versa. O rtype é o tipo de objeto retornado da função fornecida.

Google Style

O Google Style é mais fácil e intuitivo de usar. Ele pode ser usado para a forma mais curta de documentação. Uma configuração do arquivo python precisa ser feita para começar, portanto, você precisa adicionar sphinx.ext.napoleon ou sphinxcontrib.napoleon à lista de extensões em conf.py.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

O estilo Google é melhor do que o estilo Sphinx. Ele também tem um recurso inconveniente, ou seja, no código acima, a descrição de várias linhas da distância pareceria confusa. É por isso que o Numpy pode ser usado para a forma mais ampla de documentação.

Estilo Numpy

O estilo Numpy tem muitos detalhes na documentação. Ela é mais detalhada do que outras documentações, mas é uma excelente opção se você quiser fazer uma documentação detalhada, ou seja, uma documentação extensa de todas as funções e parâmetros.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

O exemplo acima é mais detalhado do que qualquer outra documentação. Ele é mais longo e só pode ser usado para documentação longa e detalhada.

PyDoc

Como você aprendeu, as docstrings podem ser acessadas por meio do atributo incorporado do Python __doc__ e da função help(). Você também pode usar o módulo interno conhecido como Pydoc, que é muito diferente em termos de recursos e funcionalidades quando comparado ao atributo doc e à função de ajuda.

O Pydoc é uma ferramenta útil quando você deseja compartilhar o código com seus colegas ou torná-lo de código aberto, caso em que você estaria visando a um público muito mais amplo. Ele pode gerar páginas da Web a partir da sua documentação do Python e também pode iniciar um servidor da Web.

Vamos ver como isso funciona.

A maneira mais fácil e conveniente de executar o módulo Pydoc é executá-lo como um script. Para executá-lo dentro da célula do laboratório jupyter, você usaria o caractere de ponto de exclamação (!).

• Pydoc como um módulo

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Se você observar a saída acima, o primeiro uso do Pydoc é mostrar a documentação de texto em uma função, módulo, classe etc., portanto, vamos ver como você pode aproveitar isso melhor do que a função de ajuda.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Agora, vamos extrair a documentação do site glob usando a função de ajuda.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Bem, como você pode ver, ele gera um erro de nome, pois o glob não está definido. Portanto, para usar a função de ajuda para extrair a documentação, você precisa primeiro importar esse módulo, o que não é o caso do Pydoc.

• Pydoc como um serviço da Web

Vamos explorar o recurso mais interessante do módulo Pydoc, ou seja, executar o Pydoc como um serviço da Web.

Para fazer isso, você simplesmente executaria o Pydoc como um script, mas com um argumento -b que iniciará um servidor HTTP em uma porta arbitrária não utilizada e abrirá um navegador da Web para navegar interativamente na documentação. Isso é útil, especialmente quando você tem vários outros serviços em execução no sistema e não se lembra de qual porta estaria em estado ocioso.

!python -m pydoc -b

^C

No momento em que você executar a célula acima, uma nova janela será aberta em um número de porta arbitrário, e o navegador da Web terá uma aparência semelhante à mostrada abaixo.

Vejamos a documentação do módulo h5py, que é um formato de arquivo usado para armazenar pesos da arquitetura da rede neural.

Conclusão

Parabéns por você ter concluído o tutorial sobre docstring em Python.

Este tutorial tem como foco principal fazer com que você comece a usar docstrings, abordando os tópicos essenciais. No entanto, Docstrings é um tópico vasto, e alguns conceitos podem não ter sido explorados. Se você quiser saber mais, confira nosso tutorial sobre strings em Python e nosso curso sobre como escrever funções em Python.

Se você está apenas começando a usar Python e gostaria de saber mais, faça o curso Introdução à ciência de dados em Python do DataCamp.