Python : comprendre les docstrings en 1 minute

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 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 auto-générée.

Exemple

Je définis une classe avec une 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