Notes de cours Python Scientifique

Constructions avancées en Python

Zbigniew Jedrzejewski-Szmek

Traducteurs

| s0h3ck | scsab |

Cette section traite de certaines fonctionnalités du langage Python qui peuvent être considérées comme avancées. Ces fonctionnalités sont avancées dans le sens où elles ne sont pas disponibles dans tous les langages et où elles sont plus utiles dans des programmes ou des bibliothèques plus complexes, mais cela ne veut pas dire qu'elles soient particulièrement spécialisées ou particulièrement compliquées.

Il est important de souligner que ce chapitre concerne uniquement le langage lui-même - les fonctionnalités prises en charge grâce à une syntaxe spéciale complétée par les fonctionnalités de la bibliothèque stdlib de Python, qui ne peuvent pas être implémentées par des modules externes inventifs.

Le processus de développement du langage de programmation Python et de sa syntaxe est très transparent. Les changements proposés sont évalués sous différents angles et discutés via les Python Enhancement Proposals - ou PEP. En conséquence, les fonctionnalités décrites dans ce chapitre ont été ajoutées après qu'il a été démontré qu'elles résolvent effectivement des problèmes réels et que leur utilisation est aussi simple que possible.

Retrouvez Les notes de cours scientifiques de Python

Commentez

- Titre : Notes de cours Python Scientifique

- Auteur : Zbigniew Jedrzejewski-Szmek

- Traducteurs : s0h3ck, scsab

- Parution : 29 janvier 2018

- Licence : Le contenu de cet article est rédigé par Zbigniew Jędrzejewski-Szmek et est mis à disposition selon les termes de la Licence Creative Commons Attribution 3.0 non transposé. Les logos Developpez.com, en-tête, pied de page, css, et look & feel de l'article sont Copyright ® 2013 Developpez.com.

Sommaire

- I. Itérateurs, expressions génératrices et générateurs

- I-A. Itérateurs

- I-B. Les expressions génératrices

- I-C. Générateurs

- I-D. Communication bidirectionnelle

- I-E. Générateurs chaînés

- II. Décorateurs

- II-A. Remplacement ou modification de l'objet d'origine

- II-B. Les décorateurs implémentés comme classes et comme fonctions

- II-C. Copier la docstring et d'autres attributs de la fonction d'origine

- II-D. Exemples dans la bibliothèque standard

- II-E. Dépréciation de fonctions

- II-F. Un décorateur de suppression de boucles While

- II-G. Un système d'enregistrement des plugins

- III. Gestionnaires de contexte

- III-A. Intercepter les exceptions

- III-B. Utilisation de générateurs pour définir les gestionnaires de contexte

I - Itérateurs, expressions génératrices et générateurs

I-A - Itérateurs

Un itérateur est un objet adhérant au protocole itératif - essentiellement cela signifie qu'il a une méthode next, qui, lorsqu'elle est appelée, renvoie l'élément suivant dans la séquence et, lorsqu'il n'y a rien à renvoyer, déclenche l'exception StopIteration.

Un objet itérateur permet de boucler une seule fois sur une séquence. Il connaît l'état (la position) d'une seule itération, et, inversement, chaque boucle sur une séquence nécessite un seul objet itérateur. Cela signifie que nous pouvons itérer sur la même séquence plus d'une fois simultanément. Faire la distinction entre la logique d'itération et la séquence nous permet d'avoir plus d'une manière de faire l'itération.

Simplicité

Multiplier l'effort est un gaspillage, et le remplacement des différentes approches « maison » par une caractéristique standard généralement rend les choses plus lisibles, mais aussi interopérables.

Guido van Rossum — Adding Optional Static Typing to Python

Appeler la méthode __iter__ sur un conteneur pour créer un objet itérateur est le moyen le plus simple pour obtenir un itérateur. La fonction iter le fait pour nous et nous permet d'économiser un peu de frappes au clavier.

1. >>> nums = [1, 2, 3]      # notez que ... varie : Ce sont des objets différents

2. >>> iter(nums)

3. <...iterator object at ...>

4. >>> nums.__iter__()

5. <...iterator object at ...>

6. >>> nums.__reversed__()

7. <...reverseiterator object at ...>

9. >>> it = iter(nums)

10. >>> next(it)

11. 1

12. >>> next(it)

13. 2

14. >>> next(it)

15. 3

16. >>> next(it)

17. Traceback (most recent call last):

18. File "<stdin>", line 1, in <module>

19. StopIteration

Lorsqu'il est utilisé en boucle, l'exception StopIteration est masquée et entraîne silencieusement l'arrêt de la boucle. Mais avec une invocation explicite, on peut voir qu'une fois que l'itérateur a épuisé la séquence, l'accès à celui-ci entraîne une exception.

L'utilisation de la boucle for..in utilise également la méthode __iter__. Cela nous permet de démarrer de façon transparente l'itération sur une séquence. Mais si nous avons déjà l'itérateur, nous voulons pouvoir l'utiliser dans une boucle for de la même manière. Pour ce faire, les itérateurs, en plus next, sont également tenus d'avoir une méthode appelée __iter__ qui renvoie l'itérateur (self).

Le support pour l'itération est omniprésent dans Python : toutes les séquences et les conteneurs non ordonnés dans la bibliothèque standard permettent l'itération. Le concept est également étendu à d'autres choses : par ex. les objets file supportent l'itération sur les lignes des fichiers.

>>> f = open('/etc/fstab')
>>> f is f.__iter__()
True

file est lui-même un itérateur et sa méthode __iter__ ne crée pas d'objet distinct : il ne permet qu'un simple processus d'accès séquentiel.

I-B - Les expressions génératrices

