Guide pour l’utilisation des descripteurs
*****************************************

Author:
   Raymond Hettinger

Contact:
   <python at rcn dot com>


Sommaire
^^^^^^^^

* Guide pour l’utilisation des descripteurs

  * Résumé

  * Définition et introduction

  * Protocole descripteur

  * Invocation des descripteurs

  * Exemple de descripteur

  * Propriétés

  * Fonctions et méthodes

  * Méthodes statiques et méthodes de classe


Résumé
======

Defines descriptors, summarizes the protocol, and shows how
descriptors are called.  Examines a custom descriptor and several
built-in python descriptors including functions, properties, static
methods, and class methods.  Shows how each works by giving a pure
Python equivalent and a sample application.

L’apprentissage des descripteurs permet non seulement d’accéder à un
ensemble d’outils plus vaste, mais aussi de mieux comprendre le
fonctionnement de Python et d’apprécier l’élégance de sa conception.


Définition et introduction
==========================

En général, un descripteur est un attribut objet avec un «
comportement contraignant », dont l’accès à l’attribut a été remplacé
par des méthodes dans le protocole du descripteur.  Ces méthodes sont
: "__get__()", "__set__()", et "__delete__()".  Si l’une de ces
méthodes est définie pour un objet, il s’agit d’un descripteur.

The default behavior for attribute access is to get, set, or delete
the attribute from an object’s dictionary.  For instance, "a.x" has a
lookup chain starting with "a.__dict__['x']", then
"type(a).__dict__['x']", and continuing through the base classes of
"type(a)" excluding metaclasses. If the looked-up value is an object
defining one of the descriptor methods, then Python may override the
default behavior and invoke the descriptor method instead. Where this
occurs in the precedence chain depends on which descriptor methods
were defined.  Note that descriptors are only invoked for new style
objects or classes (a class is new style if it inherits from "object"
or "type").

Les descripteurs sont un protocole puissant et à usage général.  Ils
sont le mécanisme derrière les propriétés, les méthodes, les méthodes
statiques, les méthodes de classes et "super()". Ils sont utilisés
dans tout Python lui-même pour implémenter les nouvelles classes de
style introduites dans la version 2.2.  Les descripteurs simplifient
le code C sous-jacent et offrent un ensemble flexible de nouveaux
outils pour les programmes Python quotidiens.


Protocole descripteur
=====================

"descr.__get__(self, obj, type=None) --> value"

"descr.__set__(self, obj, value) --> None"

"descr.__delete__(self, obj) --> None"

C’est tout ce qu’il y a à faire.  Définissez n’importe laquelle de ces
méthodes et un objet est considéré comme un descripteur et peut
remplacer le comportement par défaut lorsqu’il est recherché comme un
attribut.

Si un objet définit à la fois "__get__()" et "__set__()", il est
considéré comme un descripteur de données.  Les descripteurs qui ne
définissent que "__get__()" sont appelés descripteurs *non-data* (ils
sont généralement utilisés pour des méthodes mais d’autres
utilisations sont possibles).

Les descripteurs de données et les descripteurs *non-data* diffèrent
dans la façon dont les dérogations sont calculées en ce qui concerne
les entrées du dictionnaire d’une instance.  Si le dictionnaire d’une
instance comporte une entrée portant le même nom qu’un descripteur de
données, le descripteur de données est prioritaire.  Si le
dictionnaire d’une instance comporte une entrée portant le même nom
qu’un descripteur *non-data*, l’entrée du dictionnaire a la priorité.

Pour faire un descripteur de données en lecture seule, définissez à la
fois "__get__()" et "__set__()" avec "__set__()" levant une erreur
"AttributeError" quand il est appelé.  Définir la méthode
"__set__set__()" avec une exception élevant le caractère générique est
suffisant pour en faire un descripteur de données.


Invocation des descripteurs
===========================

Un descripteur peut être appelé directement par son nom de méthode.
Par exemple, "d.__get__(obj)".

Alternativement, il est plus courant qu’un descripteur soit invoqué
automatiquement lors de l’accès aux attributs.  Par exemple, "obj.d"
recherche "d" dans le dictionnaire de "obj.d".  Si "d" définit la
méthode "__get__()", alors "d.__get__(obj)" est invoqué selon les
règles de priorité énumérées ci-dessous.

The details of invocation depend on whether "obj" is an object or a
class. Either way, descriptors only work for new style objects and
classes.  A class is new style if it is a subclass of "object".

