# 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