Une deuxième manière de créer des objets itérateurs est via les expressions génératrices, la base des listes en compréhension. Pour augmenter la clarté, une expression génératrice doit toujours être entre parenthèses ou faire partie d'une expression. Si des parenthèses ordinaires (rondes) sont utilisées, un itérateur générateur est créé. Avec des crochets, la procédure est shuntée et nous obtenons un objet de type list.

1. >>> (i for i in nums)

2. <generator object <genexpr> at 0x...>

3. >>> [i for i in nums]

4. [1, 2, 3]

5. >>> list(i for i in nums)

6. [1, 2, 3]

La syntaxe de compréhension s'étend également aux dictionnaires et aux sets en compréhension. Un set (ensemble) est créé lorsque l'expression du générateur est entourée d'accolades. Un dict (dictionnaire) est créé lorsque l'expression du générateur contient des « paires » de la forme clef:valeur :

1. >>> {i for i in range(3)}

2. set([0, 1, 2])

3. >>> {i:i**2 for i in range(3)}

4. {0: 0, 1: 1, 2: 4}

Il faut signaler un petit problème spécifique : dans les anciennes versions de Python, il y aurait eu une fuite mémoire avec la variable d'indexation (i), mais c'est corrigé en Python 3.

I-C - Générateurs

Une troisième façon de créer des objets itératifs est d'appeler une fonction génératrice. Un générateur est une fonction contenant le mot clé yield. Il faut noter que la simple présence de ce mot-clé modifie complètement la nature de la fonction : il n'y a pas besoin que l'instruction yield soit appelée, ou même simplement accessible ; le fait que l'instruction soit présente suffit pour que la fonction soit considérée comme un générateur. Lorsqu'une fonction normale est appelée, les instructions contenues dans le corps de cette fonction sont exécutées. Lorsqu'un générateur est appelé, l'exécution s'arrête avant la première instruction dans le corps. Une invocation d'une fonction génératrice crée un objet générateur, adhérant au protocole itérateur. Comme pour les appels de fonctions normaux, les appels concurrents et récursifs de générateurs sont autorisés.

Lorsque next est appelé, la fonction est exécutée jusqu'à la première instruction yield. Chaque instruction yield rencontrée donne une valeur qui devient la valeur de retour de next. Après l'exécution de l'instruction de yield, l'exécution de cette fonction est suspendue.

1. >>> def f():

2. ...   yield 1

3. ...   yield 2

4. >>> f()

5. <generator object f at 0x...>

6. >>> gen = f()

7. >>> next(gen)

8. 1

9. >>> next(gen)

10. 2

11. >>> next(gen)

12. Traceback (most recent call last):

13. File "<stdin>", line 1, in <module>

14. StopIteration

Examinons le déroulement d'un simple appel de la fonction de générateur.

1. >>> def f():

2. ...   print("-- start --")

3. ...   yield 3

4. ...   print("-- middle --")

5. ...   yield 4

6. ...   print("-- finished --")

7. >>> gen = f()

8. >>> next(gen)

9. -- start --

10. 3

11. >>> next(gen)

12. -- middle --

13. 4

14. >>> next(gen)

15. -- finished --

16. Traceback (most recent call last):

17. ...

18. StopIteration

Contrairement à une fonction habituelle, dans laquelle l'exécution de f() entraînerait immédiatement l'exécution de la première instruction print, gen fait l'objet d'une affectation sans que le corps de la fonction soit exécuté. C'est seulement quand gen.next() est invoqué par next que les instructions sont exécutées jusqu'au premier yield. La deuxième instruction de next affiche -- middle -- et l'exécution s'arrête sur le second yield. La troisième instruction de next imprime -- finished -- et marque la fin de la fonction. Comme aucun yield n'a été atteint, une exception est signalée.

Que se passe-t-il avec la fonction après un yield, lorsque le contrôle passe à l'appelant ? L'état de chaque générateur est stocké dans l'objet générateur. Du point de vue de la fonction de générateur, on dirait presque qu'il s'agit d'un thread distinct, mais ce n'est qu'une illusion : il n'y a qu'un seul thread d'exécution, mais l'interpréteur conserve et restaure l'état entre les demandes de la valeur suivante.

Pourquoi les générateurs sont-ils utiles ? Comme indiqué dans les parties sur les itérateurs, une fonction génératrice est simplement une autre manière de créer un objet itérateur. Tout ce qui peut être fait avec des instructions yield, pourrait également être fait avec les méthodes next. Néanmoins, utiliser une fonction et laisser l'interpréteur s'occuper de créer un itérateur présentent des avantages. Une fonction peut être beaucoup plus courte que la définition d'une classe avec les méthodes next et __iter__ requises. Le plus important est qu'il est plus facile pour l'auteur du générateur de comprendre l'état qui est conservé dans les variables locales, par opposition aux attributs d'instance qui doivent être utilisés pour transmettre des données entre les invocations consécutives d'un objet itératif next.

Une question plus fréquente est de savoir pourquoi les itérateurs sont utiles ? Lorsqu'un itérateur est utilisé pour alimenter une boucle, la boucle devient très simple. Le code pour initialiser l'état, pour décider si la boucle est terminée, et pour trouver la valeur suivante est situé ailleurs. Cela met en évidence le corps de la boucle - la partie intéressante. En outre, il est possible de réutiliser le code itérateur ailleurs.

I-D - Communication bidirectionnelle

