functools en pratique : lru_cache, cached_property, partial et singledispatch

Ce que c'est

functools regroupe des utilitaires d'ordre supérieur. @lru_cache(maxsize=128) met en mémoire une fonction selon ses arguments, qui doivent être hachables ; @cache en est la forme non bornée ; cache_info() renvoie les succès, les échecs, la taille maximale et la taille actuelle, cache_clear() vide le cache et __wrapped__ permet d'atteindre la fonction d'origine. @cached_property calcule un attribut une seule fois par instance et le stocke dans le dictionnaire de l'instance. partial(f, *args, **kw) fige des arguments et renvoie un appelable exposant .func, .args et .keywords. @singledispatch transforme une fonction en fonction générique qui aiguille selon la classe de son premier argument ; register accepte une annotation de type et, depuis la 3.11, un Union ; @singledispatchmethod aiguille selon le premier argument après self. @wraps copie le nom, la docstring et d'autres métadonnées sur l'enveloppe d'un décorateur.

Pourquoi c'est important

Chacun remplace quelque chose habituellement écrit à la main (un dictionnaire de cache au niveau du module, un adaptateur lambda, une chaîne de isinstance) par un outil standard dont le comportement sous introspection, sous threads et face aux limites de cache est documenté.

Comment l'appliquer

• Ne mettre en cache que des fonctions pures dont le résultat ne dépend ni du temps ni d'un état externe ; borner maxsize dans les processus de longue durée et lire cache_info() dans un test pour confirmer que le cache est effectivement sollicité.
• Ne pas placer lru_cache sur des méthodes d'instance. La FAQ Python explique que cela crée une référence vers l'instance, si bien que les instances restent en vie jusqu'à leur expiration du cache ; utiliser cached_property pour des valeurs par instance sans argument ; la FAQ précise que les résultats ne persistent alors qu'aussi longtemps que l'instance elle-même.
• Utiliser partial pour l'adaptation de rappels (« callbacks ») ; contrairement à un lambda, il expose .func, .args et .keywords, de sorte que les journaux et les tests peuvent voir ce qui a été lié.
• Avec singledispatch, enregistrer les implémentations depuis les modules propriétaires des types (un sérialiseur apprend un nouveau type sans modifier la fonction centrale) ; l'implémentation de repli doit lever explicitement TypeError ou NotImplementedError.
• Toujours appliquer @wraps(func) dans les décorateurs écrits à la main afin que help(), les traces d'appel et __wrapped__ fonctionnent.

Pièges

La documentation avertit que des motifs d'arguments distincts constituent des clés distinctes : f(a=1, b=2) et f(b=2, a=1) peuvent avoir des entrées de cache séparées. cached_property a besoin d'un __dict__ d'instance, et ne fonctionne donc pas sur les classes à __slots__ ; la documentation suggère alors d'empiler @property par-dessus @lru_cache. Sous threads, la fonction mise en cache peut s'exécuter plus d'une fois pour les mêmes arguments avant que le premier appel ne se termine. Les annotations de singledispatch doivent nommer des classes (ou un Union de classes) ; l'aiguillage ignore entièrement les autres arguments.