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."""
passUn 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.