3. Modèle de données
********************


3.1. Objets, valeurs et types
=============================

*Objects* are Python's abstraction for data.  All data in a Python
program is represented by objects or by relations between objects.
Even code is represented by objects.

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.

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.

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é.

Types affect almost all aspects of object behavior.  Even the
importance of object identity is affected in some sense: for immutable
types, operations that compute new values may actually return a
reference to any existing object with the same type and value, while
for mutable objects this is not allowed. For example, after "a = 1; b
= 1", *a* and *b* may or may not refer to the same object with the
value one, depending on the implementation. This is because "int" is
an immutable type, so the reference to "1" can be reused. This
behaviour depends on the implementation used, so should not be relied
upon, but is something to be aware of when making use of object
identity tests. However, after "c = []; d = []", *c* and *d* are
guaranteed to refer to two different, unique, newly created empty
lists. (Note that "e = f = []" assigns the *same* object to both *e*
and *f*.)


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 was deprecated.

Modifié dans la version 3.14: Evaluating "NotImplemented" in a boolean
context now raises a "TypeError". It previously evaluated to "True"
and emitted a "DeprecationWarning" since Python 3.9.


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 distinguishes between integers, floating-point numbers, and
complex numbers:


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")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These represent machine-level double precision floating-point numbers.
You are at the mercy of the underlying machine architecture (and C or
Java implementation) for the accepted range and handling of overflow.
Python does not support single-precision floating-point numbers; the
savings in processor and memory usage that are usually the reason for
using these are dwarfed by the overhead of using objects in Python, so
there is no reason to complicate the language with two kinds of
floating-point numbers.


3.2.4.3. "numbers.Complex" ("complex")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These represent complex numbers as a pair of machine-level double
precision floating-point numbers.  The same caveats apply as for
floating-point numbers. The real and imaginary parts of a complex
number "z" can be retrieved through the read-only attributes "z.real"
and "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*)
   A bytes object is an immutable array.  The items are 8-bit bytes,
   represented by integers in the range 0 <= x < 256.  Bytes literals
   (like "b'abc'") and the built-in "bytes()" constructor can be used
   to create bytes objects.  Also, bytes objects can be decoded to
   strings via the "decode()" method.


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
   These represent a mutable set. They are created by the built-in
   "set()" constructor and can be modified afterwards by several
   methods, such as "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.

Dictionaries are mutable; they can be created by the "{}" notation
(see 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.__builtins__                              | A reference to the "dictionary" that holds the     |
|                                                    | function's builtins namespace.  Ajouté dans la     |
|                                                    | version 3.10.                                      |
+----------------------------------------------------+----------------------------------------------------+
| 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 names specified in the "co_freevars"       |
|                                                    | attribute of the function's "code object".  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.                                       |
+----------------------------------------------------+----------------------------------------------------+
| function.__name__                                  | The function's name. See also: "__name__           |
|                                                    | attributes".                                       |
+----------------------------------------------------+----------------------------------------------------+
| function.__qualname__                              | The function's *qualified name*. See also:         |
|                                                    | "__qualname__ attributes".  Ajouté 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:                 |
|                                                    | "object.__annotations__".  Modifié dans la version |
|                                                    | 3.14: Annotations are now lazily evaluated. See    |
|                                                    | **PEP 649**.                                       |
+----------------------------------------------------+----------------------------------------------------+
| function.__annotate__                              | The *annotate function* for this function, or      |
|                                                    | "None" if the function has no annotations. See     |
|                                                    | "object.__annotate__".  Ajouté dans la version     |
|                                                    | 3.14.                                              |
+----------------------------------------------------+----------------------------------------------------+
| function.__kwdefaults__                            | A "dictionary" containing defaults for keyword-    |
|                                                    | only *parameters*.                                 |
+----------------------------------------------------+----------------------------------------------------+
| function.__type_params__                           | A "tuple" containing the type parameters of a      |
|                                                    | generic function.  Ajouté dans la version 3.12.    |
+----------------------------------------------------+----------------------------------------------------+

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.

It is 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 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".


3.2.9.1. Import-related attributes on module objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Module objects have the following attributes that relate to the import
system. When a module is created using the machinery associated with
the import system, these attributes are filled in based on the
module's *spec*, before the *loader* executes and loads the module.

To create a module dynamically rather than using the import system,
it's recommended to use "importlib.util.module_from_spec()", which
will set the various import-controlled attributes to appropriate
values. It's also possible to use the "types.ModuleType" constructor
to create modules directly, but this technique is more error-prone, as
most attributes must be manually set on the module object after it has
been created when using this approach.

Prudence:

  With the exception of "__name__", it is **strongly** recommended
  that you rely on "__spec__" and its attributes instead of any of the
  other individual attributes listed in this subsection. Note that
  updating an attribute on "__spec__" will not update the
  corresponding attribute on the module itself:

     >>> import typing
     >>> typing.__name__, typing.__spec__.name
     ('typing', 'typing')
     >>> typing.__spec__.name = 'spelling'
     >>> typing.__name__, typing.__spec__.name
     ('typing', 'spelling')
     >>> typing.__name__ = 'keyboard_smashing'
     >>> typing.__name__, typing.__spec__.name
     ('keyboard_smashing', 'spelling')

module.__name__

   The name used to uniquely identify the module in the import system.
   For a directly executed module, this will be set to ""__main__"".

   This attribute must be set to the fully qualified name of the
   module. It is expected to match the value of
   "module.__spec__.name".

module.__spec__

   A record of the module's import-system-related state.

   Set to the "module spec" that was used when importing the module.
   See Spécificateurs de modules for more details.

   Ajouté dans la version 3.4.

module.__package__

   The *package* a module belongs to.

   If the module is top-level (that is, not a part of any specific
   package) then the attribute should be set to "''" (the empty
   string). Otherwise, it should be set to the name of the module's
   package (which can be equal to "module.__name__" if the module
   itself is a package). See **PEP 366** for further details.

   This attribute is used instead of "__name__" to calculate explicit
   relative imports for main modules. It defaults to "None" for
   modules created dynamically using the "types.ModuleType"
   constructor; use "importlib.util.module_from_spec()" instead to
   ensure the attribute is set to a "str".

   It is **strongly** recommended that you use
   "module.__spec__.parent" instead of "module.__package__".
   "__package__" is now only used as a fallback if "__spec__.parent"
   is not set, and this fallback path is deprecated.

   Modifié dans la version 3.4: This attribute now defaults to "None"
   for modules created dynamically using the "types.ModuleType"
   constructor. Previously the attribute was optional.

   Modifié dans la version 3.6: The value of "__package__" is expected
   to be the same as "__spec__.parent". "__package__" is now only used
   as a fallback during import resolution if "__spec__.parent" is not
   defined.

   Modifié dans la version 3.10: "ImportWarning" is raised if an
   import resolution falls back to "__package__" instead of
   "__spec__.parent".

   Modifié dans la version 3.12: Raise "DeprecationWarning" instead of
   "ImportWarning" when falling back to "__package__" during import
   resolution.

   Deprecated since version 3.13, will be removed in version 3.15:
   "__package__" will cease to be set or taken into consideration by
   the import system or standard library.

module.__loader__

   The *loader* object that the import machinery used to load the
   module.

   This attribute is mostly useful for introspection, but can be used
   for additional loader-specific functionality, for example getting
   data associated with a loader.

   "__loader__" defaults to "None" for modules created dynamically
   using the "types.ModuleType" constructor; use
   "importlib.util.module_from_spec()" instead to ensure the attribute
   is set to a *loader* object.

   It is **strongly** recommended that you use
   "module.__spec__.loader" instead of "module.__loader__".

   Modifié dans la version 3.4: This attribute now defaults to "None"
   for modules created dynamically using the "types.ModuleType"
   constructor. Previously the attribute was optional.

   Deprecated since version 3.12, will be removed in version 3.16:
   Setting "__loader__" on a module while failing to set
   "__spec__.loader" is deprecated. In Python 3.16, "__loader__" will
   cease to be set or taken into consideration by the import system or
   the standard library.

module.__path__

   A (possibly empty) *sequence* of strings enumerating the locations
   where the package's submodules will be found. Non-package modules
   should not have a "__path__" attribute. See l'attribut __path__ des
   modules for more details.

   It is **strongly** recommended that you use
   "module.__spec__.submodule_search_locations" instead of
   "module.__path__".

module.__file__

module.__cached__

   "__file__" and "__cached__" are both optional attributes that may
   or may not be set. Both attributes should be a "str" when they are
   available.

   "__file__" indicates the pathname of the file from which the module
   was loaded (if loaded from a file), or the pathname of the shared
   library file for extension modules loaded dynamically from a shared
   library. It might be missing for certain types of modules, such as
   C modules that are statically linked into the interpreter, and the
   import system may opt to leave it unset if it has no semantic
   meaning (for example, a module loaded from a database).

   If "__file__" is set then the "__cached__" attribute might also be
   set,  which is the path to any compiled version of the code (for
   example, a byte-compiled file). The file does not need to exist to
   set this attribute; the path can simply point to where the compiled
   file *would* exist (see **PEP 3147**).

   Note that "__cached__" may be set even if "__file__" is not set.
   However, that scenario is quite atypical.  Ultimately, the *loader*
   is what makes use of the module spec provided by the *finder* (from
   which "__file__" and "__cached__" are derived).  So if a loader can
   load from a cached module but otherwise does not load from a file,
   that atypical scenario may be appropriate.

   It is **strongly** recommended that you use
   "module.__spec__.cached" instead of "module.__cached__".

   Deprecated since version 3.13, will be removed in version 3.15:
   Setting "__cached__" on a module while failing to set
   "__spec__.cached" is deprecated. In Python 3.15, "__cached__" will
   cease to be set or taken into consideration by the import system or
   standard library.


3.2.9.2. Other writable attributes on module objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As well as the import-related attributes listed above, module objects
also have the following writable attributes:

module.__doc__

   The module's documentation string, or "None" if unavailable. See
   also: "__doc__ attributes".

module.__annotations__

   A dictionary containing *variable annotations* collected during
   module body execution.  For best practices on working with
   "__annotations__", see "annotationlib".

   Modifié dans la version 3.14: Annotations are now lazily evaluated.
   See **PEP 649**.

module.__annotate__

   The *annotate function* for this module, or "None" if the module
   has no annotations. See also: "__annotate__" attributes.

   Ajouté dans la version 3.14.


3.2.9.3. Module dictionaries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Module objects also have the following special read-only attribute:

module.__dict__

   The module's namespace as a dictionary object. Uniquely among the
   attributes listed here, "__dict__" cannot be accessed as a global
   variable from within a module; it can only be accessed as an
   attribute on module objects.

   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
--------------------------------------------

Custom class types are typically created by class definitions (see
section Définition de classes).  A class has a namespace implemented
by a dictionary object. Class attribute references are translated to
lookups in this dictionary, e.g., "C.x" is translated to
"C.__dict__["x"]" (although there are a number of hooks which allow
for other means of locating attributes). When the attribute name is
not found there, the attribute search continues in the base classes.
This search of the base classes uses the C3 method resolution order
which behaves correctly even in the presence of 'diamond' inheritance
structures where there are multiple inheritance paths leading back to
a common ancestor. Additional details on the C3 MRO used by Python can
be found at The Python 2.3 Method Resolution Order.

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).


