Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Python

docstring — cadeia de documentação

Um docstring é um literal de cadeia de caracteres comum (não uma f-string nem uma t-string), usado como primeira instrução de um módulo, de uma classe ou de uma função. Documenta a finalidade do objeto e está disponível através de __doc__; não é um comentário iniciado por #.

Versão: Python 3.14; repository image, production runtime not attested

Sintaxe

def function_name():
    """Describe the function's purpose."""
    pass

Um docstring é um literal de cadeia de caracteres comum (não uma f-string nem uma t-string), que aparece como primeira instrução de um módulo, de uma classe ou de uma função, incluindo métodos. O Python disponibiliza-o como atributo __doc__ do objeto. As ferramentas podem utilizar este conteúdo para apresentar documentação.

Nem um literal de cadeia formatada (f-string) nem um literal de cadeia de modelo (t-string) cria um docstring, mesmo que o literal não contenha campos de substituição e seja a primeira instrução. Se a primeira instrução de uma função for f"""Description.""", o seu atributo __doc__ tem o valor None.

Um comentário iniciado por # não cria um docstring. Um literal de cadeia isolado colocado depois de outra instrução também não se torna o docstring principal do objeto. As aspas triplas """...""" são práticas, sobretudo para várias linhas, mas não bastam por si só: tanto o tipo de literal como a sua posição são determinantes.

Por convenção, a primeira linha deve descrever brevemente a finalidade do objeto, começar com uma letra maiúscula e terminar com um ponto final. Separe a descrição adicional com uma linha em branco; explique os argumentos, os resultados e os efeitos secundários quando necessário. Estas são recomendações relativas ao conteúdo, não requisitos de sintaxe.

No exemplo, square.__doc__ disponibiliza a descrição, enquanto square(5) calcula o resultado independentemente da documentação. A opção -OO remove os docstrings, pelo que o código da aplicação não deve depender da sua presença.

Exemplos

def square(number):
    """Return the square of number."""
    return number * number

print(square.__doc__)
print(square(5))

Resultado

Return the square of number.
25

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes