Documentando Funções Python com Docstrings

Introdução

Neste laboratório, você aprenderá a importância de documentar seu código Python usando docstrings. Exploraremos como acessar as docstrings existentes para funções nativas (built-in) usando a função help() e o atributo __doc__.

Além disso, você ganhará experiência prática na escrita de suas próprias docstrings para funções personalizadas e na verificação de sua acessibilidade, tornando seu código mais compreensível e fácil de manter para você e para outros.

Passo 1: Acessando a Documentação com help()

Uma docstring é uma literal de string que ocorre como a primeira instrução na definição de um módulo, função, classe ou método. Ela é usada para documentar o que o código faz. A função nativa help() do Python é uma excelente ferramenta para visualizar essa documentação em um formato limpo e legível. A função help() é projetada para uso interativo.

Vamos começar visualizando a documentação da função nativa print().

Primeiro, abra um terminal no WebIDE. Você pode fazer isso clicando no menu Terminal na parte superior da tela e selecionando New Terminal.

No terminal, inicie o shell interativo do Python digitando o seguinte comando e pressionando Enter:

python

Você verá o prompt do Python (>>>). Agora, use a função help() para obter informações sobre print():

help(print)

O terminal exibirá a documentação para a função print.

Help on built-in function print in module builtins:

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.

(END)

Esta saída explica o que a função faz, quais parâmetros ela aceita e seus valores padrão. Pressione a tecla q para sair do visualizador de ajuda e retornar ao prompt do Python.

Agora, saia do shell interativo do Python digitando:

exit()

Passo 2: Acessando Docstrings Brutas com __doc__

Embora help() seja ótimo para uso interativo, você também pode acessar a docstring bruta de um objeto programaticamente usando seu atributo especial __doc__. Este atributo armazena a docstring como uma string simples.

Vamos ver isso em ação. No explorador de arquivos do WebIDE à esquerda, localize e abra o arquivo chamado access_docstring.py.

Adicione o seguinte código Python ao arquivo. Este código imprimirá a docstring da função nativa len().

## This script prints the docstring of the len() function.
print(len.__doc__)

Salve o arquivo (você pode usar o atalho Ctrl+S).

Agora, retorne ao terminal e execute o script com o seguinte comando:

python access_docstring.py

A saída será a docstring bruta para a função len.

Return the number of items in a container.

Como você pode ver, __doc__ fornece o conteúdo direto da string da documentação, o que pode ser útil para ferramentas ou scripts personalizados que processam documentação.

Passo 3: Escrevendo uma Docstring de Função Personalizada

Documentar suas próprias funções é uma prática fundamental para escrever código limpo e de fácil manutenção. Uma boa docstring explica o propósito da função, seus parâmetros e o que ela retorna.

Vamos escrever uma função e documentá-la. Abra o arquivo my_function.py no explorador de arquivos.

Primeiro, adicione a seguinte definição de função ao arquivo:

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Agora, vamos adicionar uma docstring. A docstring deve ser colocada imediatamente após a linha def e ter o mesmo nível de indentação do código da função. Usaremos aspas triplas ("""...""") para uma docstring de múltiplas linhas.

Modifique my_function.py para incluir a docstring. Também adicionaremos uma linha para imprimir a docstring para verificar se está funcionando.

def greet(name, greeting="Hello"):
    """Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".
    """
    print(f"{greeting}, {name}!")

## Print the docstring of our greet function
print(greet.__doc__)

Salve o arquivo. Agora, execute o script a partir do seu terminal:

python my_function.py

Você verá sua docstring personalizada impressa no console.

Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

Isso confirma que você documentou sua função com sucesso e pode acessar sua docstring usando o atributo __doc__.

Passo 4: Usando help() com Sua Função Personalizada

No passo anterior, acessamos nossa docstring personalizada usando __doc__. Agora, vamos usar a função help() para ver uma visualização mais polida e amigável da nossa documentação, assim como fizemos para a função nativa print().

Vamos importar nossa função greet para o shell interativo do Python para usar help().

No seu terminal, inicie o shell Python novamente:

python

Assim que vir o prompt >>>, importe a função greet do seu módulo my_function (o nome do arquivo my_function.py é tratado como um módulo chamado my_function).

from my_function import greet

Agora, use help() para visualizar a documentação da sua função greet:

help(greet)

Você verá uma saída bem formatada gerada a partir da sua docstring.

Help on function greet in module my_function:

greet(name, greeting='Hello')
    Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

(END)

Note como help() inclui automaticamente a assinatura da função (greet(name, greeting='Hello')) e formata a docstring para facilitar a leitura. É por isso que escrever boas docstrings é tão valioso — ela se integra diretamente ao sistema de ajuda nativo do Python.

Pressione q para sair do visualizador de ajuda e, em seguida, digite exit() para sair do shell Python.

Resumo

Neste laboratório, você aprendeu os fundamentos da documentação de código Python com docstrings. Você praticou o acesso à documentação de funções nativas usando a função interativa help() e o atributo __doc__. Em seguida, aplicou esse conhecimento escrevendo suas próprias docstrings de linha única e de múltiplas linhas para uma função personalizada, seguindo as convenções padrão. Por fim, você verificou que sua documentação personalizada é acessível tanto através de __doc__ quanto do sistema help() do Python, uma habilidade essencial para criar código legível, reutilizável e de fácil manutenção.