3.2.10.1. Special attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------------------------------------------------+----------------------------------------------------+
| Attribut                                           | Signification                                      |
|====================================================|====================================================|
| type.__name__                                      | The class's name. See also: "__name__ attributes". |
+----------------------------------------------------+----------------------------------------------------+
| type.__qualname__                                  | The class's *qualified name*. See also:            |
|                                                    | "__qualname__ attributes".                         |
+----------------------------------------------------+----------------------------------------------------+
| type.__module__                                    | Nom du module où la classe a été définie.          |
+----------------------------------------------------+----------------------------------------------------+
| type.__dict__                                      | A "mapping proxy" providing a read-only view of    |
|                                                    | the class's namespace. See also: "__dict__         |
|                                                    | attributes".                                       |
+----------------------------------------------------+----------------------------------------------------+
| type.__bases__                                     | A "tuple" containing the class's bases. In most    |
|                                                    | cases, for a class defined as "class X(A, B, C)",  |
|                                                    | "X.__bases__" will be exactly equal to "(A, B,     |
|                                                    | C)".                                               |
+----------------------------------------------------+----------------------------------------------------+
| type.__base__                                      | **Particularité de l'implémentation CPython :**    |
|                                                    | The single base class in the inheritance chain     |
|                                                    | that is responsible for the memory layout of       |
|                                                    | instances. This attribute corresponds to "tp_base" |
|                                                    | at the C level.                                    |
+----------------------------------------------------+----------------------------------------------------+
| type.__doc__                                       | The class's documentation string, or "None" if     |
|                                                    | undefined. Not inherited by subclasses.            |
+----------------------------------------------------+----------------------------------------------------+
| type.__annotations__                               | A dictionary containing *variable annotations*     |
|                                                    | collected during class body execution. See also:   |
|                                                    | "__annotations__ attributes".  For best practices  |
|                                                    | on working with "__annotations__", please see      |
|                                                    | "annotationlib". Use                               |
|                                                    | "annotationlib.get_annotations()" instead of       |
|                                                    | accessing this attribute directly.  Avertissement: |
|                                                    | Accessing the "__annotations__" attribute directly |
|                                                    | on a class object may return annotations for the   |
|                                                    | wrong class, specifically in certain cases where   |
|                                                    | the class, its base class, or a metaclass is       |
|                                                    | defined under "from __future__ import              |
|                                                    | annotations". See **749** for details.This         |
|                                                    | attribute does not exist on certain builtin        |
|                                                    | classes. On user-defined classes without           |
|                                                    | "__annotations__", it is an empty dictionary.      |
|                                                    | Modifié dans la version 3.14: Annotations are now  |
|                                                    | lazily evaluated. See **PEP 649**.                 |
+----------------------------------------------------+----------------------------------------------------+
| type.__annotate__()                                | The *annotate function* for this class, or "None"  |
|                                                    | if the class has no annotations. See also:         |
|                                                    | "__annotate__ attributes".  Ajouté dans la version |
|                                                    | 3.14.                                              |
+----------------------------------------------------+----------------------------------------------------+
| type.__type_params__                               | A "tuple" containing the type parameters of a      |
|                                                    | generic class.  Ajouté dans la version 3.12.       |
+----------------------------------------------------+----------------------------------------------------+
| type.__static_attributes__                         | A "tuple" containing names of attributes of this   |
|                                                    | class which are assigned through "self.X" from any |
|                                                    | function in its body.  Ajouté dans la version      |
|                                                    | 3.13.                                              |
+----------------------------------------------------+----------------------------------------------------+
| type.__firstlineno__                               | The line number of the first line of the class     |
|                                                    | definition, including decorators. Setting the      |
|                                                    | "__module__" attribute removes the                 |
|                                                    | "__firstlineno__" item from the type's dictionary. |
|                                                    | Ajouté dans la version 3.13.                       |
+----------------------------------------------------+----------------------------------------------------+
| type.__mro__                                       | The "tuple" of classes that are considered when    |
|                                                    | looking for base classes during method resolution. |
+----------------------------------------------------+----------------------------------------------------+


