CKTIS / Python
Docstrings de fonctions, `__doc__` et `__name__`
Lisez la documentation d’une fonction sans l’appeler. Préservez son nom et sa docstring lors de la décoration pour que les journaux d’audit et les rapports décrivent la bonne fonction.
Version : Python 3.12
Syntaxe
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."En Python 3.12, la docstring d’une fonction est un littéral de chaîne qui constitue la première instruction de son corps. Les lignes vides et les commentaires ne sont pas des instructions et peuvent donc le précéder. Ni un commentaire #, ni un littéral placé plus loin, ni une f-string (même sans substitution) ne renseigne __doc__. Les triples guillemets doubles relèvent de la convention PEP 257, pas d’une exigence syntaxique.
f.__doc__ lit la documentation stockée dans l’objet fonction sans appeler f. En l’absence de documentation, la valeur est None, et non la chaîne vide ''. Cet attribut est modifiable sur les fonctions définies par l’utilisateur. Utilisez f.__doc__ pour obtenir la valeur brute dans un rapport, ou inspect.getdoc(f) pour afficher la documentation avec une indentation nettoyée. L’option -OO de CPython supprime les docstrings : n’en faites pas dépendre le comportement du programme.
f.__name__ est un attribut distinct : il contient le nom de la fonction, pas sa documentation. alias = f crée une autre référence au même objet sans le renommer. Si un décorateur renvoie une nouvelle fonction enveloppe sans copier les métadonnées, l’audit lit le nom et la documentation de cette enveloppe. Appliquez @functools.wraps(f) à sa définition : par défaut, il copie notamment __name__ et __doc__, et fait pointer __wrapped__ vers la fonction enveloppée.
Exemples
from functools import wraps
def audit(func):
@wraps(func)
def wrapper(*args, **kwargs):
print(f"Audit: {wrapper.__name__}")
return func(*args, **kwargs)
return wrapper
@audit
def compute_net(gross, fee):
"""Return gross minus fee."""
return gross - fee
print(f"Documentation: {compute_net.__doc__!r}")
print(f"Net: {compute_net(120, fee=15)}")Résultat
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Le rapport lit d’abord la docstring sans appeler `compute_net`. La fonction enveloppe journalise ensuite le nom préservé et transmet les arguments ; le calcul renvoie `105`.
Leçons associées
- Python · Leçon 10 · Avancé · Version : 5