10.2. functools
— Fonctions de haut niveau et opérations sur des objets appelables¶
Code source : Lib/functools.py
Le module functools
est utilisé pour des fonctions de haut niveau : des fonctions qui agissent sur ou revoient d’autres fonctions. En général, tout objet appelable peut être utilisé comme une fonction pour les besoins de ce module.
Le module functools
définit les fonctions suivantes :
-
functools.
cmp_to_key
(func)¶ Transforme une fonction de comparaison à l’ancienne en une fonction clé. Utilisé avec des outils qui acceptent des fonctions clef (comme
sorted()
,min()
,max()
,heapq.nlargest()
,heapq.nsmallest()
,itertools.groupby()
). Cette fonction est destinée au portage de fonctions python 2 utilisant des fonctions de comparaison vers Python 3.Une fonction de comparaison est un appelable qui prend deux arguments, les compare, et renvoie un nombre négatif pour l’infériorité, zéro pour l’égalité ou un nombre positif pour la supériorité. Une fonction de clé est un appelable qui prend un argument et retourne une autre valeur qui sera utilisée comme clé de tri.
Exemple :
sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order
Pour des exemples de tris et un bref tutoriel, consultez Guide pour le tri.
Nouveau dans la version 3.2.
-
@
functools.
lru_cache
(maxsize=128, typed=False)¶ Décorateur qui englobe une fonction avec un appelable mémoïsant qui enregistre jusqu’à maxsize appels récents. Cela peut gagner du temps quand une fonction coûteuse en ressources est souvent appelée avec les mêmes arguments.
Comme un dictionnaire est utilisé pour mettre en cache les résultats, les arguments positionnels et nommés de la fonction doivent être hachables.
Si maxsize est à
None
, la fonctionnalité LRU est désactivée et le cache peut grossir sans limite. La fonctionnalité LRU fonctionne mieux quand maxsize est une puissance de deux.Si typed est vrai, les arguments de différents types seront mis en cache séparément. Par exemple,
f(3)
etf(3.0)
seront considérés comme des appels distincts avec des résultats distincts.Pour aider à mesurer l’efficacité du cache et ajuster le paramètre maxsize, la fonction englobée est surveillée avec une fonction
cache_info()
qui renvoie un named tuple affichant les hits, misses, maxsize et currsize. Dans un environnement multithread, les succès et échecs d’appel du cache sont approximatifs.Le décorateur fournit également une fonction
cache_clear()
pour vider ou invalider le cache.La fonction sous-jacente originale est accessible à travers l’attribut
__wrapped__
. Ceci est utile pour l’introspection, pour outrepasser le cache, ou pour ré-englober la fonction avec un cache différent.Un cache LRU (*least recently used*) fonctionne très bien lorsque les appels récents sont les prochains appels les plus probables (par exemple, les articles les plus lus d’un serveur d’actualités ont tendance à ne changer que d’un jour à l’autre). La taille limite du cache permet de s’assurer que le cache ne grossisse pas sans limite sur les processus longs comme les serveurs web.
In general, the LRU cache should only be used when you want to reuse previously computed values. Accordingly, it doesn’t make sense to cache functions with side-effects, functions that need to create distinct mutable objects on each call, or impure functions such as time() or random().
Exemple d’un cache LRU pour du contenu web statique :
@lru_cache(maxsize=32) def get_pep(num): 'Retrieve text of a Python Enhancement Proposal' resource = 'http://www.python.org/dev/peps/pep-%04d/' % num try: with urllib.request.urlopen(resource) as s: return s.read() except urllib.error.HTTPError: return 'Not Found' >>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991: ... pep = get_pep(n) ... print(n, len(pep)) >>> get_pep.cache_info() CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
Exemple de calcul efficace de la suite de Fibonacci en utilisant un cache pour implémenter la technique de programmation dynamique :
@lru_cache(maxsize=None) def fib(n): if n < 2: return n return fib(n-1) + fib(n-2) >>> [fib(n) for n in range(16)] [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610] >>> fib.cache_info() CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)
Nouveau dans la version 3.2.
Modifié dans la version 3.3: L’option typed a été ajoutée.
-
@
functools.
total_ordering
¶ A partir d’une classe définissant une ou plusieurs méthodes de comparaison riches, ce décorateur de classe fournit le reste. Ceci simplifie l’effort à fournir dans la spécification de toutes les opérations de comparaison riche :
La classe doit définir au moins une de ces méthodes
__lt__()
,__le__()
,__gt__()
, or__ge__()
. De plus, la classe doit fournir une méthode__eq__()
.Par exemple :
@total_ordering class Student: def _is_valid_operand(self, other): return (hasattr(other, "lastname") and hasattr(other, "firstname")) def __eq__(self, other): if not self._is_valid_operand(other): return NotImplemented return ((self.lastname.lower(), self.firstname.lower()) == (other.lastname.lower(), other.firstname.lower())) def __lt__(self, other): if not self._is_valid_operand(other): return NotImplemented return ((self.lastname.lower(), self.firstname.lower()) < (other.lastname.lower(), other.firstname.lower()))
Note
Même si ce décorateur permet de créer des types ordonnables facilement, cela vient avec un coût d’exécution et des traces d’exécution complexes pour les méthodes de comparaison dérivées. Si des tests de performances le révèlent comme un goulot d’étranglement, l’implémentation manuelle des six méthodes de comparaison riches résoudra normalement vos problèmes de rapidité.
Nouveau dans la version 3.2.
Modifié dans la version 3.4: Retourner NotImplemented dans les fonction de comparaison sous-jacentes pour les types non reconnus est maintenant supporté.
-
functools.
partial
(func, *args, **keywords)¶ Return a new partial object which when called will behave like func called with the positional arguments args and keyword arguments keywords. If more arguments are supplied to the call, they are appended to args. If additional keyword arguments are supplied, they extend and override keywords. Roughly equivalent to:
def partial(func, *args, **keywords): def newfunc(*fargs, **fkeywords): newkeywords = keywords.copy() newkeywords.update(fkeywords) return func(*args, *fargs, **newkeywords) newfunc.func = func newfunc.args = args newfunc.keywords = keywords return newfunc
partial()
est utilisé pour une application de fonction partielle qui « gèle » une portion des arguments et/ou mots-clés d’une fonction donnant un nouvel objet avec une signature simplifiée. Par exemple,partial()
peut être utilisé pour créer un appelable qui se comporte comme la fonctionint()
ou l’argument base est deux par défaut :>>> from functools import partial >>> basetwo = partial(int, base=2) >>> basetwo.__doc__ = 'Convert base 2 string to an int.' >>> basetwo('10010') 18
-
class
functools.
partialmethod
(func, *args, **keywords)¶ Retourne un nouveau descripteur
partialmethod
qui se comporte commepartial
sauf qu’il est fait pour être utilisé comme une définition de méthode plutôt que d’être appelé directement.func doit être un descriptor ou un appelable (les objets qui sont les deux, comme les fonction normales, sont gérés comme des descripteurs).
When func is a descriptor (such as a normal Python function,
classmethod()
,staticmethod()
,abstractmethod()
or another instance ofpartialmethod
), calls to__get__
are delegated to the underlying descriptor, and an appropriate partial object returned as the result.Quand func est un appelable non-descripteur, une méthode liée appropriée est crée dynamiquement. Elle se comporte comme une fonction Python normale quand elle est utilisée comme méthode : l’argument self sera inséré comme premier argument positionnel, avant les args et keywords fournis au constructeur
partialmethod
.Exemple :
>>> class Cell(object): ... def __init__(self): ... self._alive = False ... @property ... def alive(self): ... return self._alive ... def set_state(self, state): ... self._alive = bool(state) ... set_alive = partialmethod(set_state, True) ... set_dead = partialmethod(set_state, False) ... >>> c = Cell() >>> c.alive False >>> c.set_alive() >>> c.alive True
Nouveau dans la version 3.4.
-
functools.
reduce
(function, iterable[, initializer])¶ Applique function avec deux arguments cumulativement aux éléments de sequence, de gauche à droite, pour réduire la séquence à une valeur unique. Par exemple,
reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])
calcule((((1+2)+3)+4)+5)
. Le premier argument, x, et la valeur de cumul et le deuxième, y, est la valeur de mise à jour depuis sequence. Si l’argument optionnel initializer est présent, il est placé avant les éléments de la séquence dans le calcul, et sert de valeur par défaut quand la séquence est vide. Si initializer n’est pas renseigné et que sequence ne contient qu’un élément, le premier élément est retourné.Sensiblement équivalent à :
def reduce(function, iterable, initializer=None): it = iter(iterable) if initializer is None: value = next(it) else: value = initializer for element in it: value = function(value, element) return value
-
@
functools.
singledispatch
¶ Transforme une fonction en une fonction générique single-dispatch.
Pour définir une fonction générique, il faut la décorer avec le décorateur
@singledispatch
. Noter que la distribution est effectuée sur le type du premier argument, donc la fonction doit être créée en conséquence :>>> from functools import singledispatch >>> @singledispatch ... def fun(arg, verbose=False): ... if verbose: ... print("Let me just say,", end=" ") ... print(arg)
Pour ajouter des surcharges d’implémentation à la fonction, utiliser l’attribut
register()
de la fonction générique. C’est un décorateur, prenant un type en paramètre et décorant une fonction implémentant l’opération pour ce type :>>> @fun.register(int) ... def _(arg, verbose=False): ... if verbose: ... print("Strength in numbers, eh?", end=" ") ... print(arg) ... >>> @fun.register(list) ... def _(arg, verbose=False): ... if verbose: ... print("Enumerate this:") ... for i, elem in enumerate(arg): ... print(i, elem)
Pour permettre l’enregistrement de lambdas et de fonctions pré-existantes, l’attribut
register()
peut être utilisé sous forme fonctionnelle :>>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing)
L’attribut
register()
renvoie la fonction non décorée ce qui permet d’empiler les décorateurs, la sérialisation, et la création de tests unitaires pour chaque variante indépendamment :>>> @fun.register(float) ... @fun.register(Decimal) ... def fun_num(arg, verbose=False): ... if verbose: ... print("Half of your number:", end=" ") ... print(arg / 2) ... >>> fun_num is fun False
Quand elle est appelée, la fonction générique distribue sur le type du premier argument :
>>> fun("Hello, world.") Hello, world. >>> fun("test.", verbose=True) Let me just say, test. >>> fun(42, verbose=True) Strength in numbers, eh? 42 >>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True) Enumerate this: 0 spam 1 spam 2 eggs 3 spam >>> fun(None) Nothing. >>> fun(1.23) 0.615
Quand il n’y a pas d’implémentation enregistrée pour un type spécifique, son ordre de résolution de méthode est utilisé pour trouver une implémentation plus générique. La fonction originale est décorée avec
@singledispatch
est enregistrée pour le type d”object
, et elle sera utilisée si aucune implémentation n’est trouvée.Pour vérifier quelle implémentation la fonction générique choisira pour un type donné, utiliser l’attribut
dispatch()
:>>> fun.dispatch(float) <function fun_num at 0x1035a2840> >>> fun.dispatch(dict) # note: default implementation <function fun at 0x103fe0000>
Pour accéder à toutes les implémentations enregistrées, utiliser l’attribut en lecture seule
registry
:>>> fun.registry.keys() dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>, <class 'decimal.Decimal'>, <class 'list'>, <class 'float'>]) >>> fun.registry[float] <function fun_num at 0x1035a2840> >>> fun.registry[object] <function fun at 0x103fe0000>
Nouveau dans la version 3.4.
-
functools.
update_wrapper
(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶ Met à jour la fonction wrapper pour ressembler à la fonction wrapped. Les arguments optionnels sont des tuples pour spécifier quels attributs de la fonction originale sont assignés directement aux attributs correspondants sur la fonction englobante et quels attributs de la fonction englobante sont mis à jour avec les attributs de la fonction originale. Les valeurs par défaut de ces arguments sont les constantes au niveau du module
WRAPPER_ASSIGNMENTS
(qui assigne__module__
,__name__
,__qualname__
,__annotations__
et__doc__
, la chaîne de documentation, depuis la fonction englobante) etWRAPPER_UPDATES
(qui met à jour le__dict__
de la fonction englobante, c’est-à-dire le dictionnaire de l’instance).Pour autoriser l’accès à la fonction originale pour l’introspection ou à d’autres fins (par ex. outrepasser l’accès à un décorateur de cache comme
lru_cache()
), cette fonction ajoute automatiquement un attribut__wrapped__
qui référence la fonction englobée.La principale utilisation de cette fonction est dans les décorateurs qui renvoient une nouvelle fonction. Si la fonction crée n’est pas mise à jour, ses métadonnées refléteront sa définition dans le décorateur, au lieu de la définition originale, métadonnées souvent bien moins utiles.
update_wrapper()
peut être utilisé avec des appelables autres que des fonctions. Tout attribut défini dans assigned ou updated qui ne sont pas l’objet englobé sont ignorés (cette fonction n’essaiera pas de les définir dans la fonction englobante).AttributeError
est toujours levée si le fonction englobante elle même a des attributs non existants dans updated.Nouveau dans la version 3.2: Ajout automatique de l’attribut
__wrapped__
.Nouveau dans la version 3.2: Copie de l’attribut
__annotations__
par défaut.Modifié dans la version 3.2: Les attributs manquants ne lèvent plus d’exception
AttributeError
.Modifié dans la version 3.4: L’attribut
__wrapped__
renvoie toujours la fonction englobée, même si cette fonction définit un attribut__wrapped__
. (voir bpo-17482)
-
@
functools.
wraps
(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶ Ceci est une fonction d’aide pour appeler
update_wrapper()
comme décorateur de fonction lors de la définition d’une fonction englobante. C’est équivalent àpartial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)
. Par exemple :>>> from functools import wraps >>> def my_decorator(f): ... @wraps(f) ... def wrapper(*args, **kwds): ... print('Calling decorated function') ... return f(*args, **kwds) ... return wrapper ... >>> @my_decorator ... def example(): ... """Docstring""" ... print('Called example function') ... >>> example() Calling decorated function Called example function >>> example.__name__ 'example' >>> example.__doc__ 'Docstring'
Sans l’utilisation de cette usine à décorateur, le nom de la fonction d’exemple aurait été
'wrapper'
, et la chaîne de documentation de la fonctionexample()
originale aurait été perdue.
10.2.1. Objets partial
¶
Les objets partial
sont des objets appelables créés par partial()
. Ils ont trois attributs en lecture seule :
-
partial.
func
¶ Un objet ou une fonction appelable. Les appels à l’objet
partial
seront transmis àfunc
avec les nouveaux arguments et mots-clés.
-
partial.
args
¶ Les arguments positionnels qui seront ajoutés avant les arguments fournis lors de l’appel d’un objet
partial
.
Les objets partial
sont comme des objets function
de par le fait qu’il sont appelables, référençables, et peuvent avoir des attributs. Il y a cependant des différences importantes. Par exemple, les attributs __name__
et __doc__
ne sont pas créés automatiquement. De plus, les objets partial
définis dans les classes se comportent comme des méthodes statiques et ne se transforment pas en méthodes liées durant la recherche d’attributs dans l’instance.