3.2.10.2. Special methods
~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the special attributes described above, all Python
classes also have the following two methods available:

type.mro()

   This method can be overridden by a metaclass to customize the
   method resolution order for its instances.  It is called at class
   instantiation, and its result is stored in "__mro__".

type.__subclasses__()

   Each class keeps a list of weak references to its immediate
   subclasses. This method returns a list of all those references
   still alive. The list is in definition order. Example:

      >>> class A: pass
      >>> class B(A): pass
      >>> A.__subclasses__()
      [<class 'B'>]


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.


3.2.11.1. Special attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

object.__class__

   Classe de l'instance de classe.

object.__dict__

   A dictionary or other mapping object used to store an object's
   (writable) attributes. Not all instances have a "__dict__"
   attribute; see the section on créneaux prédéfinis (__slots__) for
   more details.


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  Ajouté 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 from at least one *nested      |
|                                                    | scope* inside the function                         |
+----------------------------------------------------+----------------------------------------------------+
| codeobject.co_freevars                             | A "tuple" containing the names of *free (closure)  |
|                                                    | variables* that a *nested scope* references in an  |
|                                                    | outer scope. See also "function.__closure__".      |
|                                                    | Note: references to global and builtin names are   |
|                                                    | *not* included.                                    |
+----------------------------------------------------+----------------------------------------------------+
| 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.  Obsolète depuis   |
|                                                    | la version 3.12: This attribute of code objects is |
|                                                    | deprecated, and may be removed in Python 3.15.     |
+----------------------------------------------------+----------------------------------------------------+
| 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 (for example, "from __future__ import
division") also use bits in "co_flags" to indicate whether a code
object was compiled with a particular feature enabled. See
"compiler_flag".

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

If a code object represents a function and has a docstring, the
"CO_HAS_DOCSTRING" bit is set in "co_flags" and the first item in
"co_consts" is the docstring of the function.


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".

   Ajouté 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 *bytecode*s. 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.

   Ajouté 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.

   Code objects are also supported by the generic function
   "copy.replace()".

   Ajouté 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 mapping used by the frame to look up local     |
|                                                    | variables. If the frame refers to an *optimized    |
|                                                    | scope*, this may return a write-through proxy      |
|                                                    | object.  Modifié dans la version 3.13: Return a    |
|                                                    | proxy for optimized scopes.                        |
+----------------------------------------------------+----------------------------------------------------+
| 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)                                   |
+----------------------------------------------------+----------------------------------------------------+
| frame.f_generator                                  | The *generator* or *coroutine* object that owns    |
|                                                    | this frame, or "None" if the frame is a normal     |
|                                                    | function.  Ajouté dans la version 3.14.            |
+----------------------------------------------------+----------------------------------------------------+


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" is raised if the frame is currently executing or
   suspended.

   Ajouté dans la version 3.4.

   Modifié dans la version 3.13: Attempting to clear a suspended frame
   raises "RuntimeError" (as has always been the case for executing
   frames).


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].