Pour les objets, la machinerie est en "object.__getattribute__()" qui
transforme "b.x" en "type(b).__dict__['x'].__get__(b, type(b)]".
L’implémentation fonctionne à travers une chaîne de priorité qui donne
la priorité aux descripteurs de données sur les variables d’instance,
la priorité aux variables d’instance sur les descripteurs *non-data*,
et attribue la priorité la plus faible à "__getattr__()" si fourni.
L’implémentation complète de C peut être trouvée dans
"PyObject_GenericGetAttr()" dans Objects/object.c.

Pour les classes, la machinerie est dans "type.__getattribute__()" qui
transforme "B.x" en "B.__dict__['x'].__get__(None, B)".  En Python
pur, il ressemble à :

   def __getattribute__(self, key):
       "Emulate type_getattro() in Objects/typeobject.c"
       v = object.__getattribute__(self, key)
       if hasattr(v, '__get__'):
           return v.__get__(None, self)
       return v

Les points importants à retenir sont :

* les descripteurs sont appelés par la méthode "__getattribute__()"

* redéfinition "__getattribute____()" empêche les appels
  automatiques de descripteurs

* "__getattribute__()" is only available with new style classes and
  objects

* "objet.__getattribute__()" et "type.__getattribute__()" font
  différents appels à "__get__()".

* les descripteurs de données remplacent toujours les dictionnaires
  d’instances.

* les descripteurs *non-data* peuvent être remplacés par des
  dictionnaires d’instance.

L’objet retourné par "super()" a aussi une méthode personnalisée
"__getattribute__()" pour appeler les descripteurs.  L’appel "super(B,
obj).m()" recherche "obj.__class__.__mro__" pour la classe de base "A"
immédiatement après "B" et renvoie ensuite
"A.__dict__['m'].__get__(obj, B)".  Si ce n’est pas un descripteur,
"m" est retourné inchangé.  Si ce n’est pas dans le dictionnaire, "m"
renvoie à une recherche avec "object.__getattribute__()".

Note, in Python 2.2, "super(B, obj).m()" would only invoke "__get__()"
if "m" was a data descriptor.  In Python 2.3, non-data descriptors
also get invoked unless an old-style class is involved.  The
implementation details are in "super_getattro()" in
Objects/typeobject.c.

Les détails ci-dessus montrent que le mécanisme des descripteurs est
intégré dans les méthodes "__getattribute__()" pour "object", "type"
et "super()". Les classes héritent de cette machinerie lorsqu’elles
dérivent de "object" ou si elles ont une méta-classe fournissant des
fonctionnalités similaires. De même, les classes peuvent désactiver
l’appel de descripteurs en remplaçant "__getattribute__()".


Exemple de descripteur
======================

Le code suivant crée une classe dont les objets sont des descripteurs
de données qui impriment un message pour chaque lecture ou écriture.
Redefinir "__getattribute__()" est une approche alternative qui
pourrait le faire pour chaque attribut.  Cependant, ce descripteur
n’est utile que pour le suivi de quelques attributs choisis :

   class RevealAccess(object):
       """A data descriptor that sets and returns values
          normally and prints a message logging their access.
       """

       def __init__(self, initval=None, name='var'):
           self.val = initval
           self.name = name

       def __get__(self, obj, objtype):
           print 'Retrieving', self.name
           return self.val

       def __set__(self, obj, val):
           print 'Updating', self.name
           self.val = val

   >>> class MyClass(object):
   ...     x = RevealAccess(10, 'var "x"')
   ...     y = 5
   ...
   >>> m = MyClass()
   >>> m.x
   Retrieving var "x"
   10
   >>> m.x = 20
   Updating var "x"
   >>> m.x
   Retrieving var "x"
   20
   >>> m.y
   5

The protocol is simple and offers exciting possibilities.  Several use
cases are so common that they have been packaged into individual
function calls. Properties, bound and unbound methods, static methods,
and class methods are all based on the descriptor protocol.


Propriétés
==========

Appeler "property()" est une façon succincte de construire un
descripteur de données qui déclenche des appels de fonction lors de
l’accès à un attribut.  Sa signature est :

   property(fget=None, fset=None, fdel=None, doc=None) -> property attribute

