# 3. Modèle de données

## 3.1. Objets, valeurs et types

En Python, les données sont représentées sous forme d'objets. Toutes les données d'un programme Python sont représentées par des objets ou par des relations entre les objets (dans un certain sens, et en conformité avec le modèle de Von Neumann d'« ordinateur à programme enregistré », le code est aussi représenté par des objets).

Every object has an identity, a type and a value. An object's identity never changes once it has been created; you may think of it as the object's address in memory. The `is` operator compares the identity of two objects; the `id()` function returns an integer representing its identity.

Particularité de l'implémentation CPython : en CPython, `id(x)` est l'adresse mémoire où est stocké `x`.

Le type de l'objet détermine les opérations que l'on peut appliquer à l'objet (par exemple, « a-t-il une longueur ? ») et définit aussi les valeurs possibles pour les objets de ce type. La fonction `type()` renvoie le type de l'objet (qui est lui-même un objet). Comme l'identifiant, le type d'un objet ne peut pas être modifié [1].

La valeur de certains objets peut changer. Les objets dont la valeur peut changer sont dits mutables ; les objets dont la valeur est définitivement fixée à leur création sont dits immuables (immutable en anglais). La valeur d'un objet conteneur immuable qui contient une référence vers un objet mutable peut varier lorsque la valeur de l'objet mutable change ; cependant, le conteneur est quand même considéré comme immuable parce que l'ensemble des objets qu'il contient ne peut pas être modifié. Ainsi, l'immuabilité n'est pas strictement équivalente au fait d'avoir une valeur non modifiable, c'est plus subtil. La muabilité d'un objet est définie par son type ; par exemple, les nombres, les chaînes de caractères et les n-uplets sont immuables alors que les dictionnaires et les listes sont mutables.

Un objet n'est jamais explicitement détruit ; cependant, lorsqu'il ne peut plus être atteint, il a vocation à être supprimé par le ramasse-miettes (garbage-collector en anglais). L'implémentation peut retarder cette opération ou même ne pas la faire du tout — la façon dont fonctionne le ramasse-miette est particulière à chaque implémentation, l'important étant qu'il ne supprime pas d'objet qui peut encore être atteint.

Particularité de l'implémentation CPython : CPython utilise aujourd'hui un mécanisme de compteur de références avec une détection, en temps différé et optionnelle, des cycles d'objets. Ce mécanisme supprime la plupart des objets dès qu'ils ne sont plus accessibles mais il ne garantit pas la suppression des objets où il existe des références circulaires. Consultez la documentation du module `gc` pour tout ce qui concerne la suppression des cycles. D'autres implémentations agissent différemment et CPython pourrait évoluer. Ne vous reposez pas sur la finalisation immédiate des objets devenus inaccessibles (ainsi, vous devez toujours fermer les fichiers explicitement).

Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching an exception with a `try`...`except` statement may keep objects alive.

Some objects contain references to "external" resources such as open files or windows. It is understood that these resources are freed when the object is garbage-collected, but since garbage collection is not guaranteed to happen, such objects also provide an explicit way to release the external resource, usually a `close()` method. Programs are strongly recommended to explicitly close such objects. The `try`...`finally` statement and the `with` statement provide convenient ways to do this.

Certains objets contiennent des références à d'autres objets ; on les appelle conteneurs. Comme exemples de conteneurs, nous pouvons citer les n-uplets, les listes et les dictionnaires. Les références sont parties intégrantes de la valeur d'un conteneur. Dans la plupart des cas, lorsque nous parlons de la valeur d'un conteneur, nous parlons des valeurs, pas des identifiants des objets contenus ; cependant, lorsque nous parlons de la muabilité d'un conteneur, seuls les identifiants des objets immédiatement contenus sont concernés. Ainsi, si un conteneur immuable (comme un n-uplet) contient une référence à un objet mutable, sa valeur change si cet objet mutable est modifié.

Presque tous les comportements d'un objet dépendent du type de l'objet. Même son identifiant est concerné dans un certain sens : pour les types immuables, les opérations qui calculent de nouvelles valeurs peuvent en fait renvoyer une référence à n'importe quel objet existant avec le même type et la même valeur, alors que pour les objets mutables cela n'est pas autorisé. Par exemple, après `a = 1 ; b = 1`, `a` et `b` peuvent ou non se référer au même objet avec la valeur un, en fonction de l'implémentation. Mais après `c = [] ; d = []`, il est garanti que `c` et `d` font référence à deux listes vides distinctes nouvellement créées. Notez que `c = d = []` attribue le même objet à `c` et `d`.

## 3.2. Hiérarchie des types standards

Vous trouvez ci-dessous une liste des types natifs de Python. Des modules d'extension (écrits en C, Java ou d'autres langages) peuvent définir des types supplémentaires. Les futures versions de Python pourront ajouter des types à cette hiérarchie (par exemple les nombres rationnels, des tableaux d'entiers stockés efficacement, etc.), bien que de tels ajouts se trouvent souvent plutôt dans la bibliothèque standard.

Quelques descriptions des types ci-dessous contiennent un paragraphe listant des « attributs spéciaux ». Ces attributs donnent accès à l'implémentation et n'ont, en général, pas vocation à être utilisés. Leur définition peut changer dans le futur.

### 3.2.1. `None`

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette valeur. Vous accédez à cet objet avec le nom natif `None`. Il est utilisé pour signifier l'absence de valeur dans de nombreux cas, par exemple pour des fonctions qui ne renvoient rien explicitement. Sa valeur booléenne est fausse.

### 3.2.2. NotImplemented

This type has a single value. There is a single object with this value. This object is accessed through the built-in name `NotImplemented`. Numeric methods and rich comparison methods should return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) It should not be evaluated in a boolean context.

Consultez Implémentation des opérations arithmétiques pour davantage de détails.

Modifié dans la version 3.9: Evaluating `NotImplemented` in a boolean context is deprecated. While it currently evaluates as true, it will emit a `DeprecationWarning`. It will raise a `TypeError` in a future version of Python.

### 3.2.3. Ellipse

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette valeur. Vous accédez à cet objet avec le littéral `...` ou le nom natif `Ellipsis`. Sa valeur booléenne est vraie.

### 3.2.4. `numbers.Number`

Ces objets sont créés par les littéraux numériques et renvoyés en tant que résultats par les opérateurs et les fonctions arithmétiques natives. Les objets numériques sont immuables ; une fois créés, leur valeur ne change pas. Les nombres Python sont bien sûr très fortement corrélés aux nombres mathématiques mais ils sont soumis aux limitations des représentations numériques par les ordinateurs.

Les représentations sous forme de chaînes de caractères des objets numériques, produites par `__repr__()` et `__str__()`, ont les propriétés suivantes :

- Ce sont des littéraux numériques valides qui, s'ils sont passés au constructeur de leur classe, produisent un objet qui a la valeur numérique de l'objet d'origine.

- La représentation est en base 10, si possible.

- Les zéros en tête, sauf en ce qui concerne un zéro seul avant la virgule (représentée par un point en Python conformément à la convention anglo-saxonne), ne sont pas affichés.

- Les zéros en fin, sauf en ce qui concerne un zéro seul après la virgule, ne sont pas affichés.

- Le signe n'est affiché que lorsque le nombre est négatif.

Python distingue les entiers, les nombres à virgule flottante et les nombres complexes :

#### 3.2.4.1. `numbers.Integral`

Ils représentent des éléments de l'ensemble mathématique des entiers (positifs ou négatifs).

Note

Les règles pour la représentation des entiers ont pour objet de donner l'interprétation la plus naturelle pour les opérations de décalage et masquage qui impliquent des entiers négatifs.

Il existe deux types d'entiers :

Entiers (`int`)

  Ils représentent les nombres, sans limite de taille, sous réserve de pouvoir être stockés en mémoire (virtuelle). Afin de pouvoir effectuer des décalages et appliquer des masques, on considère qu'ils ont une représentation binaire. Les nombres négatifs sont représentés comme une variante du complément à 2, qui donne l'illusion d'une chaîne infinie de bits de signe s'étendant vers la gauche.

Booléens (`bool`)

  Ils représentent les valeurs faux et vrai. Deux objets, `False` et `True`, sont les seuls objets booléens. Le type booléen est un sous-type du type entier et les valeurs booléennes se comportent comme les valeurs 0 (pour `False`) et 1 (pour `True`) dans presque tous les contextes. L'exception concerne la conversion en chaîne de caractères où `"False"` et `"True"` sont renvoyées.

#### 3.2.4.2. `numbers.Real` (`float`)

Ils représentent les nombres à virgule flottante en double précision, tels que manipulés directement par la machine. Vous dépendez donc de l'architecture machine sous-jacente (et de l'implémentation C ou Java) pour les intervalles gérés et le traitement des débordements. Python ne gère pas les nombres à virgule flottante en précision simple ; les gains en puissance de calcul et mémoire, qui sont généralement la raison de l'utilisation des nombres en simple précision, sont annihilés par le fait que Python encapsule de toute façon ces nombres dans des objets. Il n'y a donc aucune raison de compliquer le langage avec deux types de nombres à virgule flottante.

#### 3.2.4.3. `numbers.Complex` (`complex`)

Ils représentent les nombres complexes, sous la forme d'un couple de nombres à virgule flottante en double précision, tels que manipulés directement par la machine. Les mêmes restrictions s'appliquent que pour les nombres à virgule flottante. La partie réelle et la partie imaginaire d'un nombre complexe `z` peuvent être demandées par les attributs en lecture seule `z.real` et `z.imag`.

### 3.2.5. Séquences

These represent finite ordered sets indexed by non-negative numbers. The built-in function `len()` returns the number of items of a sequence. When the length of a sequence is n, the index set contains the numbers 0, 1, ..., n-1. Item i of sequence a is selected by `a[i]`. Some sequences, including built-in sequences, interpret negative subscripts by adding the sequence length. For example, `a[-2]` equals `a[n-2]`, the second to last item of sequence a with length `n`.

Sequences also support slicing: `a[i:j]` selects all items with index k such that i `<=` k `<` j. When used as an expression, a slice is a sequence of the same type. The comment above about negative indexes also applies to negative slice positions.

Quelques séquences gèrent le « découpage étendu » (extended slicing en anglais) avec un troisième paramètre : `a[i:j:k]` sélectionne tous les éléments de a d'indice x où `x = i + n*k`, avec n `>=` `0` et i `<=` x `<` j.

Les séquences se différencient en fonction de leur muabilité :

#### 3.2.5.1. Séquences immuables

Un objet de type de séquence immuable ne peut pas être modifié une fois qu'il a été créé. Si l'objet contient des références à d'autres objets, ces autres objets peuvent être mutables et peuvent être modifiés ; cependant, les objets directement référencés par un objet immuable ne peuvent pas être modifiés.

Les types suivants sont des séquences immuables :

Chaînes de caractères

  A string is a sequence of values that represent Unicode code points. All the code points in the range `U+0000 - U+10FFFF` can be represented in a string. Python doesn't have a char type; instead, every code point in the string is represented as a string object with length `1`. The built-in function `ord()` converts a code point from its string form to an integer in the range `0 - 10FFFF`; `chr()` converts an integer in the range `0 - 10FFFF` to the corresponding length `1` string object. `str.encode()` can be used to convert a `str` to `bytes` using the given text encoding, and `bytes.decode()` can be used to achieve the opposite.

n-uplets (tuples en anglais)

  Les éléments d'un n-uplet peuvent être n'importe quel objet Python. Les n-uplets de deux éléments ou plus sont formés par une liste d'expressions dont les éléments sont séparés par des virgules. Un n-uplet composé d'un seul élément (un « singleton ») est formé en suffixant une expression avec une virgule (une expression en tant que telle ne crée pas un n-uplet car les parenthèses doivent rester disponibles pour grouper les expressions). Un n-uplet vide est formé à l'aide d'une paire de parenthèses vide.

Chaînes d'octets (ou bytes)

  Les objets bytes sont des tableaux immuables. Les éléments sont des octets (donc composés de 8 bits), représentés par des entiers dans l'intervalle 0 à 255 inclus. Les littéraux bytes (tels que `b'abc'`) et la fonction native constructeur `bytes()` peuvent être utilisés pour créer des objets bytes. Aussi, un objet bytes peut être décodé vers une chaîne via la méthode `decode()`.

#### 3.2.5.2. Séquences mutables

Les séquences mutables peuvent être modifiées après leur création. Les notations de tranches et de sous-ensembles peuvent être utilisées en tant que cibles d'une affectation ou de l'instruction `del` (suppression).

Note

The `collections` and `array` module provide additional examples of mutable sequence types.

Il existe aujourd'hui deux types intrinsèques de séquences mutables :

Listes

  N'importe quel objet Python peut être élément d'une liste. Les listes sont créées en plaçant entre crochets une liste d'expressions dont les éléments sont séparés par des virgules (notez que les listes de longueur 0 ou 1 ne sont pas des cas particuliers).

Tableaux d'octets

  Un objet bytearray est un tableau mutable. Il est créé par la fonction native constructeur `bytearray()`. À part la propriété d'être mutable (et donc de ne pas pouvoir calculer son empreinte par hachage), un tableau d'octets possède la même interface et les mêmes fonctionnalités qu'un objet immuable `bytes`.

### 3.2.6. Ensembles

Ils représentent les ensembles d'objets, non ordonnés, finis et dont les éléments sont uniques. Tels quels, ils ne peuvent pas être indicés. Cependant, il est possible d'itérer dessus et la fonction native `len()` renvoie le nombre d'éléments de l'ensemble. Les utilisations classiques des ensembles sont les tests d'appartenance rapides, la suppression de doublons dans une séquence et le calcul d'opérations mathématiques telles que l'intersection, l'union, la différence et le complémentaire.

