Python : comprendre les docstrings en 1 minute

par Christophe Combelles, mis à jour le 13/05/2013

Les docstrings sont des chaines de doc qui doivent être placées juste en dessous des définitions de fonction ou de classe, ou bien tout en haut d'un module.
L'intérêt, c'est que les docstrings sont récupérables dynamiquement via l'attribut __doc__, ou grâce à la fonction primitive help( ). Ça permet notamment de faire de la documentation autogénérée :

Exemple :

Je définis une classe avec un docstring de classe, et une de méthode

$ python
>>> class FooBar(object):
...     "ma doc de classe"
...    
...     def une_methode():
...         "ma doc de methode"
...         print 'boo'
...

On retrouve la doc dans l'attribut __doc__ de la classe :

>>> FooBar.__doc__
'ma doc de classe'
>>> FooBar.une_methode.__doc__
'ma doc de methode'

On les retrouve aussi dans les instances :

>>> foobar = FooBar()
>>> foobar.__doc__
'ma doc de classe'
>>> foobar.une_methode.__doc__
'ma doc de methode'

On peut aussi faire des docstrings de module, en mettant la string tout en haut du fichier Python.
Ex : je crée un module python avec une docstring de module (et une docstring de fonction) :

$ cat > foobar.py << EOF
> "ma doc de module"
>
> def foo():
>     "ma doc de fonction"
>     print 'foo'
> EOF

J'importe le module et je peux récupérer la doc du module et celle de la fonction :

$ python
>>> import foobar
>>> foobar.__doc__
'ma doc de module'
>>> foobar.foo.__doc__
'ma doc de fonction'

Au lieu de l'attribut __doc__, il est plus pratique d'utiliser la primitive help( ):

>>> help(foobar)
Help on module foobar:

NAME
foobar - ma doc de module

FILE
/home/ccomb/foobar.py

FUNCTIONS
foobar()
ma doc de fonction