Exemplo de Python Docstring

As seqüências de documentação do Python, muitas vezes conhecidas como documentos, são literais de cordas usadas na declaração de um módulo, classe, método ou função. O atributo Doc de qualquer objeto Python (__doc__), bem como a funcionalidade interna da função Help (), forneça acesso aos documentos. Como a primeira frase na definição do objeto, uma constante de string define o Docstring do objeto. Python Docstrings está abordado nesta sessão. Com o auxílio de vários exemplos, descobriremos a aplicação precisa dos Docstrings.

Embora os comentários sejam utilizados para programas, declarações e expressões, que geralmente são breves, os doces são excelentes para entender o funcionamento da parte maior do script, como o uso geral de qualquer módulo, classe ou função. Eles são uma descrição de uma linha de código ou declaração produzida por um programador que geralmente é para entender o que faz. É crucial documentar seu código corretamente se você quiser escrever programas com código claro e boa documentação. Os Docstrings são fornecidos, empregando as "citações únicas triplas" ou "citações duplas triplas" logo após a definição de função, classe ou método.

Exemplo 1: Programa de Python Docstring Triple Single Quotes

O método __doc__ do objeto ou a função de ajuda pode ser usada para obter os Docstrings. A declaração e o uso de um docstring com as citações únicas triplas são mostradas nos exemplos a seguir:

Comece com a definição de uma função em Python. Criamos uma função como my_func (). Dentro do corpo do my_func, temos como uma documentação em torno das citações únicas triplas. Então, no final da função, executamos explicitamente a declaração de devolução que retorna o valor nenhum. A função de impressão leva my_func com o objeto _doc_ que exibirá o documento. Além disso, temos uma função de ajuda python que é usada para imprimir a documentação da função my_func.

Quando este programa em particular é depurado e executado, ele gera os seguintes resultados na tela do console do Spyder:

Exemplo 2: Programa de Python Docstring Triple Double Quotes

O código a seguir implanta a declaração de Docstring e o uso com as triplas de duas ditas:

Aqui, damos um nome de função my_func2. Dentro do corpo do my_func2, declaramos um documento com a citação tripla-dupla. Em seguida, chamamos o objeto _doc_ do Python para imprimir o docstring especificado e a documentação da função my_func2 com a função de ajuda.

Os resultados gerados a partir dos códigos mencionados são os seguintes. Esta saída é gerada pela execução do código afixado anterior em Spyder:

Exemplo 3: Programa de Python One-Line Docstring

Docstrings de uma linha são exatamente o que seu nome sugere: uma linha. Eles são empregados em situações flagrantes. As últimas citações estão situadas em uma linha semelhante à dos iniciais. Para as frases, isso parece mais atraente.

Aqui, construímos uma função como "add" que leva dois argumentos: x e y. Em seguida, declaramos o documento de uma linha dentro do corpo da definição de função "Add". A declaração de retorno retorna o valor da adição dos dois valores. A instrução de impressão é invocada para exibir o documento dentro da função Add, utilizando o objeto _doc_.

Os resultados da Docstring de uma linha são mostrados na seguinte tela do Spyder Console. Esta saída é gerada pela execução do código afixado acima em Spyder:

Exemplo 4: Programa de um Python Multi-Line Docstring

Semelhante ao DocStrings de uma linha, os Docstrings de várias linhas começam com uma linha de resumo e terminam com uma linha em branco antes de descrever algo com mais detalhes. A linha de resumo pode aparecer em uma linha semelhante à das citações iniciais ou em uma linha diferente. Um docstring multilina é demonstrado na seguinte instância:

Neste script de exemplo em particular, temos a definição de função que recebe um nome como python_function. Esta função leva um valor de argumento x. O corpo da função é declarado com a sequência de várias linhas, que é a descrição do valor do argumento e do tipo de dados int. Depois disso, o comando de retorno é definido. O docstring multilina é exibido chamando o objeto _doc_ dentro da função de impressão.

As várias linhas do docstring são impressas no terminal Spyder da seguinte forma:

Exemplo 5: Programa de Indentação Python Docstring

As citações em sua linha inicial são recuadas da mesma quantia que o restante do Docstring. Cada recuo na primeira linha do Docstring (com a primeira nova linha) é desnecessário e deve ser eliminado. Depois, as linhas no docstring mantêm seu recuo relativo. Como uma ilustração sobre como criar os documentos para uma aula e seus métodos, vejamos um exemplo. O acesso ao docstring é através da ajuda:

Definimos uma classe com a classe de palavra -chave e nomear essa classe como my_python_example. Dentro da classe my_python_example, declaramos o documento que é cercado pelas triplas citações duplas. Em seguida, criamos o quadrado da função que tem a entrada x e a função também é declarada com o docstring. Em seguida, criamos outra função com o nome, cubo. Também é preciso uma entrada n. Esta função é criada para o cubo do número. Esta afirmação é explicada pela declaração de Docstring. Depois disso, temos uma função de ajuda do Python para executar a documentação da classe my_python_program e o quadrado da função.

No programa Python mencionado anteriormente, a seguinte saída listada é obtida. Esta saída é gerada pela execução do código afixado anteriormente em Spyder:

Conclusão

O principal objetivo deste curso é familiarizá -lo com os Docstrings, passando pelas idéias fundamentais. No entanto, como o DocStrings é um tópico tão amplo, é possível que algumas idéias tenham sido ignoradas. Para obter a documentação de uma função, use a função Ajuda (). Coloque uma string, uma string de linha única ou uma string de várias linhas, na primeira linha da função para adicionar a documentação.