La documentation montre une utilisation typique pour définir un
attribut géré "x" :

   class C(object):
       def getx(self): return self.__x
       def setx(self, value): self.__x = value
       def delx(self): del self.__x
       x = property(getx, setx, delx, "I'm the 'x' property.")

Pour voir comment "property()" est implémenté dans le protocole du
descripteur, voici un un équivalent Python pur :

   class Property(object):
       "Emulate PyProperty_Type() in Objects/descrobject.c"

       def __init__(self, fget=None, fset=None, fdel=None, doc=None):
           self.fget = fget
           self.fset = fset
           self.fdel = fdel
           if doc is None and fget is not None:
               doc = fget.__doc__
           self.__doc__ = doc

       def __get__(self, obj, objtype=None):
           if obj is None:
               return self
           if self.fget is None:
               raise AttributeError("unreadable attribute")
           return self.fget(obj)

       def __set__(self, obj, value):
           if self.fset is None:
               raise AttributeError("can't set attribute")
           self.fset(obj, value)

       def __delete__(self, obj):
           if self.fdel is None:
               raise AttributeError("can't delete attribute")
           self.fdel(obj)

       def getter(self, fget):
           return type(self)(fget, self.fset, self.fdel, self.__doc__)

       def setter(self, fset):
           return type(self)(self.fget, fset, self.fdel, self.__doc__)

       def deleter(self, fdel):
           return type(self)(self.fget, self.fset, fdel, self.__doc__)

La fonction "property()" intégrée aide chaque fois qu’une interface
utilisateur a accordé l’accès à un attribut et que des modifications
ultérieures nécessitent l’intervention d’une méthode.

Par exemple, une classe de tableur peut donner accès à une valeur de
cellule via "Cell('b10').value". Les améliorations ultérieures du
programme exigent que la cellule soit recalculée à chaque accès ;
cependant, le programmeur ne veut pas affecter le code client existant
accédant directement à l’attribut.  La solution consiste à envelopper
l’accès à l’attribut de valeur dans un descripteur de données de
propriété :

   class Cell(object):
       . . .
       def getvalue(self):
           "Recalculate the cell before returning value"
           self.recalc()
           return self._value
       value = property(getvalue)


Fonctions et méthodes
=====================

Les fonctionnalités orientées objet de Python sont construites sur un
environnement basé sur des fonctions. À l’aide de descripteurs *non-
data*, les deux sont fusionnés de façon transparente.

Class dictionaries store methods as functions.  In a class definition,
methods are written using "def" and "lambda", the usual tools for
creating functions.  The only difference from regular functions is
that the first argument is reserved for the object instance.  By
Python convention, the instance reference is called *self* but may be
called *this* or any other variable name.

To support method calls, functions include the "__get__()" method for
binding methods during attribute access.  This means that all
functions are non-data descriptors which return bound or unbound
methods depending whether they are invoked from an object or a class.
In pure python, it works like this:

   class Function(object):
       . . .
       def __get__(self, obj, objtype=None):
           "Simulate func_descr_get() in Objects/funcobject.c"
           return types.MethodType(self, obj, objtype)

L’exécution de l’interpréteur montre comment le descripteur de
fonction se comporte dans la pratique :

   >>> class D(object):
   ...     def f(self, x):
   ...         return x
   ...
   >>> d = D()
   >>> D.__dict__['f']  # Stored internally as a function
   <function f at 0x00C45070>
   >>> D.f              # Get from a class becomes an unbound method
   <unbound method D.f>
   >>> d.f              # Get from an instance becomes a bound method
   <bound method D.f of <__main__.D object at 0x00B18C90>>

The output suggests that bound and unbound methods are two different
types. While they could have been implemented that way, the actual C
implementation of "PyMethod_Type" in Objects/classobject.c is a single
object with two different representations depending on whether the
"im_self" field is set or is *NULL* (the C equivalent of "None").

Likewise, the effects of calling a method object depend on the
"im_self" field. If set (meaning bound), the original function (stored
in the "im_func" field) is called as expected with the first argument
set to the instance.  If unbound, all of the arguments are passed
unchanged to the original function. The actual C implementation of
"instancemethod_call()" is only slightly more complex in that it
includes some type checking.


Méthodes statiques et méthodes de classe
========================================

Les descripteurs *non-data* fournissent un mécanisme simple pour les
variations des patrons habituels des fonctions de liaison dans les
méthodes.