When implementing a class that emulates any built-in type, it is
important that the emulation only be implemented to the degree that it
makes sense for the object being modelled.  For example, some
sequences may work well with retrieval of individual elements, but
extracting a slice may not make sense. (One example of this is the
NodeList interface in the W3C's Document Object Model.)


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.

   It is not guaranteed that "__del__()" methods are called for
   objects that still exist when the interpreter exits.
   "weakref.finalize" provides a straightforward way to register a
   cleanup function to be called when an object is garbage collected.

   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.

   Il est possible qu'un cycle de référence empêche le compteur de
   références d'un objet d'atteindre zéro. Dans ce cas, le cycle sera
   ultérieurement détecté et supprimé par le *ramasse-miettes*. Une
   cause fréquente de cycle de références est lorsqu'une exception a
   été interceptée dans une variable locale. Les paramètres locaux de
   la trame font ensuite référence à l'exception, qui fait référence à
   sa propre trace d'appels, qui fait référence aux paramètres locaux
   de toutes les cadres capturés dans la trace d'appels.

   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.

   This is typically used for debugging, so it is important that the
   representation is information-rich and unambiguous. A default
   implementation is provided by the "object" class itself.

object.__str__(self)

   Called by "str(object)", the default "__format__()" implementation,
   and the built-in function "print()", to compute the "informal" or
   nicely printable string representation of an object.  The return
   value must be a str object.

   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)

   Called by bytes to compute a byte-string representation of an
   object. This should return a "bytes" object. The "object" class
   itself does not provide this method.

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.

   The default implementation by the "object" class should be given an
   empty *format_spec* string. It delegates to "__str__()".

   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()".

   By default, the "object" class provides implementations consistent
   with Comparaisons de valeurs: equality compares according to object
   identity, and order comparisons raise "TypeError". Each default
   method may generate these results directly, but may also return
   "NotImplemented".

   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).

   User-defined classes have "__eq__()" and "__hash__()" methods by
   default (inherited from the "object" class); with them, all objects
   compare unequal (except with themselves) and "x.__hash__()" returns
   an appropriate value such that "x == y" implies both that "x is y"
   and "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*(*n*^2) 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__()" (which is true of the "object"
   class itself), 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)

   Called when the default attribute access fails with an
   "AttributeError" (either "__getattribute__()" raises an
   "AttributeError" because *name* is not an instance attribute or an
   attribute in the class tree for "self"; or "__get__()" of a *name*
   property raises "AttributeError").  This method should either
   return the (computed) attribute value or raise an "AttributeError"
   exception. The "object" class itself does not provide this method.

   Note that if the attribute is found through the normal mechanism,
   "__getattr__()" is not called.  (This is an intentional asymmetry
   between "__getattr__()" and "__setattr__()".) This is done both for
   efficiency reasons and because otherwise "__getattr__()" would have
   no way to access other attributes of the instance.  Note that at
   least for instance variables, you can take total control by not
   inserting any values in the instance attribute dictionary (but
   instead inserting them in another object).  See the
   "__getattribute__()" method below for a way to actually get total
   control over attribute access.

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.

   Pour les accès à certains attributs sensibles, 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)".

   Pour les assignations de certains attributs sensibles, 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.

   Pour les suppressions de certains attributs sensibles, 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