Pour les éléments des ensembles, les mêmes règles concernant l'immuabilité s'appliquent que pour les clés de dictionnaires. Notez que les types numériques obéissent aux règles normales pour les comparaisons numériques : si deux nombres sont égaux (pour l'opération de comparaison, par exemple `1` et `1.0`), un seul élément est conservé dans l'ensemble.

Actuellement, il existe deux types d'ensembles natifs :

Ensembles

  Ils représentent les ensembles mutables. Un ensemble est créé par la fonction native constructeur `set()` et peut être modifié par la suite à l'aide de différentes méthodes, par exemple `add()`.

Ensembles figés

  Ils représentent les ensembles immuables. Ils sont créés par la fonction native constructeur `frozenset()`. Comme un ensemble figé est immuable et hachable, il peut être utilisé comme élément d'un autre ensemble ou comme clé de dictionnaire.

### 3.2.7. Tableaux de correspondances

Ils représentent les ensembles finis d'objets indicés par des ensembles index arbitraires. La notation `a[k]` sélectionne l'élément indicé par `k` dans le tableau de correspondances `a` ; elle peut être utilisée dans des expressions, comme cible d'une affectation ou avec l'instruction `del`. La fonction native `len()` renvoie le nombre d'éléments du tableau de correspondances.

Il n'existe actuellement qu'un seul type natif pour les tableaux de correspondances :

#### 3.2.7.1. Dictionnaires

Ils représentent les ensembles finis d'objets indicés par des valeurs presque arbitraires. Les seuls types de valeurs non reconnus comme clés sont les valeurs contenant des listes, des dictionnaires ou les autres types mutables qui sont comparés par valeur plutôt que par l'identifiant de l'objet. La raison de cette limitation est qu'une implémentation efficace de dictionnaire requiert que l'empreinte par hachage des clés reste constante dans le temps. Les types numériques obéissent aux règles normales pour les comparaisons numériques : si deux nombres sont égaux pour l'opération de comparaison, par exemple `1` et `1.0`, alors ces deux nombres peuvent être utilisés indifféremment pour désigner la même entrée du dictionnaire.

Les dictionnaires préservent l’ordre d’insertion, ce qui signifie que les clés sont renvoyées séquentiellement dans le même ordre que celui de l’insertion. Remplacer une clé existante ne change pas l’ordre. Par contre, la retirer puis la réinsérer la met à la fin et non à sa précédente position.

Les dictionnaires sont mutables : ils peuvent être créés par la notation `{…}` (reportez-vous à la section Agencements de dictionnaires).

Les modules d'extensions `dbm.ndbm` et `dbm.gnu` apportent d'autres exemples de types tableaux de correspondances, de même que le module `collections`.

Modifié dans la version 3.7: les dictionnaires ne conservaient pas l’ordre d’insertion dans les versions antérieures à Python 3.6. Dans CPython 3.6, l’ordre d’insertion était déjà conservé, mais considéré comme un détail d’implémentation et non comme une garantie du langage.

### 3.2.8. Types appelables

Ce sont les types sur lesquels on peut faire un appel de fonction (lisez la section Appels) :

#### 3.2.8.1. Fonctions définies par l'utilisateur

Un objet fonction définie par l'utilisateur (mais ce n'est pas forcément l'utilisateur courant qui a défini cette fonction) est créé par la définition d'une fonction (voir la section Définition de fonctions). Il doit être appelé avec une liste d'arguments contenant le même nombre d'éléments que la liste des paramètres formels de la fonction.

##### 3.2.8.1.1. Special read-only attributes

Attribut | Signification
--- | ---
function.__globals__ | A reference to the `dictionary` that holds the function's global variables -- the global namespace of the module in which the function was defined.
function.__closure__ | `None` or a `tuple` of cells that contain bindings for the function's free variables. Un objet cellule possède un attribut `cell_contents`. Il peut être utilisé pour obtenir la valeur de la cellule et pour en définir la valeur.

##### 3.2.8.1.2. Special writable attributes

Most of these attributes check the type of the assigned value:

Attribut | Signification
--- | ---
function.__doc__ | The function's documentation string, or `None` if unavailable. Not inherited by subclasses.
function.__name__ | The function's name. See also: `__name__ attributes`.
function.__qualname__ | The function's qualified name. See also: `__qualname__ attributes`. Nouveau dans la version 3.3.
function.__module__ | Nom du module où la fonction est définie ou `None` si ce nom n'est pas disponible.
function.__defaults__ | A `tuple` containing default parameter values for those parameters that have defaults, or `None` if no parameters have a default value.
function.__code__ | The code object representing the compiled function body.
function.__dict__ | The namespace supporting arbitrary function attributes. See also: `__dict__ attributes`.
function.__annotations__ | A `dictionary` containing annotations of parameters. The keys of the dictionary are the parameter names, and `'return'` for the return annotation, if provided. See also: Bonnes pratiques concernant les annotations.
function.__kwdefaults__ | A `dictionary` containing defaults for keyword-only parameters.

Function objects also support getting and setting arbitrary attributes, which can be used, for example, to attach metadata to functions. Regular attribute dot-notation is used to get and set such attributes.

Particularité de l'implémentation CPython : CPython's current implementation only supports function attributes on user-defined functions. Function attributes on built-in functions may be supported in the future.

Additional information about a function's definition can be retrieved from its code object (accessible via the `__code__` attribute).

#### 3.2.8.2. Méthodes d'instances

Un objet méthode d'instance combine une classe, une instance de classe et tout objet appelable (normalement une fonction définie par l'utilisateur).

Special read-only attributes:

method.__self__ | Refers to the class instance object to which the method is bound
method.__func__ | Refers to the original function object
method.__doc__ | The method's documentation (same as `method.__func__.__doc__`). A `string` if the original function had a docstring, else `None`.
method.__name__ | The name of the method (same as `method.__func__.__name__`)
method.__module__ | The name of the module the method was defined in, or `None` if unavailable.

Methods also support accessing (but not setting) the arbitrary function attributes on the underlying function object.

User-defined method objects may be created when getting an attribute of a class (perhaps via an instance of that class), if that attribute is a user-defined function object or a `classmethod` object.

When an instance method object is created by retrieving a user-defined function object from a class via one of its instances, its `__self__` attribute is the instance, and the method object is said to be bound. The new method's `__func__` attribute is the original function object.

When an instance method object is created by retrieving a `classmethod` object from a class or instance, its `__self__` attribute is the class itself, and its `__func__` attribute is the function object underlying the class method.

When an instance method object is called, the underlying function (`__func__`) is called, inserting the class instance (`__self__`) in front of the argument list. For instance, when `C` is a class which contains a definition for a function `f()`, and `x` is an instance of `C`, calling `x.f(1)` is equivalent to calling `C.f(x, 1)`.

When an instance method object is derived from a `classmethod` object, the "class instance" stored in `__self__` will actually be the class itself, so that calling either `x.f(1)` or `C.f(1)` is equivalent to calling `f(C,1)` where `f` is the underlying function.

Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also important to note that user-defined functions which are attributes of a class instance are not converted to bound methods; this only happens when the function is an attribute of the class.

#### 3.2.8.3. Fonctions génératrices (ou générateurs)

Une fonction ou une méthode qui utilise l'instruction `yield` (voir la section L'instruction yield) est appelée fonction génératrice. Une telle fonction, lorsqu'elle est appelée, renvoie toujours un objet itérateur qui peut être utilisé pour exécuter le corps de la fonction : appeler la méthode `iterator.__next__()` de l'itérateur exécute la fonction jusqu'à ce qu'elle renvoie une valeur à l'aide de l'instruction `yield`. Quand la fonction exécute l'instruction `return` ou se termine, une exception `StopIteration` est levée et l'itérateur a atteint la fin de l'ensemble de valeurs qu'il peut renvoyer.

#### 3.2.8.4. Fonctions coroutines

Une fonction ou méthode définie en utilisant `async def` est appelée fonction coroutine. Une telle fonction, quand elle est appelée, renvoie un objet coroutine. Elle peut contenir des expressions `await` ou `async with` ou des instructions `async for`. Voir également la section Objets coroutines.

#### 3.2.8.5. Fonctions génératrices (ou générateurs) asynchrones

Une fonction ou une méthode définie avec `async def` et qui utilise l'instruction `yield` est appelée fonction génératrice asynchrone. Une telle fonction, quand elle est appelée, renvoie un objet itérateur asynchrone qui peut être utilisé dans des instructions `async for` pour exécuter le corps de la fonction.

Appeler la méthode `aiterator.__anext__` de l'itérateur asynchrone renvoie un awaitable qui, lorsqu'on l'attend, s'exécute jusqu'à ce qu'il fournisse une valeur à l'aide de l'expression `yield`. Quand la fonction exécute une instruction `return` (sans valeur) ou arrive à la fin, une exception `StopAsyncIteration` est levée et l'itérateur asynchrone a atteint la fin de l'ensemble des valeurs qu'il peut produire.

#### 3.2.8.6. Fonctions natives

