PEP257 ou les conventions des docstrings

Le but de ce PEP est de standardiser la structure de haut niveau des docstrings : ce qu'ils doivent contenir et comment le dire (sans toucher à la syntaxe du balisage dans les docstrings). Le PEP contient des conventions, et non des lois ou une syntaxe.

"Une convention universelle fournit tout ce qui est maintenabilité, clarté, cohérence, et une base pour de bonnes habitudes de programmation aussi. Ce qu'elle ne fait pas, c'est insister pour que vous la suiviez contre votre volonté. C'est Python !"

-- Tim Peters sur comp.lang.python, 2001-06-16

Si vous violez ces conventions, le pire que vous obtiendrez sera un mauvais regard. Mais certains logiciels (tels que le système de traitement des chaînes de caractères Docutils) connaissent les conventions, et les respecter vous permettra d'obtenir les meilleurs résultats.

Que sont les docstrings ?

Une docstring est une chaîne de caractères littérale qui apparaît comme première déclaration dans un module, une fonction, une classe ou une définition de méthode. Une telle docstring devient l'attribut spécial __doc__ de cet objet.

Tous les modules devraient normalement avoir des docstrings, et toutes les fonctions et classes exportées par un module devraient également avoir des docstrings. Les méthodes publiques (y compris le constructeur __init__) doivent également avoir des docstrings. Un paquet peut être documenté dans la docstring du module du fichier __init__.py dans le répertoire du paquet.

Les chaînes de caractères qui apparaissent ailleurs dans le code Python peuvent également servir de documentation. Ils ne sont pas reconnus par le compilateur de bytecode Python et ne sont pas accessibles en tant qu'attributs d'objet d'exécution (c'est-à-dire qu'ils ne sont pas affectés à __doc__), mais deux types de docstrings supplémentaires peuvent être extraits par des outils logiciels :

• Les littéraux de chaîne de caractères apparaissant immédiatement après une simple affectation au niveau supérieur d'un module, d'une classe ou de la méthode __init__ sont appelés docstrings d'attributs.
• Les chaînes de caractères qui se trouvent immédiatement après une autre chaîne de caractères sont appelées chaînes de caractères supplémentaires.

Pour des raisons de cohérence, utilisez toujours """des guillemets doubles triples"" autour des chaînes de caractères. Utilisez les """triples guillemets bruts"" si vous utilisez des antislashs dans vos chaînes de caractères. Pour les docstrings Unicode, utilisez u """chaînes Unicode à triple guillemets""".

Il existe deux formes de docstrings : les docstrings d'une ligne et les docstrings multilignes.

Les docstrings d’une ligne