module.__getattr__()
module.__dir__()

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.

module.__class__

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.

Ajouté 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following methods only apply when an instance of the class
containing the method (a so-called *descriptor* class) appears in an
*owner* class (the descriptor must be in either the owner's class
dictionary or in the class dictionary for one of its parents).  In the
examples below, "the attribute" refers to the attribute whose name is
the key of the property in the owner class' "__dict__".  The "object"
class itself does not implement any of these protocols.

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.

Python methods (including those decorated with "@staticmethod" and
"@classmethod") are implemented as non-data descriptors.  Accordingly,
instances can redefine and override methods.  This allows individual
instances to acquire behaviors that differ from other instances of the
same class.

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.

* The action of a *__slots__* declaration is not limited to the class
  where it is defined.  *__slots__* declared in parents are available
  in child classes. However, instances of a child subclass will get a
  "__dict__" and *__weakref__* unless the subclass also defines
  *__slots__* (which should only contain names of any *additional*
  slots).

* 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.

* Une "TypeError" est levée si un *__slot__* non vide est défini pour
  une classe dérivée des "types natifs à longueur variable" tels que
  "int", "bytes" et "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()".

* "__class__" assignment works only if both classes have the same
  *__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)".

   Ajouté dans la version 3.6.

When a class is created, "type.__new__()" scans the class variables
and makes callbacks to those with a "__set_name__()" hook.

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.

   Ajouté 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)

   Si une classe mère qui apparaît dans la définition d'une classe
   n'est pas une instance de "type", alors Python cherche une méthode
   "__mro_entries__()" dans cette classe mère. S'il la trouve, au
   moment de la création de la classe, la classe mère est remplacée
   par le résultat de l'appel à "__mro_entries__()". Cette méthode est
   appelée avec le *n*-uplet des classes mères originales passé au
   paramètre *bases*. Cette méthode doit renvoyer un *n*-uplet de
   classes qui seront utilisées à la place de la classe mère. Le
   *n*-uplet renvoyé peut être vide : dans ce cas la classe mère
   originale est ignorée.

Voir aussi:

  "types.resolve_bases()"
     Résout dynamiquement les classes mères qui ne sont pas des
     instances de "type".

  "types.get_original_bases()"
     Retrieve a class's "original bases" prior to modifications by
     "__mro_entries__()".

  **PEP 560**
     Prise en charge native du module *typing* et des types génériques


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.

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.

When a new class is created by "type.__new__", the object provided as
the namespace parameter is copied to a new ordered mapping and the
original object is discarded. The new copy is wrapped in a read-only
proxy, which becomes the "__dict__" attribute of the class object.

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).

type.__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)".

type.__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
     Includes the specification for customizing "isinstance()" and
     "issubclass()" behavior through "__instancecheck__()" and
     "__subclasscheck__()", with motivation for this functionality in
     the context of adding Abstract Base Classes (see the "abc"
     module) to the language.


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*.

   When defined on a class, "__class_getitem__()" is automatically a
   class method. As such, there is no need for it to be decorated with
   "@classmethod" when it is defined.


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, la sélection 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__()", la sélection d'indices 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ù
     une sélection d'indices conduit à l'appel de
     "__class_getitem__()" au lieu de "__getitem__()"


3.3.6. Émulation d'objets appelables
------------------------------------

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

   Called when the instance is "called" as a function; if this method
   is defined, "x(arg1, arg2, ...)" roughly translates to
   "type(x).__call__(x, arg1, ...)". The "object" class itself does
   not provide this method.


3.3.7. Émulation de types conteneurs
------------------------------------

The following methods can be defined to implement container objects.
None of them are provided by the "object" class itself. 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()", "clear()",
"count()", "extend()", "index()", "insert()", "pop()", "remove()", and
"reverse()", 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.

   Ajouté 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)

   These methods are called to implement the binary arithmetic
   operations ("+", "-", "*", "@", "/", "//", "%", "divmod()",
   "pow()", "**", "<<", ">>", "&", "^", "|").  For instance, to
   evaluate the expression "x + y", where *x* is an instance of a
   class that has an "__add__()" method, "type(x).__add__(x, y)" is
   called.  The "__divmod__()" method should be the equivalent to
   using "__floordiv__()" and "__mod__()"; it should not be related to
   "__truediv__()".  Note that "__pow__()" should be defined to accept
   an optional third argument if the three-argument version of the
   built-in "pow()" function is to be supported.

   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 operands are of
   different types, when the left operand does not support the
   corresponding operation [3], or the right operand's class is
   derived from the left operand's class. [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" or
   "type(y)" is a subclass of "type(x)". [5]

   Note that "__rpow__()" should be defined to accept an optional
   third argument if the three-argument version of the built-in
   "pow()" function is to be supported.

   Modifié dans la version 3.14: Three-argument "pow()" now try
   calling "__rpow__()" if necessary. Previously it was only called in
   two-argument "pow()" and the binary power operator.

   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").

   Modifié dans la version 3.14: "int()" no longer delegates to the
   "__trunc__()" method.


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.

For more information on context managers, see Le type gestionnaire de
contexte. The "object" class itself does not provide the context
manager methods.

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".

Ajouté dans la version 3.10.

Voir aussi:

  **PEP 634** — Filtrage par motif structurel
     Spécification de l'instruction "match".


3.3.11. Emulating buffer types
------------------------------

The buffer protocol provides a way for Python objects to expose
efficient access to a low-level memory array. This protocol is
implemented by builtin types such as "bytes" and "memoryview", and
third-party libraries may define additional buffer types.