Pour résumer, les fonctions ont une méthode "__get__()" pour qu’elles
puissent être converties en méthode lorsqu’on y accède comme
attributs. Le descripteur *non-data* transforme un appel
"obj.f(*args)``en ``f(obj, *args)".  Appeler "klass.f(*args)" devient
"f(*args)".

Ce tableau résume le lien (*binding*) et ses deux variantes les plus
utiles :

   +-------------------+------------------------+--------------------+
   | Transformation    | Appelé depuis un Objet | Appelé depuis un   |
   |                   |                        | Classe             |
   +===================+========================+====================+
   | fonction          | f(obj, *args)          | f(*args)           |
   +-------------------+------------------------+--------------------+
   | méthode statique  | f(*args)               | f(*args)           |
   +-------------------+------------------------+--------------------+
   | méthode de classe | f(type(obj), *args)    | f(klass, *args)    |
   +-------------------+------------------------+--------------------+

Les méthodes statiques renvoient la fonction sous-jacente sans
modifications.  Appeler "c.f" ou "C.f" est l’équivalent d’une
recherche directe dans "objet.__getattribute__(c, "f")" ou
"objet.__getattribute__(C, "f")". Par conséquent, la fonction devient
accessible de manière identique à partir d’un objet ou d’une classe.

Les bonnes candidates pour être méthode statique sont des méthodes qui
ne font pas référence à la variable "self".

Par exemple, un paquet traitant de statistiques peut inclure une
classe qui est un conteneur pour des données expérimentales.  La
classe fournit les méthodes normales pour calculer la moyenne, la
moyenne, la médiane et d’autres statistiques descriptives qui
dépendent des données. Cependant, il peut y avoir des fonctions utiles
qui sont conceptuellement liées mais qui ne dépendent pas des données.
Par exemple, "erf(x)" est une routine de conversion pratique qui
apparaît dans le travail statistique mais qui ne dépend pas
directement d’un ensemble de données particulier. Elle peut être
appelée à partir d’un objet ou de la classe :  "s.erf(1.5) --> .9332`"
ou "Sample.erf(1.5) --> .9332".

Depuis que les méthodes statiques renvoient la fonction sous-jacente
sans changement, les exemples d’appels ne sont pas excitants :

   >>> class E(object):
   ...     def f(x):
   ...         print x
   ...     f = staticmethod(f)
   ...
   >>> print E.f(3)
   3
   >>> print E().f(3)
   3

En utilisant le protocole de descripteur *non-data*, une version
Python pure de "staticmethod()" ressemblerait à ceci :

   class StaticMethod(object):
       "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

       def __init__(self, f):
           self.f = f

       def __get__(self, obj, objtype=None):
           return self.f

Contrairement aux méthodes statiques, les méthodes de classe
préchargent la référence de classe dans la liste d’arguments avant
d’appeler la fonction.  Ce format est le même que l’appelant soit un
objet ou une classe :

   >>> class E(object):
   ...     def f(klass, x):
   ...          return klass.__name__, x
   ...     f = classmethod(f)
   ...
   >>> print E.f(3)
   ('E', 3)
   >>> print E().f(3)
   ('E', 3)

Ce comportement est utile lorsque la fonction n’a besoin que d’une
référence de classe et ne se soucie pas des données sous-jacentes.
Une des utilisations des méthodes de classe est de créer d’autres
constructeurs de classe.  En Python 2.3, la méthode de classe
"dict.fromkeys()" crée un nouveau dictionnaire à partir d’une liste de
clés.  L’équivalent Python pur est :

   class Dict(object):
       . . .
       def fromkeys(klass, iterable, value=None):
           "Emulate dict_fromkeys() in Objects/dictobject.c"
           d = klass()
           for key in iterable:
               d[key] = value
           return d
       fromkeys = classmethod(fromkeys)

Maintenant un nouveau dictionnaire de clés uniques peut être construit
comme ceci :

   >>> Dict.fromkeys('abracadabra')
   {'a': None, 'r': None, 'b': None, 'c': None, 'd': None}

En utilisant le protocole de descripteur *non-data*, une version
Python pure de "classmethod()" ressemblerait à ceci :

   class ClassMethod(object):
       "Emulate PyClassMethod_Type() in Objects/funcobject.c"

       def __init__(self, f):
           self.f = f

       def __get__(self, obj, klass=None):
           if klass is None:
               klass = type(obj)
           def newfunc(*args):
               return self.f(klass, *args)
           return newfunc