A built-in function object is a wrapper around a C function. Examples of built-in functions are `len()` and `math.sin()` (`math` is a standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes:

- `__doc__` is the function's documentation string, or `None` if unavailable. See `function.__doc__`.

- `__name__` is the function's name. See `function.__name__`.

- `__self__` is set to `None` (but see the next item).

- `__module__` is the name of the module the function was defined in or `None` if unavailable. See `function.__module__`.

#### 3.2.8.7. Méthodes natives

This is really a different disguise of a built-in function, this time containing an object passed to the C function as an implicit extra argument. An example of a built-in method is `alist.append()`, assuming alist is a list object. In this case, the special read-only attribute `__self__` is set to the object denoted by alist. (The attribute has the same semantics as it does with `other instance methods`.)

#### 3.2.8.8. Classes

Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that override `__new__()`. The arguments of the call are passed to `__new__()` and, in the typical case, to `__init__()` to initialize the new instance.

#### 3.2.8.9. Instances de classe

Les instances d'une classe peuvent devenir des appelables si vous définissez la méthode `__call__()` de leur classe.

### 3.2.9. Modules

Modules are a basic organizational unit of Python code, and are created by the import system as invoked either by the `import` statement, or by calling functions such as `importlib.import_module()` and built-in `__import__()`. A module object has a namespace implemented by a `dictionary` object (this is the dictionary referenced by the `__globals__` attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., `m.x` is equivalent to `m.__dict__["x"]`. A module object does not contain the code object used to initialize the module (since it isn't needed once the initialization is done).

L'affectation d'un attribut met à jour le dictionnaire d'espace de nommage du module, par exemple `m.x = 1` est équivalent à `m.__dict__["x"] = 1`.

Attributs prédéfinis (accessibles en écriture) :

> `__name__`

>   Nom du module.

> `__doc__`

>   Chaîne de documentation du module (docstring en anglais), ou `None` si le module n'en a pas.

> `__file__`

>   Chemin vers le fichier à partir duquel le module a été chargé, s'il a été chargé depuis un fichier. L'attribut `__file__` peut être manquant pour certains types de modules, tels que les modules C qui sont statiquement liés à l'interpréteur. Pour les modules d'extension chargés dynamiquement à partir d'une bibliothèque partagée, c'est le chemin vers le fichier de la bibliothèque partagée.

> `__annotations__`

>   Dictionnaire des annotations de variable trouvées lors de l'exécution du code du module. Pour plus de détails sur l'attribut `__annotations__`, voir Bonnes pratiques concernant les annotations.

Attribut spécial en lecture seule : `__dict__` est l'objet dictionnaire répertoriant l'espace de nommage du module.

Particularité de l'implémentation CPython : en raison de la manière dont CPython nettoie les dictionnaires de modules, le dictionnaire du module est effacé quand le module n'est plus visible, même si le dictionnaire possède encore des références actives. Pour éviter ceci, copiez le dictionnaire ou gardez le module dans votre champ de visibilité tant que vous souhaitez utiliser le dictionnaire directement.

### 3.2.10. Classes déclarées par le développeur

Le type d'une classe déclarée par le développeur est créé au moment de la définition de la classe (voir la section Définition de classes). Une classe possède un espace de nommage implémenté sous la forme d'un objet dictionnaire. Les références vers les attributs de la classe sont traduits en recherches dans ce dictionnaire, par exemple `C.x` est traduit en `C.__dict__["x"]` (bien qu'il existe un certain nombre de fonctions automatiques qui permettent de trouver des attributs par d'autres moyens). Si le nom d'attribut n'est pas trouvé dans ce dictionnaire, la recherche continue dans les classes de base. Les classes de base sont trouvées en utilisant l'ordre de résolution des méthodes (method resolution order en anglais, ou MRO) C3 qui a un comportement cohérent même en présence d'héritages en "diamant", où différentes branches d'héritages conduisent vers un ancêtre commun. Vous trouverez plus de détails sur l'ordre de résolution des méthodes MRO C3 utilisé par Python dans la documentation de la version 2.3 disponible sur https://www.python.org/download/releases/2.3/mro/.

When a class attribute reference (for class `C`, say) would yield a class method object, it is transformed into an instance method object whose `__self__` attribute is `C`. When it would yield a `staticmethod` object, it is transformed into the object wrapped by the static method object. See section Implémentation de descripteurs for another way in which attributes retrieved from a class may differ from those actually contained in its `__dict__`.

Les affectations d'un attribut de classe mettent à jour le dictionnaire de la classe, jamais le dictionnaire d'une classe de base.

Un objet classe peut être appelé (voir ci-dessus) pour produire une instance de classe (voir ci-dessous).

Attributs spéciaux :

> `__name__`

>   Nom de la classe.

> `__module__`

>   Nom du module où la classe a été définie.

> `__dict__`

>   Dictionnaire qui forme l'espace de nommage de la classe.

> `__bases__`

>   N-uplet des classes mères, dans le même ordre que dans la définition de la classe.

> `__doc__`

>   Chaîne de documentation de la classe (docstring en anglais), ou bien `None` si la classe n'en a pas.

> `__annotations__`

>   Dictionnaire des annotations de variable trouvées lors de l'exécution du code de la classe. Pour plus de détails sur l'attribut `__annotations__`, voir Bonnes pratiques concernant les annotations.

### 3.2.11. Instances de classe

A class instance is created by calling a class object (see above). A class instance has a namespace implemented as a dictionary which is the first place in which attribute references are searched. When an attribute is not found there, and the instance's class has an attribute by that name, the search continues with the class attributes. If a class attribute is found that is a user-defined function object, it is transformed into an instance method object whose `__self__` attribute is the instance. Static method and class method objects are also transformed; see above under "Classes". See section Implémentation de descripteurs for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class's `__dict__`. If no class attribute is found, and the object's class has a `__getattr__()` method, that is called to satisfy the lookup.

Les affectations et suppressions d'attributs mettent à jour le dictionnaire de l'instance, jamais le dictionnaire de la classe. Si la classe possède une méthode `__setattr__()` ou `__delattr__()`, elle est appelée au lieu de mettre à jour le dictionnaire de l'instance directement.

Les instances de classes peuvent prétendre être des nombres, des séquences ou des tableaux de correspondances si elles ont des méthodes avec des noms spéciaux. Voir la section Méthodes spéciales.

Attributs spéciaux : `__dict__` est le dictionnaire des attributs ; `__class__` est la classe de l'instance.

### 3.2.12. Objets entrées-sorties (ou objets fichiers)

Un objet fichier représente un fichier ouvert. Différents raccourcis existent pour créer des objets fichiers : la fonction native `open()` et aussi `os.popen()`, `os.fdopen()` ou la méthode `makefile()` des objets connecteurs (et sûrement d'autres fonctions ou méthodes fournies par les modules d'extensions).

Les objets `sys.stdin`, `sys.stdout` et `sys.stderr` sont initialisés à des objets fichiers correspondant à l'entrée standard, la sortie standard et le flux d'erreurs de l'interpréteur ; ils sont tous ouverts en mode texte et se conforment donc à l'interface définie par la classe abstraite `io.TextIOBase`.

### 3.2.13. Types internes

Quelques types utilisés en interne par l'interpréteur sont accessibles à l'utilisateur. Leur définition peut changer dans les futures versions de l'interpréteur mais ils sont donnés ci-dessous à fin d'exhaustivité.

#### 3.2.13.1. Objets Code

Un objet code représente le code Python sous sa forme compilée en code intermédiaire. La différence entre un objet code et un objet fonction est que l'objet fonction contient une référence explicite vers les globales de la fonction (le module dans lequel elle est définie) alors qu'un objet code ne contient aucun contexte ; par ailleurs, les valeurs par défaut des arguments sont stockées dans l'objet fonction, pas dans l'objet code (parce que ce sont des valeurs calculées au moment de l'exécution). Contrairement aux objets fonctions, les objets codes sont immuables et ne contiennent aucune référence (directe ou indirecte) à des objets mutables.

##### 3.2.13.1.1. Special read-only attributes

codeobject.co_name | The function name
codeobject.co_qualname | The fully qualified function name Nouveau dans la version 3.11.
codeobject.co_argcount | The total number of positional parameters (including positional-only parameters and parameters with default values) that the function has
codeobject.co_posonlyargcount | The number of positional-only parameters (including arguments with default values) that the function has
codeobject.co_kwonlyargcount | The number of keyword-only parameters (including arguments with default values) that the function has
codeobject.co_nlocals | The number of local variables used by the function (including parameters)
codeobject.co_varnames | A `tuple` containing the names of the local variables in the function (starting with the parameter names)
codeobject.co_cellvars | A `tuple` containing the names of local variables that are referenced by nested functions inside the function
codeobject.co_freevars | A `tuple` containing the names of free variables in the function
codeobject.co_code | A string representing the sequence of bytecode instructions in the function
codeobject.co_consts | A `tuple` containing the literals used by the bytecode in the function
codeobject.co_names | A `tuple` containing the names used by the bytecode in the function
codeobject.co_filename | The name of the file from which the code was compiled
codeobject.co_firstlineno | The line number of the first line of the function
codeobject.co_lnotab | A string encoding the mapping from bytecode offsets to line numbers. For details, see the source code of the interpreter.
codeobject.co_stacksize | The required stack size of the code object
codeobject.co_flags | An `integer` encoding a number of flags for the interpreter.

The following flag bits are defined for `co_flags`: bit `0x04` is set if the function uses the `*arguments` syntax to accept an arbitrary number of positional arguments; bit `0x08` is set if the function uses the `**keywords` syntax to accept arbitrary keyword arguments; bit `0x20` is set if the function is a generator. See Bit d'option des objets code for details on the semantics of each flags that might be present.

Future feature declarations (`from __future__ import division`) also use bits in `co_flags` to indicate whether a code object was compiled with a particular feature enabled: bit `0x2000` is set if the function was compiled with future division enabled; bits `0x10` and `0x1000` were used in earlier versions of Python.

Other bits in `co_flags` are reserved for internal use.

If a code object represents a function, the first item in `co_consts` is the documentation string of the function, or `None` if undefined.

##### 3.2.13.1.2. Methods on code objects

codeobject.co_positions()

  Returns an iterable over the source code positions of each bytecode instruction in the code object.

  The iterator returns `tuple`s containing the `(start_line, end_line, start_column, end_column)`. The i-th tuple corresponds to the position of the source code that compiled to the i-th code unit. Column information is 0-indexed utf-8 byte offsets on the given source line.

  L'information sur la position peut être manquante. Ce peut être le cas si (liste non exhaustive) :

  - l'interpréteur est lancé avec l'option `-X` `no_debug_ranges` ;

  - le fichier .pyc est le produit d'une compilation avec l'option `-X` `no_debug_ranges` ;

  - le n-uplet de position correspond à des instructions artificielles ;

  - les lignes et colonnes ne peuvent pas être représentées en tant que nombre, en raison de limitations dues à l'implémentation ;

  Dans ce cas, certains ou tous les éléments du n-uplet peuvent valoir `None`.

  Nouveau dans la version 3.11.

  Note

  cette fonctionnalité nécessite de stocker les positions de colonne dans les objets code, ce qui peut conduire à une légère augmentation de l'utilisation du disque par les fichiers Python compilés ou de l'utilisation de la mémoire. Pour éviter de stocker cette information supplémentaire ou pour désactiver l'affichage supplémentaire dans la pile d'appels, vous pouvez activer l'option de ligne de commande `-X` `no_debug_ranges` ou la variable d'environnement `PYTHONNODEBUGRANGES`.

codeobject.co_lines()

  Returns an iterator that yields information about successive ranges of bytecodes. Each item yielded is a `(start, end, lineno)` `tuple`:

  - `start` (an `int`) represents the offset (inclusive) of the start of the bytecode range

  - `end` (an `int`) represents the offset (exclusive) of the end of the bytecode range

  - `lineno` is an `int` representing the line number of the bytecode range, or `None` if the bytecodes in the given range have no line number

  The items yielded will have the following properties:

  - The first range yielded will have a `start` of 0.

  - The `(start, end)` ranges will be non-decreasing and consecutive. That is, for any pair of `tuple`s, the `start` of the second will be equal to the `end` of the first.

  - No range will be backwards: `end >= start` for all triples.

  - The last `tuple` yielded will have `end` equal to the size of the bytecode.

  Zero-width ranges, where `start == end`, are allowed. Zero-width ranges are used for lines that are present in the source code, but have been eliminated by the bytecode compiler.

  Nouveau dans la version 3.10.

  Voir aussi

  PEP 626 - Precise line numbers for debugging and other tools.

    The PEP that introduced the `co_lines()` method.

codeobject.replace(**kwargs)

  Return a copy of the code object with new values for the specified fields.

  Nouveau dans la version 3.8.

#### 3.2.13.2. Objets cadres

Frame objects represent execution frames. They may occur in traceback objects, and are also passed to registered trace functions.

##### 3.2.13.2.1. Special read-only attributes

frame.f_back | Points to the previous stack frame (towards the caller), or `None` if this is the bottom stack frame
frame.f_code | The code object being executed in this frame. Accessing this attribute raises an auditing event `object.__getattr__` with arguments `obj` and `"f_code"`.
frame.f_locals | The dictionary used by the frame to look up local variables
frame.f_globals | The dictionary used by the frame to look up global variables
frame.f_builtins | The dictionary used by the frame to look up built-in (intrinsic) names
frame.f_lasti | The "precise instruction" of the frame object (this is an index into the bytecode string of the code object)

##### 3.2.13.2.2. Special writable attributes

frame.f_trace | If not `None`, this is a function called for various events during code execution (this is used by debuggers). Normally an event is triggered for each new source line (see `f_trace_lines`).
frame.f_trace_lines | Set this attribute to `False` to disable triggering a tracing event for each source line.
frame.f_trace_opcodes | Set this attribute to `True` to allow per-opcode events to be requested. Note that this may lead to undefined interpreter behaviour if exceptions raised by the trace function escape to the function being traced.
frame.f_lineno | The current line number of the frame -- writing to this from within a trace function jumps to the given line (only for the bottom-most frame). A debugger can implement a Jump command (aka Set Next Statement) by writing to this attribute.

##### 3.2.13.2.3. Frame object methods

Les objets cadres comprennent une méthode :

frame.clear()

  This method clears all references to local variables held by the frame. Also, if the frame belonged to a generator, the generator is finalized. This helps break reference cycles involving frame objects (for example when catching an exception and storing its traceback for later use).

  `RuntimeError` est levée si le cadre est en cours d'exécution.

  Nouveau dans la version 3.4.

#### 3.2.13.3. Objets traces d'appels

Traceback objects represent the stack trace of an exception. A traceback object is implicitly created when an exception occurs, and may also be explicitly created by calling `types.TracebackType`.

Modifié dans la version 3.7: Traceback objects can now be explicitly instantiated from Python code.

For implicitly created tracebacks, when the search for an exception handler unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section L'instruction try.) It is accessible as the third item of the tuple returned by `sys.exc_info()`, and as the `__traceback__` attribute of the caught exception.

When the program contains no suitable handler, the stack trace is written (nicely formatted) to the standard error stream; if the interpreter is interactive, it is also made available to the user as `sys.last_traceback`.

For explicitly created tracebacks, it is up to the creator of the traceback to determine how the `tb_next` attributes should be linked to form a full stack trace.

Special read-only attributes:

traceback.tb_frame | Points to the execution frame of the current level. Accessing this attribute raises an auditing event `object.__getattr__` with arguments `obj` and `"tb_frame"`.
traceback.tb_lineno | Gives the line number where the exception occurred
traceback.tb_lasti | Indicates the "precise instruction".

The line number and last instruction in the traceback may differ from the line number of its frame object if the exception occurred in a `try` statement with no matching except clause or with a `finally` clause.

traceback.tb_next

  The special writable attribute `tb_next` is the next level in the stack trace (towards the frame where the exception occurred), or `None` if there is no next level.

  Modifié dans la version 3.7: This attribute is now writable

#### 3.2.13.4. Objets tranches

Un objet tranche est utilisé pour représenter des découpes des méthodes `__getitem__()`. Ils sont aussi créés par la fonction native `slice()`.

Attributs spéciaux en lecture seule : `start` est la borne inférieure ; `stop` est la borne supérieure ; `step` est la valeur du pas ; chaque attribut vaut `None` s'il est omis. Ces attributs peuvent être de n'importe quel type.

Les objets tranches comprennent une méthode :

slice.indices(self, length)

  Cette méthode prend un argument entier length et calcule les informations de la tranche que l'objet slice décrit s'il est appliqué à une séquence de length éléments. Elle renvoie un triplet d'entiers ; respectivement, ce sont les indices de début et fin ainsi que le pas de découpe. Les indices manquants ou en dehors sont gérés de manière cohérente avec les tranches normales.

#### 3.2.13.5. Objets méthodes statiques

Les objets méthodes statiques permettent la transformation des objets fonctions en objets méthodes décrits au-dessus. Un objet méthode statique encapsule tout autre objet, souvent un objet méthode définie par l'utilisateur. Quand un objet méthode statique est récupéré depuis une classe ou une instance de classe, l'objet réellement renvoyé est un objet encapsulé, qui n'a pas vocation à être transformé encore une fois. Les objets méthodes statiques sont aussi appelables. Les objets méthodes statiques sont créés par le constructeur natif `staticmethod()`.

#### 3.2.13.6. Objets méthodes de classes

A class method object, like a static method object, is a wrapper around another object that alters the way in which that object is retrieved from classes and class instances. The behaviour of class method objects upon such retrieval is described above, under "instance methods". Class method objects are created by the built-in `classmethod()` constructor.

## 3.3. Méthodes spéciales

Une classe peut implémenter certaines opérations que l'on invoque par une syntaxe spéciale (telles que les opérations arithmétiques ou la découpe en tranches) en définissant des méthodes aux noms particuliers. C'est l'approche utilisée par Python pour la surcharge d'opérateur, permettant à une classe de définir son propre comportement vis-à-vis des opérateurs du langage. Par exemple, si une classe définit une méthode `__getitem__()` et que `x` est une instance de cette classe, alors `x[i]` est globalement équivalent à `type(x).__getitem__(x, i)`. Sauf lorsque c'est mentionné, toute tentative d'appliquer une opération alors que la méthode appropriée n'est pas définie lève une exception (typiquement `AttributeError` ou `TypeError`).

Définir une méthode spéciale à `None` indique que l'opération correspondante n'est pas disponible. Par exemple, si une classe assigne `None` à `__iter__()`, vous ne pouvez pas itérer sur la classe et appeler `iter()` sur une instance lève `TypeError` (sans se replier sur `__getitem__()`) [2].

Lorsque vous implémentez une classe qui émule un type natif, il est important que cette émulation n'implémente que ce qui fait sens pour l'objet qui est modélisé. Par exemple, la recherche d'éléments individuels d'une séquence peut faire sens, mais pas l'extraction d'une tranche (un exemple est l'interface de `NodeList` dans le modèle objet des documents W3C).

### 3.3.1. Personnalisation de base

object.__new__(cls[, ...])

  Appelée pour créer une nouvelle instance de la classe cls. La méthode `__new__()` est statique (c'est un cas particulier, vous n'avez pas besoin de la déclarer comme telle) qui prend comme premier argument la classe pour laquelle on veut créer une instance. Les autres arguments sont ceux passés à l'expression de l'objet constructeur (l'appel à la classe). La valeur de retour de `__new__()` doit être l'instance du nouvel objet (classiquement une instance de cls).

  Typical implementations create a new instance of the class by invoking the superclass's `__new__()` method using `super().__new__(cls[, ...])` with appropriate arguments and then modifying the newly created instance as necessary before returning it.

  Si `__new__()` est appelée pendant la construction de l'objet et renvoie une instance de cls, alors la méthode `__init__()` de la nouvelle instance est invoquée avec `__init__(self[, …])` où self est la nouvelle instance et les autres arguments sont les mêmes que ceux passés au constructeur de l'objet.

  Si `__new__()` ne renvoie pas une instance de cls, alors la méthode `__init__()` de la nouvelle instance n'est pas invoquée.

  L'objectif de `__new__()` est principalement, pour les sous-classes de types immuables (comme `int`, `str` ou `tuple`), d'autoriser la création sur mesure des instances. Elle est aussi souvent surchargée dans les métaclasses pour particulariser la création des classes.

object.__init__(self[, ...])

  Appelée après la création de l'instance (par `__new__()`), mais avant le retour vers l'appelant. Les arguments sont ceux passés à l'expression du constructeur de classe. Si une classe de base possède une méthode `__init__()`, la méthode `__init__()` de la classe dérivée, si elle existe, doit explicitement appeler cette méthode pour assurer une initialisation correcte de la partie classe de base de l'instance ; par exemple : `super().__init__([args…])`.

  Comme `__new__()` et `__init__()` travaillent ensemble pour créer des objets (`__new__()` pour le créer, `__init__()` pour le particulariser), `__init__()` ne doit pas renvoyer de valeur `None` ; sinon une exception `TypeError` est levée à l'exécution.

object.__del__(self)

  Appelée au moment où une instance est sur le point d'être détruite. On l'appelle aussi finaliseur ou (improprement) destructeur. Si une classe de base possède une méthode `__del__()`, la méthode `__del__()` de la classe dérivée, si elle existe, doit explicitement l'appeler pour s'assurer de l'effacement correct de la partie classe de base de l'instance.

  Il est possible (mais pas recommandé) que la méthode `__del__()` retarde la destruction de l'instance en créant une nouvelle référence vers cet objet. Python appelle ceci la résurrection d'objet. En fonction de l'implémentation, `__del__()` peut être appelée une deuxième fois au moment où l'objet ressuscité va être détruit ; l'implémentation actuelle de CPython ne l'appelle qu'une fois.

  Il n'est pas garanti que soient appelées les méthodes `__del__()` des objets qui existent toujours quand l'interpréteur termine.

  Note

  `del x` n'appelle pas directement `x.__del__()` — la première décrémente le compteur de références de `x`. La seconde n'est appelée que quand le compteur de références de `x` atteint zéro.

  Particularité de l'implémentation CPython : It is possible for a reference cycle to prevent the reference count of an object from going to zero. In this case, the cycle will be later detected and deleted by the cyclic garbage collector. A common cause of reference cycles is when an exception has been caught in a local variable. The frame's locals then reference the exception, which references its own traceback, which references the locals of all frames caught in the traceback.

  Voir aussi

  Documentation du module `gc`.

  Avertissement

  en raison des conditions particulières qui règnent quand `__del__()` est appelée, les exceptions levées pendant son exécution sont ignorées et, à la place, un avertissement est affiché sur `sys.stderr`. En particulier :

  - `__del__()` peut être invoquée quand du code arbitraire est en cours d'exécution, et ce dans n'importe quel fil d'exécution. Si `__del__()` a besoin de poser un verrou ou d'accéder à tout autre ressource bloquante, elle peut provoquer un blocage mutuel (deadlock en anglais) car la ressource peut être déjà utilisée par le code qui est interrompu pour exécuter la méthode `__del__()`.

  - `__del__()` peut être exécutée pendant que l'interpréteur se ferme. En conséquence, les variables globales auxquelles elle souhaite accéder (y compris les autres modules) peuvent déjà être détruites ou assignées à `None`. Python garantit que les variables globales dont le nom commence par un tiret bas sont supprimées de leur module avant que les autres variables globales ne le soient ; si aucune autre référence vers ces variables globales n'existe, cela peut aider à s'assurer que les modules importés soient toujours accessibles au moment où la méthode `__del__()` est appelée.

object.__repr__(self)

  Appelée par la fonction native `repr()` pour calculer la représentation « officielle » en chaîne de caractères d'un objet. Tout est fait pour que celle-ci ressemble à une expression Python valide pouvant être utilisée pour recréer un objet avec la même valeur (dans un environnement donné). Si ce n'est pas possible, une chaîne de la forme `<…une description utile…>` est renvoyée. La valeur renvoyée doit être un objet chaîne de caractères. Si une classe définit `__repr__()` mais pas `__str__()`, alors `__repr__()` est aussi utilisée quand une représentation « informelle » en chaîne de caractères est demandée pour une instance de cette classe.

  Cette fonction est principalement utilisée à fins de débogage, il est donc important que la représentation donne beaucoup d'informations et ne soit pas ambigüe.

object.__str__(self)

  Appelée par `str(objet)` ainsi que les fonctions natives `format()` et `print()` pour calculer une chaîne de caractères « informelle » ou joliment mise en forme de représentation de l'objet. La valeur renvoyée doit être un objet string.

  Cette méthode diffère de `object.__repr__()` car il n'est pas attendu que `__str__()` renvoie une expression Python valide : une représentation plus agréable à lire ou plus concise peut être utilisée.

  L'implémentation par défaut du type natif `object` appelle `object.__repr__()` .

object.__bytes__(self)

  Appelée par bytes pour calculer une représentation en chaîne bytes d'un objet. Elle doit renvoyer un objet `bytes`.

object.__format__(self, format_spec)

  Appelée par la fonction native `format()` et, par extension, lors de l'évaluation de chaînes de caractères littérales formatées et la méthode `str.format()`. Elle produit une chaîne de caractères « formatée » représentant un objet. L'argument `format_spec` est une chaîne de caractères contenant la description des options de formatage voulues. L'interprétation de l'argument `format_spec` est laissée au type implémentant `__format__()`. Cependant, la plupart des classes délèguent le formatage aux types natifs ou utilisent une syntaxe similaire pour les options de formatage.

  Lisez Mini-langage de spécification de format pour une description de la syntaxe standard du formatage.

  La valeur renvoyée doit être un objet chaîne de caractères.

  Modifié dans la version 3.4: la méthode `__format__` de `object` lui-même lève une `TypeError` si vous lui passez une chaîne non vide.

  Modifié dans la version 3.7: `object.__format__(x, '')` est maintenant équivalent à `str(x)` plutôt qu'à `format(str(x), '')`.

object.__lt__(self, other)
object.__le__(self, other)
object.__eq__(self, other)
object.__ne__(self, other)
object.__gt__(self, other)
object.__ge__(self, other)

  Ce sont les méthodes dites de « comparaisons riches ». La correspondance entre les symboles opérateurs et les noms de méthodes est la suivante : `x<y` appelle `x.__lt__(y)`, `x<=y` appelle `x.__le__(y)`, `x==y` appelle `x.__eq__(y)`, `x!=y` appelle `x.__ne__(y)`, `x>y` appelle `x.__gt__(y)` et `x>=y` appelle `x.__ge__(y)`.

  A rich comparison method may return the singleton `NotImplemented` if it does not implement the operation for a given pair of arguments. By convention, `False` and `True` are returned for a successful comparison. However, these methods can return any value, so if the comparison operator is used in a Boolean context (e.g., in the condition of an `if` statement), Python will call `bool()` on the value to determine if the result is true or false.

  By default, `object` implements `__eq__()` by using `is`, returning `NotImplemented` in the case of a false comparison: `True if x is y else NotImplemented`. For `__ne__()`, by default it delegates to `__eq__()` and inverts the result unless it is `NotImplemented`. There are no other implied relationships among the comparison operators or default implementations; for example, the truth of `(x<y or x==y)` does not imply `x<=y`. To automatically generate ordering operations from a single root operation, see `functools.total_ordering()`.

  Lisez le paragraphe `__hash__()` pour connaître certaines notions importantes relatives à la création d'objets hachables qui acceptent les opérations de comparaison personnalisées et qui sont utilisables en tant que clés de dictionnaires.

  There are no swapped-argument versions of these methods (to be used when the left argument does not support the operation but the right argument does); rather, `__lt__()` and `__gt__()` are each other's reflection, `__le__()` and `__ge__()` are each other's reflection, and `__eq__()` and `__ne__()` are their own reflection. If the operands are of different types, and the right operand's type is a direct or indirect subclass of the left operand's type, the reflected method of the right operand has priority, otherwise the left operand's method has priority. Virtual subclassing is not considered.

  When no appropriate method returns any value other than `NotImplemented`, the `==` and `!=` operators will fall back to `is` and `is not`, respectively.

object.__hash__(self)

  Appelée par la fonction native `hash()` et par les opérations sur les membres de collections hachées (ce qui comprend `set`, `frozenset` et `dict`). La méthode `__hash__()` doit renvoyer un entier. La seule propriété requise est que les objets qui sont égaux pour la comparaison doivent avoir la même valeur de hachage ; il est conseillé de mélanger les valeurs de hachage des composants d'un objet qui jouent un rôle dans la comparaison des objets, en les emballant dans un n-uplet dont on calcule l'empreinte. Par exemple :

      def __hash__(self):
          return hash((self.name, self.nick, self.color))

  Note

  `hash()` limite la valeur renvoyée d'un objet ayant une méthode `__hash__()` personnalisée à la taille d'un `Py_ssize_t`. C'est classiquement 8 octets pour une implémentation 64 bits et 4 octets sur une implémentation 32 bits. Si la méthode `__hash__()` d'un objet doit être interopérable sur des plateformes ayant des implémentations différentes, assurez-vous de vérifier la taille du hachage sur toutes les plateformes. Une manière facile de le faire est la suivante : `python -c "import sys; print(sys.hash_info.width)"`.

  If a class does not define an `__eq__()` method it should not define a `__hash__()` operation either; if it defines `__eq__()` but not `__hash__()`, its instances will not be usable as items in hashable collections. If a class defines mutable objects and implements an `__eq__()` method, it should not implement `__hash__()`, since the implementation of hashable collections requires that a key's hash value is immutable (if the object's hash value changes, it will be in the wrong hash bucket).

  Les classes définies par l'utilisateur possèdent des méthodes `__eq__()` et `__hash__()` par défaut ; ces méthodes répondent que tous les objets sont différents (sauf avec eux-mêmes) et `x.__hash__()` renvoie une valeur telle que `x == y` implique à la fois `x is y` et `hash(x) == hash(y)`.

  Une classe qui surcharge `__eq__()` et qui ne définit pas `__hash__()` a sa méthode `__hash__()` implicitement assignée à `None`. Quand la méthode `__hash__()` d'une classe est `None`, une instance de cette classe lève `TypeError` quand un programme essaie de demander son empreinte et elle est correctement identifiée comme non hachable quand on vérifie `isinstance(obj, collections.abc.Hashable)`.

  Si une classe qui surcharge `__eq__()` a besoin de conserver l'implémentation de `__hash__()` de la classe parente, vous devez l'indiquer explicitement à l'interpréteur en définissant `__hash__ = <ClasseParente>.__hash__`.

  Si une classe ne surcharge pas `__eq__()` et veut supprimer le calcul des empreintes, elle doit inclure `__hash__ = None` dans la définition de la classe. Une classe qui définit sa propre méthode `__hash__()` qui lève explicitement `TypeError` serait incorrectement identifiée comme hachable par un appel à `isinstance(obj, collections.abc.Hashable)`.

  Note

  par défaut, les valeurs renvoyées par `__hash__()` pour les chaînes et les bytes sont « salées » avec une valeur aléatoire non prévisible. Bien qu'une empreinte reste constante tout au long d'un processus Python, sa valeur n'est pas prévisible entre deux invocations de Python.

  This is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict insertion, O(n2) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.

  Modifier les empreintes obtenues par hachage modifie l'ordre d'itération sur les sets. Python n'a jamais donné de garantie sur cet ordre (d'ailleurs, l'ordre n'est pas le même entre les implémentations 32 et 64 bits).

  Voir aussi `PYTHONHASHSEED`.

  Modifié dans la version 3.3: la randomisation des empreintes est activée par défaut.

object.__bool__(self)

  Called to implement truth value testing and the built-in operation `bool()`; should return `False` or `True`. When this method is not defined, `__len__()` is called, if it is defined, and the object is considered true if its result is nonzero. If a class defines neither `__len__()` nor `__bool__()`, all its instances are considered true.

### 3.3.2. Personnalisation de l'accès aux attributs

Les méthodes suivantes peuvent être définies pour personnaliser l'accès aux attributs (utilisation, assignation, suppression de `x.name`) pour les instances de classes.

object.__getattr__(self, name)

  Appelée lorsque l'accès par défaut à l'attribut échoue en levant `AttributeError` (soit `__getattribute__()` lève `AttributeError` car name n'est pas un attribut de l'instance ou un attribut dans l'arborescence de la classe de `self` ; ou `__get__()` de la propriété name lève `AttributeError`). Cette méthode doit renvoyer soit la valeur (calculée) de l'attribut, soit lever une exception `AttributeError`.

  Notez que si l'attribut est trouvé par le mécanisme normal, `__getattr__()` n'est pas appelée (c'est une asymétrie voulue entre `__getattr__()` et `__setattr__()`). Ce comportement est adopté à la fois pour des raisons de performance et parce que, sinon, `__getattr__()` n'aurait aucun moyen d'accéder aux autres attributs de l'instance. Notez que, au moins pour ce qui concerne les variables d'instance, vous pouvez simuler un contrôle total en n'insérant aucune valeur dans le dictionnaire des attributs de l'instance (mais en les insérant dans un autre objet à la place). Lisez la partie relative à la méthode `__getattribute__()` ci-dessous pour obtenir un contrôle total effectif sur l'accès aux attributs.

object.__getattribute__(self, name)

  Appelée de manière inconditionnelle pour implémenter l'accès aux attributs des instances de la classe. Si la classe définit également `__getattr__()`, cette dernière n'est pas appelée à moins que `__getattribute__()` ne l'appelle explicitement ou ne lève une exception `AttributeError`. Cette méthode doit renvoyer la valeur (calculée) de l'attribut ou lever une exception `AttributeError`. Afin d'éviter une récursion infinie sur cette méthode, son implémentation doit toujours appeler la méthode de la classe de base avec le même paramètre name pour accéder à n'importe quel attribut dont elle a besoin. Par exemple, `object.__getattribute__(self, name)`.

  Note

  This method may still be bypassed when looking up special methods as the result of implicit invocation via language syntax or built-in functions. See Recherche des méthodes spéciales.

  Lève un événement d'audit `object.__getattr__` avec les arguments `obj` et `name`.

object.__setattr__(self, name, value)

  Appelée lors d'une assignation d'attribut. Elle est appelée à la place du mécanisme normal (c'est-à-dire stocker la valeur dans le dictionnaire de l'instance). name est le nom de l'attribut, value est la valeur à assigner à cet attribut.

  Si `__setattr__()` veut assigner un attribut d'instance, elle doit appeler la méthode de la classe de base avec le même nom, par exemple `object.__setattr__(self, name, value)`.

  Lève un événement d'audit `object.__setattr__` avec les arguments `obj`, `name` et `value`.

object.__delattr__(self, name)

  Comme `__setattr__()` mais pour supprimer un attribut au lieu de l'assigner. Elle ne doit être implémentée que si `del obj.name` a du sens pour cet objet.

  Lève un événement d'audit `object.__deltattr__` avec les arguments `obj` et `name`.

object.__dir__(self)

  Called when `dir()` is called on the object. An iterable must be returned. `dir()` converts the returned iterable to a list and sorts it.

#### 3.3.2.1. Personnalisation de l'accès aux attributs d'un module

Les noms spéciaux `__getattr__` et `__dir__` peuvent aussi être personnalisés pour accéder aux attributs du module. La fonction `__getattr__` au niveau du module doit accepter un argument qui est un nom d'attribut et doit renvoyer la valeur calculée ou lever une `AttributeError`. Si un attribut n'est pas trouvé dans l'objet module en utilisant la recherche normale, c'est-à-dire `object.__getattribute__()`, alors Python recherche `__getattr__` dans le `__dict__` du module avant de lever une `AttributeError`. S'il la trouve, il l'appelle avec le nom de l'attribut et renvoie le résultat.

The `__dir__` function should accept no arguments, and return an iterable of strings that represents the names accessible on module. If present, this function overrides the standard `dir()` search on a module.

Pour une personnalisation plus fine du comportement d'un module (assignation des attributs, propriétés, etc.), vous pouvez assigner l'attribut `__class__` d'un objet module à une sous-classe de `types.ModuleType`. Par exemple :

    import sys
    from types import ModuleType

    class VerboseModule(ModuleType):
        def __repr__(self):
            return f'Verbose {self.__name__}'

        def __setattr__(self, attr, value):
            print(f'Setting {attr}...')
            super().__setattr__(attr, value)

    sys.modules[__name__].__class__ = VerboseModule

Note

définir `__getattr__` du module et `__class__` pour le module impacte uniquement les recherches qui utilisent la syntaxe d'accès aux attributs — accéder directement aux globales d'un module (soit par le code dans le module, soit via une référence au dictionnaire des variables globales du module) fonctionne toujours de la même façon.

Modifié dans la version 3.5: l'attribut `__class__` du module est maintenant en lecture-écriture.

Nouveau dans la version 3.7: attributs `__getattr__` et `__dir__` du module.

Voir aussi

PEP 562 — `__getattr__` et `__dir__` pour un module

  Décrit les fonctions `__getattr__` et `__dir__` des modules.

#### 3.3.2.2. Implémentation de descripteurs

Les méthodes qui suivent s'appliquent seulement quand une instance de la classe (dite classe descripteur) contenant la méthode apparaît dans une classe propriétaire (owner en anglais) ; la classe descripteur doit figurer dans le dictionnaire de la classe propriétaire ou dans le dictionnaire de la classe d'un des parents. Dans les exemples ci-dessous, « l'attribut » fait référence à l'attribut dont le nom est une clé du `__dict__` de la classe propriétaire.

object.__get__(self, instance, owner=None)

  Appelée pour obtenir l'attribut de la classe propriétaire (accès à un attribut de classe) ou d'une instance de cette classe (accès à un attribut d'instance). L'argument optionnel owner est la classe propriétaire alors que instance est l'instance par laquelle on accède à l'attribut ou `None` lorsque l'on accède par la classe owner.

  Il convient que cette méthode renvoie la valeur calculée de l'attribut ou lève une exception `AttributeError`.

  La PEP 252 spécifie que `__get__()` soit un appelable avec un ou deux arguments. Les descripteurs natifs de Python suivent cette spécification ; cependant, il est probable que des outils tiers aient des descripteurs qui requièrent les deux arguments. L'implémentation de `__getattribute__()` de Python passe toujours les deux arguments, qu'ils soient requis ou non.

object.__set__(self, instance, value)

  Appelée pour définir l'attribut d'une instance instance de la classe propriétaire à la nouvelle valeur value.

  Notez que ajouter `__set__()` ou `__delete__()` modifie la nature du descripteur vers un « descripteur de donnée ». Reportez-vous à Invocation des descripteurs pour plus de détails.

object.__delete__(self, instance)

  Appelée pour supprimer l'attribut de l'instance instance de la classe propriétaire.

Instances of descriptors may also have the `__objclass__` attribute present:

object.__objclass__

  The attribute `__objclass__` is interpreted by the `inspect` module as specifying the class where this object was defined (setting this appropriately can assist in runtime introspection of dynamic class attributes). For callables, it may indicate that an instance of the given type (or a subclass) is expected or required as the first positional argument (for example, CPython sets this attribute for unbound methods that are implemented in C).

#### 3.3.2.3. Invocation des descripteurs

En général, un descripteur est un attribut d'objet dont le comportement est « lié » (binding dehavior en anglais), c'est-à-dire que les accès aux attributs ont été surchargés par des méthodes conformes au protocole des descripteurs : `__get__()`, `__set__()` et `__delete__()`. Si l'une de ces méthodes est définie pour un objet, il est réputé être un descripteur.

Le comportement par défaut pour la gestion d'un attribut est de définir, obtenir et supprimer cet attribut du dictionnaire de l'objet. Par exemple, pour `a.x` Python commence d'abord par rechercher `a.__dict__['x']`, puis `type(a).__dict__['x']` ; ensuite Python continue en remontant les classes de base de `type(a)`, en excluant les métaclasses.

Cependant, si la valeur cherchée est un objet qui définit une des méthodes de descripteur, alors Python modifie son comportement et invoque la méthode du descripteur à la place. Le moment où cela intervient dans la recherche citée ci-dessus dépend de l'endroit où a été définie la méthode de descripteur et comment elle a été appelée.

Le point de départ pour une invocation de descripteur est la liaison `a.x`. La façon dont les arguments sont assemblés dépend de `a` :

Appel direct

  Le plus simple et le plus rare des appels est quand l'utilisateur code directement l'appel à la méthode du descripteur : `x.__get__(a)`.

Liaison avec une instance

  Si elle est liée à un objet instance, `a.x` est transformé en l'appel suivant : `type(a).__dict__['x'].__get__(a, type(a))`.

Liaison avec une classe

  Si elle est liée à une classe, `A.x` est transformé en l'appel suivant : `A.__dict__['x'].__get__(None, A)`.

Liaison super

  Une recherche avec un point telle que `super(A, a).x` cherche `a.__class__.__mro__` pour une classe de base `B` qui suit (dans l'ordre MRO) `A`, puis renvoie `B.__dict__['x'].__get__(a, A)`. Si ce n'est pas un descripteur, `x` est renvoyé inchangé.

For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination of `__get__()`, `__set__()` and `__delete__()`. If it does not define `__get__()`, then accessing the attribute will return the descriptor object itself unless there is a value in the object's instance dictionary. If the descriptor defines `__set__()` and/or `__delete__()`, it is a data descriptor; if it defines neither, it is a non-data descriptor. Normally, data descriptors define both `__get__()` and `__set__()`, while non-data descriptors have just the `__get__()` method. Data descriptors with `__get__()` and `__set__()` (and/or `__delete__()`) defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances.

Les méthodes Python (y compris celles décorées par `@staticmethod` et `@classmethod`) sont implémentées comme des descripteurs hors-données. De la même manière, les instances peuvent redéfinir et surcharger les méthodes. Ceci permet à chaque instance d'avoir un comportement qui diffère des autres instances de la même classe.

La fonction `property()` est implémentée en tant que descripteur de données. Ainsi, les instances ne peuvent pas surcharger le comportement d'une propriété.

#### 3.3.2.4. créneaux prédéfinis (`__slots__`)

Les créneaux prédéfinis (`__slots__`) vous permettent de déclarer des membres d'une donnée (comme une propriété) et d'interdire la création de `__dict__` ou de __weakref__ (à moins qu'ils ne soient explicitement déclarés dans le `__slots__` ou présent dans le parent).

L'espace gagné par rapport à l'utilisation d'un `__dict__` peut être significatif. La recherche d'attribut peut aussi s'avérer beaucoup plus rapide.

object.__slots__

  Cette variable de classe peut être assignée avec une chaîne, un itérable ou une séquence de chaînes avec les noms de variables utilisés par les instances. __slots__ réserve de la place pour ces variables déclarées et interdit la création automatique de `__dict__` et __weakref__ pour chaque instance.

Notes on using __slots__:

- Lorsque vous héritez d'une classe sans __slots__, les attributs `__dict__` et __weakref__ des instances sont toujours accessibles.

- Sans variable `__dict__`, les instances ne peuvent pas assigner de nouvelles variables (non listées dans la définition de __slots__). Les tentatives d'assignation sur un nom de variable non listé lève `AttributeError`. Si l'assignation dynamique de nouvelles variables est nécessaire, ajoutez `'__dict__'` à la séquence de chaînes dans la déclaration __slots__.

- Sans variable __weakref__ pour chaque instance, les classes qui définissent __slots__ ne gèrent pas les `références faibles` vers leurs instances. Si vous avez besoin de gérer des références faibles, ajoutez `'__weakref__'` à la séquence de chaînes dans la déclaration de __slots__.

- Les __slots__ sont implémentés au niveau de la classe en créant des descripteurs pour chaque nom de variable. Ainsi, les attributs de classe ne peuvent pas être utilisés pour des valeurs par défaut aux variables d'instances définies par __slots__ ; sinon, l'attribut de classe surchargerait l'assignation par descripteur.

- L'action de la déclaration du __slots__ ne se limite pas à la classe où il est défini. Les __slots__ déclarés par les parents sont disponibles dans les classes enfants. Cependant, les sous-classes enfants ont un `__dict__` et un __weakref__ à moins qu'elles ne définissent aussi un __slots__ (qui ne doit contenir alors que les noms supplémentaires aux créneaux déjà prédéfinis).

- Si une classe définit un slot déjà défini dans une classe de base, la variable d'instance définie par la classe de base est inaccessible (sauf à utiliser le descripteur de la classe de base directement). Cela rend la signification du programme indéfinie. Dans le futur, une vérification sera ajoutée pour empêcher cela.

- `TypeError` will be raised if nonempty __slots__ are defined for a class derived from a `"variable-length" built-in type` such as `int`, `bytes`, and `tuple`.

- Tout itérable, sauf les chaînes de caractères, peuvent être affectés à __slots__.

- Si vous affectez __slots__ à un `dictionnaire`, les clés du dictionnaires seront les noms du slot. Les valeurs du dictionnaire peuvent être utilisées en tant que chaines de description (docstrings) et sont reconnues par `inspect.getdoc()` qui les affiche dans la sortie de `help()`.

- Les assignations de `__class__` ne fonctionnent que si les deux classes ont le même __slots__.

- L'héritage multiple avec plusieurs classes parentes qui ont des __slots__ est possible, mais seul un parent peut avoir des attributs créés par __slots__ (les autres classes parentes doivent avoir des __slots__ vides). La violation de cette règle lève `TypeError`.

- Si un itérateur est utilisé pour __slots__, alors un descripteur est créé pour chacune des valeurs de l'itérateur. Cependant, l'attribut __slots__ est un itérateur vide.

### 3.3.3. Personnalisation de la création de classes

Quand une classe hérite d'une classe parente, la méthode `__init_subclass__()` de la classe parente est appelée. Ainsi, il est possible d'écrire des classes qui modifient le comportement des sous-classes. Ce comportement est corrélé aux décorateurs de classes mais, alors que les décorateurs de classes agissent seulement sur la classe qu'ils décorent, `__init_subclass__` agit uniquement sur les futures sous-classes de la classe qui définit cette méthode.

classmethod object.__init_subclass__(cls)

  Cette méthode est appelée quand la classe est sous-classée. cls est alors la nouvelle sous-classe. Si elle est définie en tant que méthode d'instance normale, cette méthode est implicitement convertie en méthode de classe.

  Keyword arguments which are given to a new class are passed to the parent class's `__init_subclass__`. For compatibility with other classes using `__init_subclass__`, one should take out the needed keyword arguments and pass the others over to the base class, as in:

      class Philosopher:
          def __init_subclass__(cls, /, default_name, **kwargs):
              super().__init_subclass__(**kwargs)
              cls.default_name = default_name

      class AustralianPhilosopher(Philosopher, default_name="Bruce"):
          pass

  L'implémentation par défaut de `object.__init_subclass__` ne fait rien sans argument, mais lève une erreur si elle est appelée avec un argument ou plus.

  Note

  l'indication de métaclasse `metaclass` est absorbée par le reste du mécanisme de types et n'est jamais passée à l'implémentation de `__init_subclass__`. La métaclasse réelle (plutôt que l'indication explicite) peut être récupérée par `type(cls)`.

  Nouveau dans la version 3.6.

Lorsqu'une classe est créée, `type.__new__()` exécute le point d'entrée `___set_name__()` de toute variable de la classe qui en possède un.

object.__set_name__(self, owner, name)

  Appelée automatiquement au moment où la classe propriétaire owner est créée. L'objet self a été assigné à name dans owner :

      class A:
          x = C()  # Automatically calls: x.__set_name__(A, 'x')

  Si l'affectation se produit après la création de la classe, le point d'entrée `__set_name__()` n'est pas appelé automatiquement. Mais il est autorisé d'appeler `__set_name__()` manuellement :

      class A:
         pass

      c = C()
      A.x = c                  # The hook is not called
      c.__set_name__(A, 'x')   # Manually invoke the hook

  Consultez Création de l'objet classe pour davantage de détails.

  Nouveau dans la version 3.6.

#### 3.3.3.1. Métaclasses

Par défaut, les classes sont construites en utilisant `type()`. Le corps de la classe est exécuté dans un nouvel espace de nommage et le nom de la classe est lié localement au résultat de `type(name, bases, namespace)`.

Le déroulement de création de la classe peut être personnalisé en passant l'argument nommé `metaclass` dans la ligne de définition de la classe ou en héritant d'une classe existante qui comporte déjà un tel argument. Dans l'exemple qui suit, `MyClass` et `MySubclass` sont des instances de `Meta` :

    class Meta(type):
        pass

    class MyClass(metaclass=Meta):
        pass

    class MySubclass(MyClass):
        pass

Tout autre argument nommé spécifié dans la définition de la classe est passé aux opérations de métaclasses décrites auparavant.

Quand la définition d'une classe est exécutée, les différentes étapes suivies sont :

- les entrées MRO sont résolues ;

- la métaclasse appropriée est déterminée ;

- l'espace de nommage de la classe est préparé ;

- le corps de la classe est exécuté ;

- l'objet classe est créé.

#### 3.3.3.2. Résolution des entrées MRO

object.__mro_entries__(self, bases)

  If a base that appears in a class definition is not an instance of `type`, then an `__mro_entries__()` method is searched on the base. If an `__mro_entries__()` method is found, the base is substituted with the result of a call to `__mro_entries__()` when creating the class. The method is called with the original bases tuple passed to the bases parameter, and must return a tuple of classes that will be used instead of the base. The returned tuple may be empty: in these cases, the original base is ignored.

Voir aussi

`types.resolve_bases()`

  Dynamically resolve bases that are not instances of `type`.

PEP 560

  Core support for typing module and generic types.

#### 3.3.3.3. Détermination de la métaclasse appropriée

La métaclasse appropriée pour une définition de classe est déterminée de la manière suivante :

- si aucune classe et aucune métaclasse n'est donnée, alors `type()` est utilisée ;

- si une métaclasse explicite est donnée et que ce n'est pas une instance de `type()`, alors elle est utilisée directement en tant que métaclasse ;

- si une instance de `type()` est donnée comme métaclasse explicite ou si bases est définie, alors la métaclasse la plus dérivée est utilisée.

La métaclasse la plus dérivée est choisie à partir des métaclasses explicitement spécifiées (s'il y en a) et les métaclasses (c'est-à-dire les `type(cls)`) de toutes les classes de base spécifiées. La métaclasse la plus dérivée est celle qui est un sous-type de toutes ces métaclasses candidates. Si aucune des métaclasses candidates ne remplit ce critère, alors la définition de la classe échoue en levant `TypeError`.

#### 3.3.3.4. Préparation de l'espace de nommage de la classe

Une fois que la métaclasse appropriée est identifiée, l'espace de nommage de la classe est préparé. Si la métaclasse possède un attribut `__prepare__`, il est appelé avec `namespace = metaclass.__prepare__(name, bases, **kwds)` (où les arguments nommés supplémentaires, s'il y en a, sont les arguments de la définition de la classe). La méthode `__prepare__` doit être implémentée comme une `méthode de classe`). L’espace de nommage renvoyé par `__prepare__` est passé à `__new__`, mais quand l’instance finale est créée, l’espace de nommage est copié vers un nouveau `dict`.

Si la métaclasse ne possède pas d'attribut `__prepare__`, alors l'espace de nommage de la classe est initialisé en tant que tableau de correspondances ordonné.

Voir aussi

PEP 3115 — Métaclasses dans Python 3000

  introduction de la fonction automatique `__prepare__` de l'espace de nommage

#### 3.3.3.5. Exécution du corps de la classe

Le corps de la classe est exécuté (approximativement) avec `exec(body, globals(), namespace)`. La principale différence avec un appel normal à `exec()` est que la portée lexicale autorise le corps de la classe (y compris les méthodes) à faire référence aux noms de la portée courante et des portées externes lorsque la définition de classe a lieu dans une fonction.

Cependant, même quand une définition de classe intervient dans une fonction, les méthodes définies à l'intérieur de la classe ne peuvent pas voir les noms définis en dehors de la portée de la classe. On accède aux variables de la classe via le premier paramètre des méthodes d'instance ou de classe, ou via la référence implicite `__class__` incluse dans la portée lexicale et décrite dans la section suivante.

#### 3.3.3.6. Création de l'objet classe

Quand l'espace de nommage a été rempli en exécutant le corps de la classe, l'objet classe est créé en appelant `metaclass(name, bases, namespace, **kwds)` (les arguments nommés supplémentaires passés ici sont les mêmes que ceux passés à `__prepare__`).

Cet objet classe est celui qui est référencé par la forme sans argument de `super()`. `__class__` est une référence implicite créée par le compilateur si une méthode du corps de la classe fait référence soit à `__class__`, soit à `super`. Ceci permet que la forme sans argument de `super()` identifie la classe en cours de définition en fonction de la portée lexicale, tandis que la classe ou l'instance utilisée pour effectuer l'appel en cours est identifiée en fonction du premier argument transmis à la méthode.

Particularité de l'implémentation CPython : dans CPython 3.6 et suivants, la cellule `__class__` est passée à la métaclasse en tant qu'entrée `__classcell__` dans l'espace de nommage de la classe. Si elle est présente, elle doit être propagée à l'appel `type.__new__` pour que la classe soit correctement initialisée. Ne pas le faire se traduit par un `RuntimeError` dans Python 3.8.

Quand vous utilisez la métaclasse par défaut `type` ou toute autre métaclasse qui finit par appeler `type.__new__`, les étapes de personnalisation supplémentaires suivantes sont suivies après la création de l'objet classe :

1. `type.__new__` récupère, dans l'espace de nommage de la classe, tous les descripteurs qui définissent une méthode `__set_name__()` ;

2. Toutes ces méthodes `__set_name__` sont appelées avec la classe en cours de définition et le nom assigné à chaque descripteur ;

3. La méthode automatique `__init_subclass__()` est appelée sur le parent immédiat de la nouvelle classe en utilisant l'ordre de résolution des méthodes.

Après la création de l'objet classe, il est passé aux décorateurs de la classe, y compris ceux inclus dans la définition de la classe (s'il y en a) et l'objet résultant est lié à l'espace de nommage local en tant que classe définie.

Quand une nouvelle classe est créée via `type.__new__`, l'objet fourni en tant que paramètre d'espace de nommage est copié vers un nouveau tableau de correspondances ordonné et l'objet original est laissé de côté. La nouvelle copie est encapsulée dans un mandataire en lecture seule qui devient l'attribut `__dict__` de l'objet classe.

Voir aussi

PEP 3135 — Nouvelle méthode super

  Décrit la référence à la fermeture (closure en anglais) de la `__class__` implicite

#### 3.3.3.7. Cas d'utilisations des métaclasses

Les utilisations possibles des métaclasses sont immenses. Quelques pistes ont déjà été explorées comme l'énumération, la gestion des traces, le contrôle des interfaces, la délégation automatique, la création automatique de propriétés, les mandataires, les frameworks ainsi que le verrouillage ou la synchronisation automatique de ressources.

### 3.3.4. Personnalisation des instances et vérification des sous-classes

Les méthodes suivantes sont utilisées pour surcharger le comportement par défaut des fonctions natives `isinstance()` et `issubclass()`.

En particulier, la métaclasse `abc.ABCMeta` implémente ces méthodes pour autoriser l'ajout de classes de base abstraites (ABC pour Abstract Base Classes en anglais) en tant que « classes de base virtuelles » pour toute classe ou type (y compris les types natifs).

class.__instancecheck__(self, instance)

  Renvoie `True` si instance doit être considérée comme une instance (directe ou indirecte) de class. Si elle est définie, elle est appelée pour implémenter `isinstance(instance, class)`.

class.__subclasscheck__(self, subclass)

  Renvoie `True` si subclass doit être considérée comme une sous-classe (directe ou indirecte) de class. Si elle est définie, appelée pour implémenter `issubclass(subclass, class)`.

Notez que ces méthodes sont recherchées dans le type (la métaclasse) d'une classe. Elles ne peuvent pas être définies en tant que méthodes de classe dans la classe réelle. C'est cohérent avec la recherche des méthodes spéciales qui sont appelées pour les instances, sauf qu'ici l'instance est elle-même une classe.

Voir aussi

PEP 3119 — Introduction aux classes de bases abstraites

  Inclut la spécification pour la personnalisation du comportement de `isinstance()` et `issubclass()` à travers `__instancecheck__()` et `__subclasscheck__()`, avec comme motivation pour cette fonctionnalité l'ajout des classes de base abstraites (voir le module `abc`) au langage.

### 3.3.5. Émulation de types génériques

Lors de l'utilisation d'annotations de types, il est souvent utile de paramètrer un type générique en se servant de la notation crochets de Python. Par exemple, l'annotation `list[int]` peut être utilisée pour signifier une `liste` dans laquelle tous les éléments sont de type `entiers`.

Voir aussi

PEP 343 — Indications de types

  Introduction à l'annotation de types en Python (document en anglais)

Types alias génériques

  Documentation pour les objets qui représentent des classes génériques paramétrées

Génériques, Types génériques définis par l'utilisateur et classe `typing.Generic (classe de base abstraite pour les types génériques)`

  Documentation sur la manière d'implémenter des classes génériques qui peuvent être paramétrées à l'exécution et comprises par les vérificateurs statiques de types.

Généralement, une classe ne peut être paramétrée que si elle définit une méthode spéciale de classe `__class_getitem__()`.

classmethod object.__class_getitem__(cls, key)

  Renvoie un objet représentant la spécialisation d'une classe générique en fonction des arguments types trouvés dans key.

  Lorsqu'elle est définie dans une classe, `__class_getitem__()` est automatiquement une méthode de classe. Ainsi, il est superflu de la décorer avec `@classmethod` lors de sa définition.

#### 3.3.5.1. Intention de __class_getitem__

Le but de `__class_getitem__()` est de permettre la paramétrisation à l'exécution des classes génériques de la bibliothèque standard de façon à pouvoir appliquer plus facilement des annotations de type à ces classes.

Pour implémenter des classes génériques particularisées pouvant être paramétrées à l'exécution, et comprises par les vérificateurs statiques de type, vous pouvez soit hériter d'une classe de la bibliothèque standard qui implémente déjà `__class_getitem__()`, ou hériter de `typing.Generic`, qui a sa propre implémentation de `__class_getitem__()`.

Les implémentations particularisées de `__class_getitem__()` sur des classes définies ailleurs que la bibliothèque standard peuvent ne pas être comprises par des vérificateurs de types tiers tels que mypy. L'utilisation de `__class_getitem__()` pour tout autre objectif que l'annotation de type n'est pas conseillée.

#### 3.3.5.2. __class_getitem__ contre __getitem__

D'habitude, l'indiçage d'un objet en utilisant des crochets appelle la méthode `__getitem__()` de l'instance, définie dans la classe de l'objet. Cependant, si l'objet dont on cherche un indice est lui-même une classe, la méthode de classe `__class_getitem__()` peut être appelée à la place. `__class_getitem__()` doit renvoyer un objet GenericAlias si elle est correctement définie.

Lorsqu'on lui présente l'expression `obj[x]`, l'interpréteur Python suit une sorte de processus suivant pour décider s'il faut appeler `__getitem__()` ou `__class_getitem__()` :

    from inspect import isclass

    def subscribe(obj, x):
        """Return the result of the expression 'obj[x]'"""

        class_of_obj = type(obj)

        # If the class of obj defines __getitem__,
        # call class_of_obj.__getitem__(obj, x)
        if hasattr(class_of_obj, '__getitem__'):
            return class_of_obj.__getitem__(obj, x)

        # Else, if obj is a class and defines __class_getitem__,
        # call obj.__class_getitem__(x)
        elif isclass(obj) and hasattr(obj, '__class_getitem__'):
            return obj.__class_getitem__(x)

        # Else, raise an exception
        else:
            raise TypeError(
                f"'{class_of_obj.__name__}' object is not subscriptable"
            )

En Python, toutes les classes sont des instances d'autres classes. La classe d'une classe est appelée la métaclasse de la classe et la plupart des classes ont la classe `type` comme métaclasse. `type` ne définit pas `__getitem__()`, ce qui veut dire que des expressions telles que `list[int]`, `dict[str, float]` et `tuple[str, bytes]` aboutissent toutes à l'appel de `__class_getitem__()` :

    >>> # list has class "type" as its metaclass, like most classes:
    >>> type(list)
    <class 'type'>
    >>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
    True
    >>> # "list[int]" calls "list.__class_getitem__(int)"
    >>> list[int]
    list[int]
    >>> # list.__class_getitem__ returns a GenericAlias object:
    >>> type(list[int])
    <class 'types.GenericAlias'>

Cependant, si une classe a une métaclasse particularisée qui définit `__getitem__()`, l'indiçage de la classe peut conduire à un comportement différent. Un exemple peut être trouvé dans le module `enum` :

    >>> from enum import Enum
    >>> class Menu(Enum):
    ...     """A breakfast menu"""
    ...     SPAM = 'spam'
    ...     BACON = 'bacon'
    ...
    >>> # Enum classes have a custom metaclass:
    >>> type(Menu)
    <class 'enum.EnumMeta'>
    >>> # EnumMeta defines __getitem__,
    >>> # so __class_getitem__ is not called,
    >>> # and the result is not a GenericAlias object:
    >>> Menu['SPAM']
    <Menu.SPAM: 'spam'>
    >>> type(Menu['SPAM'])
    <enum 'Menu'>

Voir aussi

PEP 560 — Gestion de base pour les types modules et les types génériques

  Introduction de `__class_getitem__()`, et présentation des cas où un indiçage conduit à l'appel de `__class_getitem__()` au lieu de `__getitem__()`

### 3.3.6. Émulation d'objets appelables

object.__call__(self[, args...])

  Appelée quand l'instance est « appelée » en tant que fonction ; si la méthode est définie, `x(arg1, arg2, …)` est un raccourci pour `type(x).__call__(x, arg1, …)`.

### 3.3.7. Émulation de types conteneurs

The following methods can be defined to implement container objects. Containers usually are sequences (such as `lists` or `tuples`) or mappings (like `dictionaries`), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers k for which `0 <= k < N` where N is the length of the sequence, or `slice` objects, which define a range of items. It is also recommended that mappings provide the methods `keys()`, `values()`, `items()`, `get()`, `clear()`, `setdefault()`, `pop()`, `popitem()`, `copy()`, and `update()` behaving similar to those for Python's standard `dictionary` objects. The `collections.abc` module provides a `MutableMapping` abstract base class to help create those methods from a base set of `__getitem__()`, `__setitem__()`, `__delitem__()`, and `keys()`. Mutable sequences should provide methods `append()`, `count()`, `index()`, `extend()`, `insert()`, `pop()`, `remove()`, `reverse()` and `sort()`, like Python standard `list` objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods `__add__()`, `__radd__()`, `__iadd__()`, `__mul__()`, `__rmul__()` and `__imul__()` described below; they should not define other numerical operators. It is recommended that both mappings and sequences implement the `__contains__()` method to allow efficient use of the `in` operator; for mappings, `in` should search the mapping's keys; for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the `__iter__()` method to allow efficient iteration through the container; for mappings, `__iter__()` should iterate through the object's keys; for sequences, it should iterate through the values.

object.__len__(self)

  Called to implement the built-in function `len()`. Should return the length of the object, an integer `>=` 0. Also, an object that doesn't define a `__bool__()` method and whose `__len__()` method returns zero is considered to be false in a Boolean context.

  Particularité de l'implémentation CPython : In CPython, the length is required to be at most `sys.maxsize`. If the length is larger than `sys.maxsize` some features (such as `len()`) may raise `OverflowError`. To prevent raising `OverflowError` by truth value testing, an object must define a `__bool__()` method.

object.__length_hint__(self)

  Called to implement `operator.length_hint()`. Should return an estimated length for the object (which may be greater or less than the actual length). The length must be an integer `>=` 0. The return value may also be `NotImplemented`, which is treated the same as if the `__length_hint__` method didn't exist at all. This method is purely an optimization and is never required for correctness.

  Nouveau dans la version 3.4.

Note

le découpage est effectué uniquement à l'aide des trois méthodes suivantes. Un appel comme

    a[1:2] = b

est traduit en

    a[slice(1, 2, None)] = b

et ainsi de suite. Les éléments manquants sont remplacés par `None`.

object.__getitem__(self, key)

  Called to implement evaluation of `self[key]`. For sequence types, the accepted keys should be integers. Optionally, they may support `slice` objects as well. Negative index support is also optional. If key is of an inappropriate type, `TypeError` may be raised; if key is a value outside the set of indexes for the sequence (after any special interpretation of negative values), `IndexError` should be raised. For mapping types, if key is missing (not in the container), `KeyError` should be raised.

  Note

  `for` s'attend à ce qu'une `IndexError` soit levée en cas d'indice illégal afin de détecter correctement la fin de la séquence.

  Note

  quand on vous spécifiez un indice pour une classe, la méthode de classe spéciale `__class_getitem__()` peut être appelée au lieu de `__getitem__()`. Reportez-vous à __class_getitem__ contre __getitem__ pour plus de détails.

object.__setitem__(self, key, value)

  Appelée pour implémenter l'assignation à `self[key]`. La même note que pour `__getitem__()` s'applique. Elle ne doit être implémentée que pour les tableaux de correspondances qui autorisent les modifications de valeurs des clés, ceux pour lesquels on peut ajouter de nouvelles clés ou, pour les séquences, celles dont les éléments peuvent être remplacés. Les mêmes exceptions que pour la méthode `__getitem__()` doivent être levées en cas de mauvaises valeurs de clés.

object.__delitem__(self, key)

  Appelée pour implémenter la suppression de `self[key]`. La même note que pour `__getitem__()` s'applique. Elle ne doit être implémentée que pour les tableaux de correspondances qui autorisent les suppressions de clés ou pour les séquences dont les éléments peuvent être supprimés de la séquence. Les mêmes exceptions que pour la méthode `__getitem__()` doivent être levées en cas de mauvaises valeurs de clés.

object.__missing__(self, key)

  Appelée par `dict`.`__getitem__()` pour implémenter `self[key]` dans les sous-classes de dictionnaires lorsque la clé n'est pas dans le dictionnaire.

object.__iter__(self)

  Cette méthode est appelée quand un itérateur est requis pour un conteneur. Cette méthode doit renvoyer un nouvel objet itérateur qui peut itérer sur tous les objets du conteneur. Pour les tableaux de correspondances, elle doit itérer sur les clés du conteneur.

object.__reversed__(self)

  Appelée (si elle existe) par la fonction native `reversed()` pour implémenter l'itération en sens inverse. Elle doit renvoyer un nouvel objet itérateur qui itère sur tous les objets du conteneur en sens inverse.

  Si la méthode `__reversed__()` n'est pas fournie, la fonction native `reversed()` se replie sur le protocole de séquence (`__len__()` et `__getitem__()`). Les objets qui connaissent le protocole de séquence ne doivent fournir `__reversed__()` que si l'implémentation qu'ils proposent est plus efficace que celle de `reversed()`.

Les opérateurs de tests d'appartenance (`in` et `not in`) sont normalement implémentés comme des itérations sur un conteneur. Cependant, les objets conteneurs peuvent fournir les méthodes spéciales suivantes avec une implémentation plus efficace, qui ne requièrent d'ailleurs pas que l'objet soit itérable.

object.__contains__(self, item)

  Appelée pour implémenter les opérateurs de test d'appartenance. Elle doit renvoyer `True` si item est dans self et `False` sinon. Pour les tableaux de correspondances, seules les clés sont considérées (pas les valeurs des paires clés-valeurs).

  Pour les objets qui ne définissent pas `__contains__()`, les tests d'appartenance essaient d'abord d'itérer avec `__iter__()` puis avec le vieux protocole d'itération sur les séquences via `__getitem__()`, reportez-vous à cette section dans la référence du langage.

### 3.3.8. Émulation de types numériques

Les méthodes suivantes peuvent être définies pour émuler des objets numériques. Les méthodes correspondant à des opérations qui ne sont pas autorisées pour la catégorie de nombres considérée (par exemple, les opérations bit à bit pour les nombres qui ne sont pas entiers) doivent être laissées indéfinies.

object.__add__(self, other)
object.__sub__(self, other)
object.__mul__(self, other)
object.__matmul__(self, other)
object.__truediv__(self, other)
object.__floordiv__(self, other)
object.__mod__(self, other)
object.__divmod__(self, other)
object.__pow__(self, other[, modulo])
object.__lshift__(self, other)
object.__rshift__(self, other)
object.__and__(self, other)
object.__xor__(self, other)
object.__or__(self, other)

  Ces méthodes sont appelées pour implémenter les opérations arithmétiques binaires (`+`, `-`, `*`, `@`, `/`, `//`, `%`, `divmod()`, `pow()`, `**`, `<<`, `>>`, `&`, `^`, `|`). Par exemple, pour évaluer l'expression `x + y`, où x est une instance d'une classe qui possède une méthode `__add__()`, `type(x).__add__(x, y)` est appelée. La méthode `__divmod__()` doit être l'équivalent d'appeler `__floordiv__()` et `__mod__()` ; elle ne doit pas être reliée à `__truediv__()`. Notez que `__pow__()` doit être définie de manière à accepter un troisième argument optionnel si la version ternaire de la fonction native `pow()` est autorisée.

  If one of those methods does not support the operation with the supplied arguments, it should return `NotImplemented`.

object.__radd__(self, other)
object.__rsub__(self, other)
object.__rmul__(self, other)
object.__rmatmul__(self, other)
object.__rtruediv__(self, other)
object.__rfloordiv__(self, other)
object.__rmod__(self, other)
object.__rdivmod__(self, other)
object.__rpow__(self, other[, modulo])
object.__rlshift__(self, other)
object.__rrshift__(self, other)
object.__rand__(self, other)
object.__rxor__(self, other)
object.__ror__(self, other)

  These methods are called to implement the binary arithmetic operations (`+`, `-`, `*`, `@`, `/`, `//`, `%`, `divmod()`, `pow()`, `**`, `<<`, `>>`, `&`, `^`, `|`) with reflected (swapped) operands. These functions are only called if the left operand does not support the corresponding operation [3] and the operands are of different types. [4] For instance, to evaluate the expression `x - y`, where y is an instance of a class that has an `__rsub__()` method, `type(y).__rsub__(y, x)` is called if `type(x).__sub__(x, y)` returns `NotImplemented`.

  Notez que la fonction ternaire `pow()` n'essaie pas d'appeler `__rpow__()` (les règles de coercition seraient trop compliquées).

  Note

  si le type de l'opérande de droite est une sous-classe du type de l'opérande de gauche et que cette sous-classe fournit une implémentation différente de la méthode symétrique pour l'opération, cette méthode est appelée avant la méthode originelle de l'opérande gauche. Ce comportement permet à des sous-classes de surcharger les opérations de leurs ancêtres.

object.__iadd__(self, other)
object.__isub__(self, other)
object.__imul__(self, other)
object.__imatmul__(self, other)
object.__itruediv__(self, other)
object.__ifloordiv__(self, other)
object.__imod__(self, other)
object.__ipow__(self, other[, modulo])
object.__ilshift__(self, other)
object.__irshift__(self, other)
object.__iand__(self, other)
object.__ixor__(self, other)
object.__ior__(self, other)

  These methods are called to implement the augmented arithmetic assignments (`+=`, `-=`, `*=`, `@=`, `/=`, `//=`, `%=`, `**=`, `<<=`, `>>=`, `&=`, `^=`, `|=`). These methods should attempt to do the operation in-place (modifying self) and return the result (which could be, but does not have to be, self). If a specific method is not defined, or if that method returns `NotImplemented`, the augmented assignment falls back to the normal methods. For instance, if x is an instance of a class with an `__iadd__()` method, `x += y` is equivalent to `x = x.__iadd__(y)` . If `__iadd__()` does not exist, or if `x.__iadd__(y)` returns `NotImplemented`, `x.__add__(y)` and `y.__radd__(x)` are considered, as with the evaluation of `x + y`. In certain situations, augmented assignment can result in unexpected errors (see Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?), but this behavior is in fact part of the data model.

object.__neg__(self)
object.__pos__(self)
object.__abs__(self)
object.__invert__(self)

  Appelées pour implémenter les opérations arithmétiques unaires (`-`, `+`, `abs()` et `~`).

object.__complex__(self)
object.__int__(self)
object.__float__(self)

  Appelées pour implémenter les fonctions natives `complex()`, `int()` et `float()`. Elles doivent renvoyer une valeur du type approprié.

object.__index__(self)

  Appelée pour implémenter `operator.index()` et lorsque Python a besoin de convertir sans perte un objet numérique en objet entier (pour un découpage ou dans les fonctions natives `bin()`, `hex()` et `oct()`). La présence de cette méthode indique que l'objet numérique est un type entier. Elle doit renvoyer un entier.

  Si `__int__()`, `__float__()` et `__complex__()` ne sont pas définies, alors les fonctions natives `int()`, `float()` et `complex()` redirigent par défaut vers `__index__()`.

object.__round__(self[, ndigits])
object.__trunc__(self)
object.__floor__(self)
object.__ceil__(self)

  Appelées pour implémenter la fonction native `round()` et les fonctions du module `math` `trunc()`, `floor()` et `ceil()`. À moins que ndigits ne soit passé à `__round__()`, toutes ces méthodes doivent renvoyer la valeur de l'objet tronquée pour donner un `Integral` (typiquement un `int`).

  La fonction native `int()` se replie sur `__trunc__()` dans le cas où ni `__int__()` ni `__index__()` ne sont définies.

  Modifié dans la version 3.11: la délégation de `int()` vers `__trunc__()` est obsolète.

### 3.3.9. Gestionnaire de contexte With

Un gestionnaire de contexte est un objet qui met en place un contexte prédéfini au moment de l'exécution de l'instruction `with`. Le gestionnaire de contexte gère l'entrée et la sortie de ce contexte d'exécution pour tout un bloc de code. Les gestionnaires de contextes sont normalement invoqués en utilisant une instruction `with` (décrite dans la section L'instruction with), mais ils peuvent aussi être directement invoqués par leurs méthodes.

Les utilisations classiques des gestionnaires de contexte sont la sauvegarde et la restauration d'états divers, le verrouillage et le déverrouillage de ressources, la fermeture de fichiers ouverts, etc.

Pour plus d'informations sur les gestionnaires de contexte, lisez Le type gestionnaire de contexte.

object.__enter__(self)

  Entre dans le contexte d'exécution relatif à cet objet. L'instruction `with` lie la valeur de retour de cette méthode à une (ou plusieurs) cible spécifiée par la clause `as` de l'instruction, si elle est spécifiée.

object.__exit__(self, exc_type, exc_value, traceback)

  Sort du contexte d'exécution relatif à cet objet. Les paramètres décrivent l'exception qui a causé la sortie du contexte. Si l'on sort du contexte sans exception, les trois arguments sont à `None`.

  Si une exception est indiquée et que la méthode souhaite supprimer l'exception (c'est-à-dire qu'elle ne veut pas que l'exception soit propagée), elle doit renvoyer `True`. Sinon, l'exception est traitée normalement à la sortie de cette méthode.

  Note that `__exit__()` methods should not reraise the passed-in exception; this is the caller's responsibility.

Voir aussi

PEP 343 — L'instruction `with`

  La spécification, les motivations et des exemples de l'instruction `with` en Python.

### 3.3.10. Arguments positionnels dans le filtrage par motif sur les classes

When using a class name in a pattern, positional arguments in the pattern are not allowed by default, i.e. `case MyClass(x, y)` is typically invalid without special support in `MyClass`. To be able to use that kind of pattern, the class needs to define a __match_args__ attribute.

object.__match_args__

  Cet attribut de la classe est un n-uplet de chaînes. Lorsque la classe apparaît dans un filtre avec des arguments positionnels, ils sont convertis en arguments nommés avec les noms du n-uplet, dans l'ordre. Si l'attribut n'est pas défini, tout se passe comme si sa valeur était le n-uplet vide `()`.

Ainsi, si `UneClasse.__match_args__` est mis à `("gauche", "milieu", "droite")`, le filtre `case UneClasse(x, y)` est équivalent à `case UneClasse(gauche=x, milieu=y)`. Le filtre doit comporter au maximum autant d'arguments positionnels que la longueur `__match_args__`. Dans le cas contraire, le filtrage lève l'exception `TypeError`.

Nouveau dans la version 3.10.

Voir aussi

PEP 634 — Filtrage par motif structurel

  Spécification de l'instruction `match`.

### 3.3.11. Recherche des méthodes spéciales

Pour les classes définies par le développeur, l'invocation implicite de méthodes spéciales n'est garantie que si ces méthodes sont définies par le type d'objet, pas dans le dictionnaire de l'objet instance. Ce comportement explique pourquoi le code suivant lève une exception :

    >>> class C:
    ...     pass
    ...
    >>> c = C()
    >>> c.__len__ = lambda: 5
    >>> len(c)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: object of type 'C' has no len()

La raison de ce comportement vient de certaines méthodes spéciales telles que `__hash__()` et `__repr__()` qui sont implémentées par tous les objets, y compris les objets types. Si la recherche effectuée par ces méthodes utilisait le processus normal de recherche, elles ne fonctionneraient pas si on les appelait sur l'objet type lui-même :

    >>> 1 .__hash__() == hash(1)
    True
    >>> int.__hash__() == hash(int)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: descriptor '__hash__' of 'int' object needs an argument

Essayer d'invoquer une méthode non liée d'une classe de cette manière est parfois appelé « confusion de métaclasse » et se contourne en shuntant l'instance lors de la recherche des méthodes spéciales :

    >>> type(1).__hash__(1) == hash(1)
    True
    >>> type(int).__hash__(int) == hash(int)
    True

En plus de shunter les attributs des instances pour fonctionner correctement, la recherche des méthodes spéciales implicites shunte aussi la méthode `__getattribute__()` même dans la métaclasse de l'objet :

    >>> class Meta(type):
    ...     def __getattribute__(*args):
    ...         print("Metaclass getattribute invoked")
    ...         return type.__getattribute__(*args)
    ...
    >>> class C(object, metaclass=Meta):
    ...     def __len__(self):
    ...         return 10
    ...     def __getattribute__(*args):
    ...         print("Class getattribute invoked")
    ...         return object.__getattribute__(*args)
    ...
    >>> c = C()
    >>> c.__len__()                 # Explicit lookup via instance
    Class getattribute invoked
    10
    >>> type(c).__len__(c)          # Explicit lookup via type
    Metaclass getattribute invoked
    10
    >>> len(c)                      # Implicit lookup
    10

En shuntant le mécanisme de `__getattribute__()` de cette façon, cela permet d'optimiser la vitesse de l'interpréteur moyennant une certaine manœuvre dans la gestion des méthodes spéciales (la méthode spéciale doit être définie sur l'objet classe lui-même afin d'être invoquée de manière cohérente par l'interpréteur).

## 3.4. Coroutines

### 3.4.1. Objets attendables (awaitable)

Un objet awaitable implémente généralement une méthode `__await__()`. Les objets coroutine renvoyés par les fonctions `async def` sont des attendables (awaitable).

Note

les objets itérateur de générateur renvoyés par les générateurs décorés par `types.coroutine()` sont aussi des attendables (awaitable), mais ils n'implémentent pas `__await__()`.

object.__await__(self)

  Doit renvoyer un itérateur. Doit être utilisé pour implémenter les objets awaitable. Par exemple, `asyncio.Future` implémente cette méthode pour être compatible avec les expressions `await`.

  Note

  The language doesn't place any restriction on the type or value of the objects yielded by the iterator returned by `__await__`, as this is specific to the implementation of the asynchronous execution framework (e.g. `asyncio`) that will be managing the awaitable object.

Nouveau dans la version 3.5.

Voir aussi

PEP 492 pour les informations relatives aux objets attendables (awaitable).

### 3.4.2. Objets coroutines

Les objets coroutine sont des objets awaitable. L'exécution d'une coroutine peut être contrôlée en appelant `__await__()` et en itérant sur le résultat. Quand la coroutine a fini de s'exécuter et termine, l'itérateur lève `StopIteration` et l'attribut `value` de l'exception contient la valeur de retour. Si la coroutine lève une exception, elle est propagée par l'itérateur. Les coroutines ne doivent pas lever directement des exceptions `StopIteration` non gérées.

Les coroutines disposent aussi des méthodes listées ci-dessous, analogues à celles des générateurs (voir Méthodes des générateurs-itérateurs). Cependant, au contraire des générateurs, vous ne pouvez pas itérer directement sur des coroutines.

Modifié dans la version 3.5.2: utiliser await plus d'une fois sur une coroutine lève une `RuntimeError`.

coroutine.send(value)

  Starts or resumes execution of the coroutine. If value is `None`, this is equivalent to advancing the iterator returned by `__await__()`. If value is not `None`, this method delegates to the `send()` method of the iterator that caused the coroutine to suspend. The result (return value, `StopIteration`, or other exception) is the same as when iterating over the `__await__()` return value, described above.

coroutine.throw(value)
coroutine.throw(type[, value[, traceback]])

  Lève l'exception spécifiée dans la coroutine. Cette méthode délègue à la méthode `throw()` de l'itérateur qui a causé la suspension de la coroutine, s'il possède une telle méthode. Sinon, l'exception est levée au point de suspension. Le résultat (valeur de retour, `StopIteration` ou une autre exception) est le même que lorsque vous itérez sur la valeur de retour de `__await__()`, décrite ci-dessus. Si l'exception n'est pas gérée par la coroutine, elle est propagée à l'appelant.

coroutine.close()

  Demande à la coroutine de faire le ménage et de se terminer. Si la coroutine est suspendue, cette méthode délègue d'abord à la méthode `close()` de l'itérateur qui a causé la suspension de la coroutine, s'il possède une telle méthode. Ensuite, elle lève `GeneratorExit` au point de suspension, ce qui fait le ménage dans la coroutine immédiatement. Enfin, la coroutine est marquée comme ayant terminé son exécution, même si elle n'a jamais démarré.

  Les objets coroutines sont automatiquement fermés en utilisant le processus décrit au-dessus au moment où ils sont détruits.

### 3.4.3. Itérateurs asynchrones

Un itérateur asynchrone peut appeler du code asynchrone dans sa méthode `__anext__`.

Les itérateurs asynchrones peuvent être utilisés dans des instructions `async for`.

object.__aiter__(self)

  Doit renvoyer un objet itérateur asynchrone.

object.__anext__(self)

  Doit renvoyer un attendable (awaitable) qui se traduit par la valeur suivante de l'itérateur. Doit lever une `StopAsyncIteration` quand l'itération est terminée.

Un exemple d'objet itérateur asynchrone :

    class Reader:
        async def readline(self):
            ...

        def __aiter__(self):
            return self

        async def __anext__(self):
            val = await self.readline()
            if val == b'':
                raise StopAsyncIteration
            return val

Nouveau dans la version 3.5.

Modifié dans la version 3.7: avant Python 3.7, `__aiter__()` pouvait renvoyer un attendable (awaitable) qui se résolvait potentiellement en un itérateur asynchrone.

À partir de Python 3.7, `__aiter__()` doit renvoyer un objet itérateur asynchrone. Renvoyer autre chose entraine une erreur `TypeError`.

### 3.4.4. Gestionnaires de contexte asynchrones

Un gestionnaire de contexte asynchrone est un gestionnaire de contexte qui est capable de suspendre son exécution dans ses méthodes `__aenter__` et `__aexit__`.

Les gestionnaires de contexte asynchrones peuvent être utilisés dans des instructions `async with`.

object.__aenter__(self)

  Semantically similar to `__enter__()`, the only difference being that it must return an awaitable.

object.__aexit__(self, exc_type, exc_value, traceback)

  Semantically similar to `__exit__()`, the only difference being that it must return an awaitable.

Un exemple de classe de gestionnaire de contexte asynchrone :

    class AsyncContextManager:
        async def __aenter__(self):
            await log('entering context')

        async def __aexit__(self, exc_type, exc, tb):
            await log('exiting context')

Nouveau dans la version 3.5.

Notes de bas de page

[1]

Il est possible, dans certains cas, de changer le type d'un objet, sous certaines conditions. Cependant, ce n'est généralement pas une bonne idée car cela peut conduire à un comportement très étrange si ce n'est pas géré correctement.

[2]

Les méthodes `__hash__()`, `__iter__()`, `__reversed__()` et `__contains__()` ont une gestion particulière pour cela ; les autres lèvent toujours `TypeError`, mais le font en considérant que `None` n'est pas un appelable.

[3]

"Does not support" here means that the class has no such method, or the method returns `NotImplemented`. Do not set the method to `None` if you want to force fallback to the right operand's reflected method—that will instead have the opposite effect of explicitly blocking such fallback.

[4]

Pour des opérandes de même type, on considère que si la méthode originelle (telle que `__add__()`) échoue, alors l'opération en tant que telle n'est pas autorisée et donc la méthode symétrique n'est pas appelée.