While buffer types are usually implemented in C, it is also possible
to implement the protocol in Python.

object.__buffer__(self, flags)

   Called when a buffer is requested from *self* (for example, by the
   "memoryview" constructor). The *flags* argument is an integer
   representing the kind of buffer requested, affecting for example
   whether the returned buffer is read-only or writable.
   "inspect.BufferFlags" provides a convenient way to interpret the
   flags. The method must return a "memoryview" object.

object.__release_buffer__(self, buffer)

   Called when a buffer is no longer needed. The *buffer* argument is
   a "memoryview" object that was previously returned by
   "__buffer__()". The method must release any resources associated
   with the buffer. This method should return "None". Buffer objects
   that do not need to perform any cleanup are not required to
   implement this method.

Ajouté dans la version 3.12.

Voir aussi:

  **PEP 688** - Making the buffer protocol accessible in Python
     Introduces the Python "__buffer__" and "__release_buffer__"
     methods.

  "collections.abc.Buffer"
     ABC for buffer types.


3.3.12. Annotations
-------------------

Functions, classes, and modules may contain *annotations*, which are a
way to associate information (usually *type hints*) with a symbol.

object.__annotations__

   This attribute contains the annotations for an object. It is lazily
   evaluated, so accessing the attribute may execute arbitrary code
   and raise exceptions. If evaluation is successful, the attribute is
   set to a dictionary mapping from variable names to annotations.

   Modifié dans la version 3.14: Annotations are now lazily evaluated.

object.__annotate__(format)

   An *annotate function*. Returns a new dictionary object mapping
   attribute/parameter names to their annotation values.

   Takes a format parameter specifying the format in which annotations
   values should be provided. It must be a member of the
   "annotationlib.Format" enum, or an integer with a value
   corresponding to a member of the enum.

   If an annotate function doesn't support the requested format, it
   must raise "NotImplementedError". Annotate functions must always
   support "VALUE" format; they must not raise "NotImplementedError()"
   when called with this format.

   When called with  "VALUE" format, an annotate function may raise
   "NameError"; it must not raise "NameError" when called requesting
   any other format.

   If an object does not have any annotations, "__annotate__" should
   preferably be set to "None" (it can’t be deleted), rather than set
   to a function that returns an empty dict.

   Ajouté dans la version 3.14.

Voir aussi:

  **PEP 649** --- Deferred evaluation of annotation using descriptors
     Introduces lazy evaluation of annotations and the "__annotate__"
     function.


3.3.13. 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)

   Must return an *iterator*.  Should be used to implement *awaitable*
   objects.  For instance, "asyncio.Future" implements this method to
   be compatible with the "await" expression. The "object" class
   itself is not awaitable and does not provide this method.

   Note:

     le langage n'impose aucune restriction sur le type ou la valeur
     des objets générés par l'itérateur renvoyé par "__await__", car
     cela est spécifique à l'implémentation du cadriciel d'exécution
     asynchrone (par exemple "asyncio") qui gère l'objet *awaitable*.

Ajouté 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.

   Modifié dans la version 3.12: The second signature (type[, value[,
   traceback]]) is deprecated and may be removed in a future version
   of Python.

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".

The "object" class itself does not provide these methods.

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

Ajouté 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".

The "object" class itself does not provide these methods.

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')

Ajouté dans la version 3.5.

-[ Notes ]-

[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] The "__hash__()", "__iter__()", "__reversed__()",
    "__contains__()", "__class_getitem__()" and "__fspath__()" methods
    have special handling for this. Others will still raise a
    "TypeError", but may do so by relying on the behavior that "None"
    is not callable.

[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] For operands of the same type, it is assumed that if the non-
    reflected method (such as "__add__()") fails then the operation is
    not supported, which is why the reflected method is not called.

[5] If the right operand's type is a subclass of the left operand's
    type, the reflected method having precedence allows subclasses to
    override their ancestors' operations.