Chaque instruction yield entraîne la transmission d'une valeur à l'appelant. C'est la raison pour laquelle la PEP 255 a introduit la notion de générateur (implémentée en Python 2.2). Mais la communication en sens inverse est également utile. Une façon évidente serait un état externe, soit une variable globale, soit un objet mutable partagé. La communication directe est possible grâce à la PEP 342 (implémentée en 2.5). Elle est obtenue en transformant l'instruction yield précédemment fastidieuse en une expression. Lorsque le générateur reprend l'exécution après une instruction yield, l'appelant peut invoquer une méthode sur l'objet générateur pour passer une valeur dans le générateur, qui est ensuite renvoyée par l'instruction yield ou une autre méthode pour injecter une exception dans le générateur.

La première des nouvelles méthodes est send(value), qui est similaire à next(), mais transmet la valeur en paramètre dans le générateur qui sera utilisée comme valeur de l'expression yield. En fait, g.next() et g.send(None) sont équivalents.

La seconde des nouvelles méthodes est throw (type, value = None, traceback = None) qui est équivalent à :

raise type, value, tracebackau point de l'instruction yield.

Contrairement à raise (qui ajoute immédiatement une exception au point d'exécution actuel), throw() reprend le générateur et ne traite qu'ensuite l'exception. Le mot throw (jeter) a été choisi, car il suggère l'idée de placer l'exception dans un autre emplacement et est associé à des exceptions dans d'autres langages.

Que se passe-t-il lorsqu'une exception est déclenchée à l'intérieur du générateur ? Elle peut être déclenchée explicitement ou lors de l'exécution de certaines instructions, ou elle peut être injectée au point d'une instruction yield au moyen de la méthode throw(). Dans les deux cas, une telle exception se propage de manière standard : elle peut être interceptée par une clause except ou finally, sinon elle entraîne l'interruption de l'exécution de la fonction génératrice et se propage dans l'appelant.

Pour être complet, il convient de mentionner que les itérateurs générateurs ont également une méthode close(), qui peut être utilisée pour forcer un générateur à s'arrêter immédiatement, même s'il était en mesure de fournir plus de valeurs. Il permet à la méthode __del__ du générateur de détruire les objets contenant l'état du générateur.

Définissons un générateur qui imprime les paramètres passés via send et throw :

1. >>> import itertools

2. >>> def g():

3. ...     print('--start--')

4. ...     for i in itertools.count():

5. ...         print('--yielding %i--' % i)

6. ...         try:

7. ...             ans = yield i

8. ...         except GeneratorExit:

9. ...             print('--closing--')

10. ...             raise

11. ...         except Exception as e:

12. ...             print('--yield raised %r--' % e)

13. ...         else:

14. ...             print('--yield returned %s--' % ans)

16. >>> it = g()

17. >>> next(it)

18. --start--

19. --yielding 0--

20. 0

21. >>> it.send(11)

22. --yield returned 11--

23. --yielding 1--

24. 1

25. >>> it.throw(IndexError)

26. --yield raised IndexError()--

27. --yielding 2--

28. 2

29. >>> it.close()

30. --closing--

next ou __next__ ?

Dans les versions Python 2.x, la méthode itérative pour récupérer la valeur suivante s'appelle next. Elle est invoquée implicitement par la fonction globale next, ce qui signifie qu'elle devrait s'appeler __next__. Tout comme la fonction globale iter appelle __iter__. Cette incohérence est corrigée dans les versions Python 3.x, où it.next devient it.__ next__. Pour les autres méthodes du générateur, send et throw, la situation est plus compliquée, car elle n'est pas appelée implicitement par l'interpréteur. Néanmoins, il existe une proposition d'extension de syntaxe pour permettre à continue de prendre un argument qui sera transmis à l'instruction send de l'itérateur de la boucle. Si cette extension est acceptée, il est probable que gen.send devienne gen .__ send__. La dernière des méthodes du générateur, close, est bien évidemment mal nommée, car il est déjà invoqué implicitement.

I-E - Générateurs chaînés

Il s'agit d'un aperçu de la PEP 380 (introduite en Python 3.3).

Supposons que nous écrivions un générateur et que nous voulions fournir un certain nombre de valeurs générées par un deuxième générateur, un sous-générateur. Si notre seule préoccupation est de fournir des valeurs, cela peut se faire sans difficulté à l'aide d'une boucle telle que :

1. subgen = some_other_generator()

2. for v in subgen:

3. yield v

Cependant, si le sous-générateur doit interagir correctement avec l'appelant dans le cas des appels de send(), throw() et close(), les choses deviennent beaucoup plus difficiles. L'instruction yield doit être protégée par une structure try..except..finally similaire à celle définie dans la section précédente pour « déboguer » la fonction du générateur. Un tel code est fourni dans PEP 380 # id13 ; qu'il suffise de dire ici que la nouvelle syntaxe de yield à partir d'un sous-générateur a été introduite dans Python 3.3 (en 2013) :

yield from some_other_generator()

Cela fonctionne comme la boucle explicite ci-dessus, renvoyant à plusieurs reprises des valeurs fournies par some_other_generator jusqu'à ce que celui-ci soit épuisé, mais aussi envoie send, throw et close du sous-générateur.

II - Décorateurs

Étant donné que les fonctions et les classes sont des objets, elles peuvent être passées en paramètre. Et comme elles sont des objets mutables, elles peuvent être modifiées. Le fait de modifier une fonction ou un objet de classe après l'avoir construit, mais avant de le lier à son nom s'appelle décoration.

Deux choses se cachent derrière le mot « décorateur » : l'une est la fonction qui fait le travail de décoration, c'est-à-dire le travail réel ; et l'autre est l'expression qui adhère à la syntaxe du décorateur, c'est-à-dire un symbole et le nom de la fonction de décoration.

Une fonction peut être décorée en utilisant la syntaxe du décorateur pour les fonctions :

1. @decorator

2. def function():

3. pass

La fonction est définie de manière standard (ligne 2).

L'expression commençant par @ placée avant la définition de la fonction est le décorateur (ligne 1). La partie après @ doit être une expression simple, généralement ce n'est que le nom d'une fonction ou d'une classe. Cette partie est évaluée en premier, et, après que la fonction définie ci-dessous est prête, le décorateur est appelé avec l'objet de fonction nouvellement défini comme argument unique. La valeur renvoyée par le décorateur est attachée au nom original de la fonction.

Les décorateurs peuvent être appliqués aux fonctions et aux classes. Pour les classes, la sémantique est identique - la définition de classe d'origine est utilisée comme argument pour appeler le décorateur et tout ce qui est renvoyé est affecté au nom d'origine.

Avant la mise en œuvre de la syntaxe du décorateur (PEP 318), il était possible d'obtenir le même résultat en affectant la fonction ou l'objet de classe à une variable temporaire, puis en invoquant explicitement le décorateur et enfin en affectant la valeur de retour au nom de la fonction. Cela suggère qu'il faut écrire plus de code, et c'est bien le cas. Et le nom de la fonction décorée dupliquée comme variable temporaire doit être utilisé au moins trois fois, ce qui peut être une source d'erreurs. Néanmoins, l'exemple ci-dessus équivaut à ceci :

def function():                  # ①
pass
function = decorator(function)   # ②

Les décorateurs peuvent être empilés - l'ordre d'application est de bas en haut ou à l'envers. La sémantique est telle que la fonction définie à l'origine est utilisée comme argument pour le premier décorateur, tout ce qui est retourné par le premier décorateur est utilisé comme argument pour le second décorateur, et ainsi de suite, et tout ce qui est retourné par le dernier décorateur est lié au nom de la fonction originale.

La syntaxe du décorateur a été choisie pour sa lisibilité. Puisque le décorateur est spécifié avant l'en-tête de la fonction, il est évident qu'il ne fait pas partie du corps de la fonction et il est clair qu'il ne peut fonctionner que sur l'ensemble de la fonction. Comme l'expression préfixée avec @ est visible et est difficile à manquer (« dans votre visage », selon le PEP :)). Lorsqu'on utilise plus d'un décorateur, chacun est placé sur une ligne distincte de manière à rendre plus facile la lecture.

II-A - Remplacement ou modification de l'objet d'origine

Les décorateurs peuvent soit retourner la même fonction ou classe, soit renvoyer un objet complètement différent. Dans le premier cas, le décorateur peut exploiter le fait que les objets de fonction et de classe sont mutables et ajouter des attributs, par ex. ajouter un docstring à une classe. Un décorateur pourrait faire quelque chose d'utile même sans modifier l'objet, par exemple enregistrer la classe décorée dans un registre global. Dans le deuxième cas, pratiquement tout est possible : lorsque la fonction ou la classe d'origine est remplacée par quelque chose de différent, le nouvel objet peut être complètement différent. Néanmoins, un tel comportement n'est pas le but des décorateurs : ils sont destinés à modifier l'objet décoré, et non à faire quelque chose d'imprévisible. Par conséquent, lorsqu'une fonction est « décorée » et remplacée par une fonction différente, la nouvelle fonction appelle généralement la fonction d'origine, après avoir effectué des opérations préparatoires. De même, lorsqu'une classe est « décorée » en la remplaçant par une nouvelle classe, la nouvelle classe est généralement dérivée de la classe d'origine. Lorsque le but du décorateur est de faire quelque chose « à chaque fois », par exemple tracer chaque appel à une fonction décorée, seul le second type de décorateurs peut être utilisé. Si en revanche le premier type est suffisant, il est préférable de l'utiliser, car il est plus simple.

II-B - Les décorateurs implémentés comme classes et comme fonctions

La seule exigence sur les décorateurs est qu'ils peuvent être appelés avec un seul argument. Cela signifie que les décorateurs peuvent être implémentés comme des fonctions normales, ou comme des classes avec une méthode __call__, ou, en théorie, comme une fonction lambda.

Comparons les approches de fonction et de classe. L'expression du décorateur (la partie après @) peut être soit un nom, soit un appel. L'approche du nom nu est attrayante (moins de code, semble plus propre, etc.), mais n'est possible que si aucun argument n'est nécessaire pour personnaliser le décorateur. Les décorateurs écrits comme fonctions peuvent être utilisés dans ces deux cas :

1. >>> def simple_decorator(function):

2. ...   print("doing decoration")

3. ...   return function

4. >>> @simple_decorator

5. ... def function():

6. ...   print("inside function")

7. doing decoration

8. >>> function()

9. inside function

11. >>> def decorator_with_arguments(arg):

12. ...   print("defining the decorator")

13. ...   def _decorator(function):

14. ...       # Dans cette fonction interne, arg est également disponible

15. ...       print("doing decoration, %r" % arg)

16. ...       return function

17. ...   return _decorator

18. >>> @decorator_with_arguments("abc")

19. ... def function():

20. ...   print("inside function")

21. defining the decorator

22. doing decoration, 'abc'

23. >>> function()

24. inside function

Les deux décorateurs triviaux ci-dessus tombent dans la catégorie des décorateurs qui renvoient la fonction originale. S'ils devaient renvoyer une nouvelle fonction, un niveau supplémentaire d'imbrication serait nécessaire. Dans le pire des cas, on aura trois niveaux de fonctions imbriquées.

1. >>> def replacing_decorator_with_args(arg):

2. ...   print("defining the decorator")

3. ...   def _decorator(function):

4. ...       # Dans cette fonction interne, arg est également disponible

5. ...       print("doing decoration, %r" % arg)

6. ...       def _wrapper(*args, **kwargs):

7. ...           print("inside wrapper, %r %r" % (args, kwargs))

8. ...           return function(*args, **kwargs)

9. ...       return _wrapper

10. ...   return _decorator

11. >>> @replacing_decorator_with_args("abc")

12. ... def function(*args, **kwargs):

13. ...     print("inside function, %r %r" % (args, kwargs))

14. ...     return 14

15. defining the decorator

16. doing decoration, 'abc'

17. >>> function(11, 12)

18. inside wrapper, (11, 12) {}

19. inside function, (11, 12) {}

20. 14

La fonction _wrapper est définie de façon à accepter tous les arguments positionnels ou nommés. En général, nous ne pouvons pas savoir quels arguments la fonction décorée est censée accepter, de sorte que la fonction _wrapper passe tout à la fonction encapsulée. Une conséquence malheureuse est que la liste apparente des arguments est trompeuse.

Par rapport aux décorateurs définis comme des fonctions, les décorateurs complexes définis comme des classes sont plus simples. Lorsqu'un objet est créé, la méthode __init__ est seulement autorisée à renvoyer None et le type de l'objet créé ne peut pas être modifié. Cela signifie que lorsqu'un décorateur est défini comme une classe, utiliser la forme sans argument n'aurait pas beaucoup de sens : l'objet finalement décoré serait juste une instance de la classe de décoration, renvoyée par l'appel du constructeur, ce qui ne serait pas très utile. Par conséquent, il suffit de discuter des décorateurs basés sur les classes où les arguments sont donnés dans l'expression du décorateur et la méthode __init__ du décorateur est utilisée pour la construction du décorateur.

1. >>> class decorator_class(object):

2. ...   def __init__(self, arg):

3. ...       # Cette méthode est appelée dans l'expression du décorateur

4. ...       print("in decorator init, %s" % arg)

5. ...       self.arg = arg

6. ...   def __call__(self, function):

7. ...       # Cette méthode est appelée pour faire le travail

8. ...       print("in decorator call, %s" % self.arg)

9. ...       return function

10. >>> deco_instance = decorator_class('foo')

11. in decorator init, foo

12. >>> @deco_instance

13. ... def function(*args, **kwargs):

14. ...   print("in function, %s %s" % (args, kwargs))

15. in decorator call, foo

16. >>> function()

17. in function, () {}

Contrairement aux règles habituelles (PEP 8), les décorateurs écrits comme classes se comportent plus comme des fonctions et, par conséquent, leurs noms commencent souvent par une lettre minuscule.

En réalité, il n'est pas utile de créer une nouvelle classe simplement pour avoir un décorateur qui renvoie la fonction originale. Les objets sont censés conserver leur état, et de tels décorateurs sont plus utiles lorsque le décorateur renvoie un nouvel objet.

1. >>> class replacing_decorator_class(object):

2. ...   def __init__(self, arg):

3. ...       # cette méthode est appelée dans l'expression du décorateur

4. ...       print("in decorator init, %s" % arg)

5. ...       self.arg = arg

6. ...   def __call__(self, function):

7. ...       # Cette méthode est appelée pour faire le travail

8. ...       print("in decorator call, %s" % self.arg)

9. ...       self.function = function

10. ...       return self._wrapper

11. ...   def _wrapper(self, *args, **kwargs):

12. ...       print("in the wrapper, %s %s" % (args, kwargs))

13. ...       return self.function(*args, **kwargs)

14. >>> deco_instance = replacing_decorator_class('foo')

15. in decorator init, foo

16. >>> @deco_instance

17. ... def function(*args, **kwargs):

18. ...   print("in function, %s %s" % (args, kwargs))

19. in decorator call, foo

20. >>> function(11, 12)

21. in the wrapper, (11, 12) {}

22. in function, (11, 12) {}

Un décorateur comme celui-ci peut à peu près tout faire, car il peut modifier l'objet de la fonction d'origine et modifier ou même défigurer les arguments, appeler la fonction d'origine ou non, et ensuite modifier la valeur de retour.

II-C - Copier la docstring et d'autres attributs de la fonction d'origine

Lorsqu'une nouvelle fonction est renvoyée par le décorateur pour remplacer la fonction d'origine, une conséquence fâcheuse est que le nom de la fonction d'origine, la docstring d'origine, la liste des arguments d'origine sont perdus. Ces attributs de la fonction d'origine peuvent être partiellement « transplantés » à la nouvelle fonction en définissant __doc__ (la docstring), __module__ et __name__ (nom complet de la fonction) et __annotations__ (les informations supplémentaires sur les arguments et la valeur de retour de la fonction disponible dans Python 3). Cela peut se faire automatiquement en utilisant functools.update_wrapper.

functools.update_wrapper(wrapper, wrapped)

1. >>> import functools

2. >>> def replacing_decorator_with_args(arg):

3. ...   print("defining the decorator")

4. ...   def _decorator(function):

5. ...       print("doing decoration, %r" % arg)

6. ...       def _wrapper(*args, **kwargs):

7. ...           print("inside wrapper, %r %r" % (args, kwargs))

8. ...           return function(*args, **kwargs)

9. ...       return functools.update_wrapper(_wrapper, function)

10. ...   return _decorator

11. >>> @replacing_decorator_with_args("abc")

12. ... def function():

13. ...     "extensive documentation"

14. ...     print("inside function")

15. ...     return 14

16. defining the decorator

17. doing decoration, 'abc'

18. >>> function

19. <function function at 0x...>

20. >>> print(function.__doc__)

21. extensive documentation

Une chose importante manque dans la liste des attributs qui peuvent être copiés dans la fonction de remplacement : la liste des arguments. Les valeurs par défaut pour les arguments peuvent être modifiées à l'aide des attributs __defaults__, __kwdefaults__, mais malheureusement, la liste d'arguments elle-même ne peut pas être définie comme un attribut. Cela signifie que help(function) affichera une liste d'arguments inutiles qui perturbera l'utilisateur de la fonction. Une manière efficace, mais laide, de résoudre ce problème, c'est de créer dynamiquement un wrapper, en utilisant eval. Cela peut être automatisé en utilisant le module externe decorator. Il fournit un support decorator pour le décorateur, qui prend un wrapper et le transforme en un décorateur qui préserve la signature de la fonction.

Pour résumer, les décorateurs doivent toujours utiliser functools.update_wrapper ou d'autres moyens pour copier les attributs de la fonction.

II-D - Exemples dans la bibliothèque standard

Tout d'abord, il convient de noter qu'il existe un certain nombre de décorateurs utiles disponibles dans la bibliothèque standard. Il y a trois décorateurs qui font partie du langage :

- avec classmethod, une méthode devient une « méthode de classe », ce qui signifie qu'elle peut être invoquée sans devoir instancier un objet de cette classe. Lorsqu'une méthode normale est invoquée, l'interpréteur insère l'objet d'instance comme premier paramètre de position, self. Lorsqu'une méthode de classe est invoquée, la classe elle-même est fournie comme le premier paramètre, souvent appelé cls.

Les méthodes de classe sont toujours accessibles via l'espace de noms de la classe, de sorte qu'elles ne polluent pas l'espace de noms du module. Les méthodes de classe peuvent être utilisées pour fournir des constructeurs de remplacement :

1. class Array(object):

2. def __init__(self, data):

3. self.data = data

5. @classmethod

6. def fromfile(cls, file):

7. data = numpy.load(file)

8. return cls(data)

C'est plus propre que d'utiliser une multitude d'indicateurs à __init__ ;

- staticmethod s'applique à des méthodes pour les rendre « statiques », c'est-à-dire en faire essentiellement des fonctions normales, mais accessibles par l'espace de noms de la classe. Cela peut être utile lorsque la fonction n'est nécessaire que dans cette classe (son nom serait alors préfixé avec _), ou lorsque l'on veut que l'utilisateur pense que la méthode est connectée à la classe, malgré une implémentation qui n'exige pas cela ;

- property est la réponse pythonique au problème des accesseurs (getters) et des mutateurs (setters). Une méthode décorée avec property devient un accesseur qui est automatiquement appelé pour l'accès aux attributs.

1. >>> class A(object):

2. ...   @property

3. ...   def a(self):

4. ...     "an important attribute"

5. ...     return "a value"

6. >>> A.a

7. <property object at 0x...>

8. >>> A().a

9. 'a value'

Dans cet exemple, A.a est un attribut en lecture seule. Il est également documenté : help (A) intègre la docstring pour l'attribut a tiré de l'accesseur. Définir a comme une propriété lui permet d'être calculé à la volée et par conséquent le rend accessible en lecture seule, car aucun mutateur n'est défini.

Pour avoir un accesseur et un mutateur, deux méthodes sont évidemment nécessaires. Depuis Python 2.6, la syntaxe suivante est adoptée :

1. class Rectangle(object):

2. def __init__(self, edge):

3. self.edge = edge

5. @property

6. def area(self):

7. """Aire calculée.

9. Ceci met à jour la longueur du côté à la valeur appropriée.

10. """

11. return self.edge**2

13. @area.setter

14. def area(self, area):

15. self.edge = area ** 0.5

Cela fonctionne de sorte que le décorateur property remplace l'accesseur par un objet propriété. Cet objet à son tour comporte trois méthodes, getter, setter et deleter, qui peuvent être utilisées comme décorateurs. Leur travail est de définir l'accesseur, le mutateur et l'effaceur de l'objet propriété (stocké comme attributs fget, fset et fdel). L'accesseur peut être configuré comme dans l'exemple ci-dessus, lors de la création de l'objet. Lors de la définition du mutateur, nous avons déjà l'objet de propriété sous area, et nous ajoutons le mutateur à celui-ci en utilisant la méthode setter. Tout cela se produit lorsque nous créons la classe.

Par la suite, lorsqu'une instance de la classe est créée, l'objet de propriété est spécial. Lorsque l'interpréteur exécute l'accès, l'affectation ou la suppression des attributs, le travail est délégué aux méthodes de l'objet de propriété.

Pour que tout soit clair, définissons un exemple de « débogage » :

1. >>> class D(object):

2. ...    @property

3. ...    def a(self):

4. ...      print("getting 1")

5. ...      return 1

6. ...    @a.setter

7. ...    def a(self, value):

8. ...      print("setting %r" % value)

9. ...    @a.deleter

10. ...    def a(self):

11. ...      print("deleting")

12. >>> D.a

13. <property object at 0x...>

14. >>> D.a.fget

15. <function ...>

16. >>> D.a.fset

17. <function ...>

18. >>> D.a.fdel

19. <function ...>

20. >>> d = D()               # ...varie, ce n'est pas la même fonction `a`

21. >>> d.a

22. getting 1

23. 1

24. >>> d.a = 2

25. setting 2

26. >>> del d.a

27. deleting

28. >>> d.a

29. getting 1

30. 1

Les propriétés sont une sorte d'extension de la syntaxe des décorateurs. L'une des prémisses de la syntaxe du décorateur - la non-duplication du nom - est violée, mais rien de mieux n'a été inventé jusqu'à présent. Utiliser le même nom pour les méthodes d'accès, de mutation et d'effacement est une bonne pratique stylistique.

Voici quelques exemples plus récents :

- functools.lru_cache mémoïse une fonction arbitraire en maintenant un cache limité de paires argument-réponse (Python 3.2)

- functools.total_ordering est un décorateur de classe qui remplit les méthodes de comparaison d'ordre manquantes (__lt__, __gt__, __le__……) sur la base du seul qui soit disponible (Python 2.7).

II-E - Dépréciation de fonctions

Supposons que nous voulions afficher un avertissement de dépréciation sur stderr lors de la première invocation d'une fonction que nous n'aimons plus. Si nous ne voulons pas modifier la fonction, nous pouvons utiliser un décorateur :

1. class deprecated(object):

2. """Imprime un avertissement de dépréciation lors de la première utilisation de la fonction.

4. >>> @deprecated()                    # doctest: +SKIP

5. ... def f():

6. ...     pass

7. >>> f()                              # doctest: +SKIP

8. f is deprecated

9. """

10. def __call__(self, func):

11. self.func = func

12. self.count = 0

13. return self._wrapper

14. def _wrapper(self, *args, **kwargs):

15. self.count += 1

16. if self.count == 1:

17. print self.func.__name__, 'is deprecated'

18. return self.func(*args, **kwargs)

Il est aussi possible de mettre en place ce genre d'avertissement sous la forme d'une fonction :

1. def deprecated(func):

2. """Imprime un avertissement de dépréciation lors de la première utilisation de la fonction.

4. >>> @deprecated                      # doctest: +SKIP

5. ... def f():

6. ...     pass

7. >>> f()                              # doctest: +SKIP

8. f is deprecated

9. """

10. count = [0]

11. def wrapper(*args, **kwargs):

12. count[0] += 1

13. if count[0] == 1:

14. print func.__name__, 'is deprecated'

15. return func(*args, **kwargs)

16. return wrapper

II-F - Un décorateur de suppression de boucles While

Considérons une fonction qui renvoie une liste de choses, et cette liste est créée en exécutant une boucle. Si nous ne savons pas combien d'objets seront nécessaires, la façon standard de le faire ressemble à ceci :

def find_answers():
answers = []
while True:
ans = look_for_next_answer()
if ans is None:
break
answers.append(ans)
return answers

C'est bien tant que le corps de la boucle reste assez compact. Quand cela devient plus compliqué, comme c'est souvent le cas dans un code réel, cela devient assez illisible. Nous pourrions simplifier cela en utilisant des instructions yield, mais l'utilisateur devrait appeler explicitement list(find_answers()).

Nous pouvons définir un décorateur qui nous construit la liste :

1. def vectorized(generator_func):

2. def wrapper(*args, **kwargs):

3. return list(generator_func(*args, **kwargs))

4. return functools.update_wrapper(wrapper, generator_func)

Notre fonction devient alors :

@vectorized
def find_answers():
while True:
ans = look_for_next_answer()
if ans is None:
break
yield ans

II-G - Un système d'enregistrement des plugins

Il s'agit d'un décorateur de classe qui ne modifie pas la classe, mais la place dans un registre global. Il appartient à la catégorie des décorateurs qui renvoient l'objet d'origine :

1. class WordProcessor(object):

2. PLUGINS = []

3. def process(self, text):

4. for plugin in self.PLUGINS:

5. text = plugin().cleanup(text)

6. return text

8. @classmethod

9. def plugin(cls, plugin):

10. cls.PLUGINS.append(plugin)

12. @WordProcessor.plugin

13. class CleanMdashesExtension(object):

14. def cleanup(self, text):

15. return text.replace('&mdash;', u'\N{em dash}')

Nous utilisons ici un décorateur pour décentraliser l'enregistrement des plugins. Nous appelons notre décorateur avec un nom, au lieu d'un verbe, parce que nous l'utilisons pour déclarer que notre classe est un plugin pour WordProcessor. La méthode plugin ajoute simplement la classe à la liste des plugins.

Un mot sur le plugin lui-même : il remplace l'entité HTML pour le tiret long (&mdash;) par un véritable caractère tiret long en Unicode. Il exploite la notation littérale unicode pour insérer un caractère en utilisant son nom dans la base de données unicode (« em dash »). Si le caractère Unicode était inséré directement, il serait impossible de le distinguer d'un tiret long dans le code source d'un programme.

III - Gestionnaires de contexte

Un gestionnaire de contexte est un objet avec les méthodes __enter__ et __exit__ qui peuvent être utilisées dans l'instruction with :

with manager as var:
do_something(var)

est le cas le plus simple équivalent à :

var = manager.__enter__()
try:
do_something(var)
finally:
manager.__exit__()

Autrement dit, le protocole de gestionnaire de contexte défini dans la PEP 343 permet l'extraction de la partie ennuyeuse d'une structure try..except..finally dans une classe séparée laissant seulement le bloc intéressant do_something.

1. La méthode __enter__ est appelée d'abord. Il peut renvoyer une valeur qui sera affectée à var. La partie as est facultative : si elle n'est pas présente, la valeur renvoyée par __enter__ est simplement ignorée.

2. Le bloc de code en dessous de with est exécuté. Tout comme avec les clauses try, il peut être exécuté avec succès jusqu'à la fin, ou il peut s'interrompre sur un break, un continue ou un return, ou encore déclencher une exception. Quoi qu'il en soit, une fois le bloc terminé, on appelle la méthode __exit__. Si une exception a été déclenchée, les informations sur l'exception sont passées à __exit__, qui est décrit ci-dessous dans la prochaine sous-section. Dans le cas normal, les exceptions peuvent être ignorées, tout comme dans une clause finally, et elles seront déclenchées à nouveau après la fin de __exit__.

Supposons que nous voulions nous assurer que le fichier soit fermé immédiatement après la fin de l'écriture :

1. >>> class closing(object):

2. ...   def __init__(self, obj):

3. ...     self.obj = obj

4. ...   def __enter__(self):

5. ...     return self.obj

6. ...   def __exit__(self, *args):

7. ...     self.obj.close()

8. >>> with closing(open('/tmp/file', 'w')) as f:

9. ...   f.write('the contents\n')

Ici, nous nous sommes assuré que la méthode f.close () est appelée lorsque le bloc with se termine. Comme la fermeture des fichiers est une opération très courante, ce genre d'opération est assuré dans la classe file. Elle a une méthode __exit__ qui appelle close et peut être utilisée comme gestionnaire de contexte :

1. >>> with open('/tmp/file', 'a') as f:

2. ...   f.write('more contents\n')

Une utilisation courante de try..finally est de libérer des ressources. Différents cas sont implémentés de la même manière : dans la phase __enter__, la ressource est acquise ; dans la phase __exit__ elle est libérée ; et l'exception, si elle est déclenchée, se propage. Comme pour les fichiers, il y a souvent une opération naturelle à effectuer après l'utilisation de l'objet et il est très pratique de le faire de façon automatique. À chaque nouvelle version, Python offre de nouvelles possibilités :

- tous les fichiers et objets assimilés :

- file : automatiquement fermé,

- fileinput, tempfile (py >= 3.2) ,

- bz2.BZ2File, gzip.GzipFile, tarfile.TarFile, zipfile.ZipFile,

- ftplib, nntplib : ferme la connexion (py >= 3.2 ou 3.3) ;

- verrous

- multiprocessing.RLock : Verrouillage et déverrouillage,

- multiprocessing.Semaphore,

- memoryview : automatiquement libéré (py >= 3.2 and 2.7) ;

- decimal.localcontext : modifie temporairement la précision de calcul ;

- _winreg.PyHKEY : ouvre et ferme la clé ;

- warnings.catch_warnings : détruit les avertissements temporairement ;

- contextlib.closing : identique à l'exemple ci-dessus, appelle close ;

- Programmation en parallèle

- concurrent.futures.ThreadPoolExecutor : invoque en parallèle puis détruit le pool de thread (py >= 3.2),

- concurrent.futures.ProcessPoolExecutor : invoque en parallèle puis détruit le pool de processus (py >= 3.2),

- nogil : résout le problème GIL temporairement (seulement cython  :( ).

III-A - Intercepter les exceptions

Lorsqu'une exception est déclenchée dans le bloc with, elle est transmise en paramètre à __exit__. Trois arguments sont utilisés, identiques à ceux renvoyés par sys.exc_info() : type, valeur, traceback. Lorsqu'il n'y a aucune exception, les arguments sont positionnés à None. Le gestionnaire de contexte peut « avaler » l'exception en renvoyant une valeur réelle de __exit__. Les exceptions peuvent être facilement ignorées, car si __exit__ n'utilise pas return et n'échoue qu'à la fin, None est renvoyé, une valeur fausse, et donc l'exception est déclenchée après la fin de __exit__.

La possibilité d'intercepter des exceptions ouvre des possibilités intéressantes. Un exemple classique est celui des tests unitaires - nous voulons nous assurer que le code signale le bon type d'exception :

1. class assert_raises(object):

2. # basé sur pytest et unittest.TestCase

3. def __init__(self, type):

4. self.type = type

5. def __enter__(self):

6. pass

7. def __exit__(self, type, value, traceback):

8. if type is None:

9. raise AssertionError('exception expected')

10. if issubclass(type, self.type):

11. return True # swallow the expected exception

12. raise AssertionError('wrong exception type')

14. with assert_raises(KeyError):

15. {}['foo']

III-B - Utilisation de générateurs pour définir les gestionnaires de contexte

Lors de la discussion sur les générateurs, on a dit que nous préférions les générateurs aux itérateurs mis en œuvre en tant que classes parce qu'ils sont plus courts et plus faciles, et parce que l'état est stocké dans une variable locale, et non une variable d'instance. D'autre part, comme nous l'avons vu dans la section sur la communication bidirectionnelle, le flux de données entre le générateur et son appelant peut être bidirectionnel. Cela comprend les exceptions, qui peuvent être déclenchées dans le générateur. Nous souhaitons implémenter des gestionnaires de contexte sous la forme de fonctions génératrices spéciales. En fait, le protocole de générateur a été conçu pour permettre ce cas d'utilisation.

1. @contextlib.contextmanager

2. def some_generator(<arguments>):

3. <setup>

4. try:

5. yield <value>

6. finally:

7. <cleanup>

L'assistant contextelib.contextmanager prend un générateur et le transforme en un gestionnaire de contexte. Le générateur doit obéir à certaines règles qui sont appliquées par la fonction wrapper - surtout il doit y avoir un appel à l'instruction yield et un seul. La partie avant yield est exécutée à partir de __enter__, le bloc de code protégé par le gestionnaire de contexte est exécuté lorsque le générateur est suspendu à yield et le reste est exécuté dans __exit__. Si une exception est signalée, l'interpréteur la transmet au wrapper par le biais des arguments d'__exit__, et la fonction wrapper déclenche alors l'exception au point de l'instruction yield. Grâce à l'utilisation de générateurs, le gestionnaire de contexte est plus court et plus simple.

Réécrivons l'exemple closing sous la forme d'un générateur :

@contextlib.contextmanager
def closing(obj):
try:
yield obj
finally:
obj.close()

Réécrivons l'exemple assert_raises sous la forme d'un générateur :

@contextlib.contextmanager
def assert_raises(type):
try:
yield
except type:
return
except Exception as value:
raise AssertionError('wrong exception type')
else:
raise AssertionError('exception expected')

Nous utilisons ici un décorateur pour transformer les fonctions du générateur en gestionnaires de contexte !