Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / Python

docstring — chaîne de documentation

Un docstring est un littéral de chaîne ordinaire (ni une f-string ni une t-string), utilisé comme première instruction d’un module, d’une classe ou d’une fonction. Il documente le rôle de l’objet et est accessible via __doc__ ; ce n’est pas un commentaire commençant par #.

Version : Python 3.14; repository image, production runtime not attested

Syntaxe

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

Un docstring est un littéral de chaîne ordinaire (ni une f-string ni une t-string), placé comme première instruction d’un module, d’une classe ou d’une fonction, y compris une méthode. Python le rend accessible comme attribut __doc__ de l’objet. Des outils peuvent utiliser ce contenu pour afficher la documentation.

Ni un littéral de chaîne formatée (f-string) ni un littéral de chaîne modèle (t-string) ne crée de docstring, même si le littéral ne contient aucun champ de remplacement et constitue la première instruction. Si la première instruction d’une fonction est f"""Description.""", son attribut __doc__ vaut None.

Un commentaire commençant par # ne crée pas de docstring. Un littéral de chaîne utilisé seul après une autre instruction ne devient pas non plus le docstring principal de l’objet. Les guillemets triples """...""" sont pratiques, surtout sur plusieurs lignes, mais ne suffisent pas à eux seuls : le type de littéral et sa position comptent tous les deux.

Par convention, la première ligne doit décrire brièvement le rôle de l’objet, commencer par une majuscule et se terminer par un point. Séparez la suite de la description par une ligne vide ; expliquez si nécessaire les arguments, les résultats et les effets de bord. Ce sont des recommandations de contenu, et non des exigences de syntaxe.

Dans l’exemple, square.__doc__ donne accès à la description, tandis que square(5) calcule son résultat indépendamment de la documentation. L’option -OO supprime les docstrings ; le code d’une application ne doit donc pas dépendre de leur présence.

Exemples

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

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

Résultat

Return the square of number.
25

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources