"inspect" --- Inspect live objects
**********************************

**Code source :** Lib/inspect.py

======================================================================

The "inspect" module provides several useful functions to help get
information about live objects such as modules, classes, methods,
functions, tracebacks, frame objects, and code objects.  For example,
it can help you examine the contents of a class, retrieve the source
code of a method, extract and format the argument list for a function,
or get all the information you need to display a detailed traceback.

Ce module donne accès à 4 types de services : vérification de typage,
obtention de code source, inspection de classes et de fonctions et
examen de la pile d'exécution.


Types et membres
================

The "getmembers()" function retrieves the members of an object such as
a class or module. The functions whose names begin with "is" are
mainly provided as convenient choices for the second argument to
"getmembers()". They also help you determine when you can expect to
find the following special attributes (see Import-related attributes
on module objects for module attributes):

+-------------------+---------------------+-----------------------------+
| Type              | Attribut            | Description                 |
|===================|=====================|=============================|
| classe            | __doc__             | texte de documentation      |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | nom de la classe lors de sa |
|                   |                     | définition                  |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | nom du module contenant la  |
|                   |                     | classe lors de sa           |
|                   |                     | définition                  |
+-------------------+---------------------+-----------------------------+
|                   | __type_params__     | A tuple containing the type |
|                   |                     | parameters of a generic     |
|                   |                     | class                       |
+-------------------+---------------------+-----------------------------+
| méthode           | __doc__             | texte de documentation      |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | nom de la méthode lors de   |
|                   |                     | sa définition               |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | __func__            | objet fonction contenant    |
|                   |                     | l'implémentation de la      |
|                   |                     | méthode                     |
+-------------------+---------------------+-----------------------------+
|                   | __self__            | instance à laquelle cette   |
|                   |                     | méthode est liée, ou "None" |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | nom du module contenant la  |
|                   |                     | méthode lors de sa          |
|                   |                     | définition                  |
+-------------------+---------------------+-----------------------------+
| fonction          | __doc__             | texte de documentation      |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | nom de la fonction lors de  |
|                   |                     | sa définition               |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | __code__            | objet code contenant le     |
|                   |                     | *code intermédiaire* d'une  |
|                   |                     | fonction compilée           |
+-------------------+---------------------+-----------------------------+
|                   | __defaults__        | *n*-uplet de valeurs par    |
|                   |                     | défaut pour arguments       |
|                   |                     | positionnels ou nommés      |
+-------------------+---------------------+-----------------------------+
|                   | __kwdefaults__      | tableau de correspondance   |
|                   |                     | de valeurs par défaut pour  |
|                   |                     | les paramètres nommés       |
+-------------------+---------------------+-----------------------------+
|                   | __globals__         | espace de nommage global    |
|                   |                     | lors de la définition de la |
|                   |                     | fonction                    |
+-------------------+---------------------+-----------------------------+
|                   | __builtins__        | builtins namespace          |
+-------------------+---------------------+-----------------------------+
|                   | __annotations__     | tableau de correspondance   |
|                   |                     | des paramètres à leur       |
|                   |                     | annotation ; ""return"" est |
|                   |                     | un mot-clé réservé pour les |
|                   |                     | annotations de type         |
|                   |                     | renvoyé.                    |
+-------------------+---------------------+-----------------------------+
|                   | __type_params__     | A tuple containing the type |
|                   |                     | parameters of a generic     |
|                   |                     | function                    |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | nom du module contenant la  |
|                   |                     | fonction lors de sa         |
|                   |                     | définition                  |
+-------------------+---------------------+-----------------------------+
| traceback         | tb_frame            | objet cadre à ce niveau     |
+-------------------+---------------------+-----------------------------+
|                   | tb_lasti            | index de la dernière        |
|                   |                     | instruction lancée dans le  |
|                   |                     | code intermédiaire          |
|                   |                     | ("bytecode")                |
+-------------------+---------------------+-----------------------------+
|                   | tb_lineno           | numéro de ligne courant     |
|                   |                     | dans le code source Python  |
+-------------------+---------------------+-----------------------------+
|                   | tb_next             | trace de pile interne       |
|                   |                     | suivante (appel par le      |
|                   |                     | cadre courant)              |
+-------------------+---------------------+-----------------------------+
| cadre             | f_back              | trace d'exécution externe   |
|                   |                     | suivante (le contexte       |
|                   |                     | appelant du cadre courant)  |
+-------------------+---------------------+-----------------------------+
|                   | f_builtins          | espace de nommage natif du  |
|                   |                     | cadre courant               |
+-------------------+---------------------+-----------------------------+
|                   | f_code              | objet code exécuté dans le  |
|                   |                     | cadre courant               |
+-------------------+---------------------+-----------------------------+
|                   | f_globals           | espace de nommage global    |
|                   |                     | tel que vu par cadre        |
|                   |                     | courant                     |
+-------------------+---------------------+-----------------------------+
|                   | f_lasti             | index de la dernière        |
|                   |                     | instruction lancée dans le  |
|                   |                     | code intermédiaire          |
|                   |                     | ("bytecode")                |
+-------------------+---------------------+-----------------------------+
|                   | f_lineno            | numéro de ligne courant     |
|                   |                     | dans le code source Python  |
+-------------------+---------------------+-----------------------------+
|                   | f_locals            | espace de nommage local du  |
|                   |                     | cadre courant               |
+-------------------+---------------------+-----------------------------+
|                   | f_generator         | returns the generator or    |
|                   |                     | coroutine object that owns  |
|                   |                     | this frame, or "None" if    |
|                   |                     | the frame is of a regular   |
|                   |                     | function                    |
+-------------------+---------------------+-----------------------------+
|                   | f_trace             | fonction de traçage du      |
|                   |                     | cadre courant, ou "None"    |
+-------------------+---------------------+-----------------------------+
|                   | f_trace_lines       | indicate whether a tracing  |
|                   |                     | event is triggered for each |
|                   |                     | source source line          |
+-------------------+---------------------+-----------------------------+
|                   | f_trace_opcodes     | indicate whether per-opcode |
|                   |                     | events are requested        |
+-------------------+---------------------+-----------------------------+
|                   | clear()             | used to clear all           |
|                   |                     | references to local         |
|                   |                     | variables                   |
+-------------------+---------------------+-----------------------------+
| code              | co_argcount         | nombre d'arguments          |
|                   |                     | (excluant les arguments     |
|                   |                     | *keyword-only*, * ou **)    |
+-------------------+---------------------+-----------------------------+
|                   | co_code             | texte du code intermédiaire |
|                   |                     | compilé                     |
+-------------------+---------------------+-----------------------------+
|                   | co_cellvars         | *n*-uplet du nom des        |
|                   |                     | cellules variables          |
|                   |                     | (référencées par leur       |
|                   |                     | contexte)                   |
+-------------------+---------------------+-----------------------------+
|                   | co_consts           | *n*-uplet des constantes    |
|                   |                     | utilisées dans le code      |
|                   |                     | intermédiaire ("bytecode")  |
+-------------------+---------------------+-----------------------------+
|                   | co_filename         | nom du fichier dans lequel  |
|                   |                     | cet objet code a été créé   |
+-------------------+---------------------+-----------------------------+
|                   | co_firstlineno      | numéro de la première ligne |
|                   |                     | dans le code source Python  |
+-------------------+---------------------+-----------------------------+
|                   | co_flags            | **bitmap** des options      |
|                   |                     | "CO_*", voir plus ici       |
+-------------------+---------------------+-----------------------------+
|                   | co_lnotab           | tableau de correspondance   |
|                   |                     | encodée des numéros de      |
|                   |                     | ligne aux numéros d'indices |
|                   |                     | du code intermédiaire       |
|                   |                     | ("bytecode")                |
+-------------------+---------------------+-----------------------------+
|                   | co_freevars         | *n*-uplet des noms de       |
|                   |                     | variables libres            |
|                   |                     | (référencées par la         |
|                   |                     | fermeture (*closure* en     |
|                   |                     | anglais) d'une fonction)    |
+-------------------+---------------------+-----------------------------+
|                   | co_posonlyargcount  | nombre d'arguments          |
|                   |                     | positionnels                |
+-------------------+---------------------+-----------------------------+
|                   | co_kwonlyargcount   | nombre d'arguments          |
|                   |                     | *keywords-only* (excluant   |
|                   |                     | les arguments **)           |
+-------------------+---------------------+-----------------------------+
|                   | co_name             | nom de l'objet code lors de |
|                   |                     | sa définition               |
+-------------------+---------------------+-----------------------------+
|                   | co_qualname         | fully qualified name with   |
|                   |                     | which this code object was  |
|                   |                     | defined                     |
+-------------------+---------------------+-----------------------------+
|                   | co_names            | tuple of names other than   |
|                   |                     | arguments and function      |
|                   |                     | locals                      |
+-------------------+---------------------+-----------------------------+
|                   | co_nlocals          | nombre de variables locales |
+-------------------+---------------------+-----------------------------+
|                   | co_stacksize        | espace requis pour la pile  |
|                   |                     | de la machine virtuelle     |
+-------------------+---------------------+-----------------------------+
|                   | co_varnames         | *n*-uplet des noms des      |
|                   |                     | arguments et variables      |
|                   |                     | locales                     |
+-------------------+---------------------+-----------------------------+
|                   | co_lines()          | returns an iterator that    |
|                   |                     | yields successive bytecode  |
|                   |                     | ranges                      |
+-------------------+---------------------+-----------------------------+
|                   | co_positions()      | returns an iterator of      |
|                   |                     | source code positions for   |
|                   |                     | each bytecode instruction   |
+-------------------+---------------------+-----------------------------+
|                   | replace()           | returns a copy of the code  |
|                   |                     | object with new values      |
+-------------------+---------------------+-----------------------------+
| generator         | __name__            | nom                         |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | gi_frame            | cadre                       |
+-------------------+---------------------+-----------------------------+
|                   | gi_running          | est-ce que le générateur    |
|                   |                     | est en cours d'exécution ?  |
+-------------------+---------------------+-----------------------------+
|                   | gi_suspended        | is the generator suspended? |
+-------------------+---------------------+-----------------------------+
|                   | gi_code             | code                        |
+-------------------+---------------------+-----------------------------+
|                   | gi_yieldfrom        | objet pointé par            |
|                   |                     | l'itérateur "yield from",   |
|                   |                     | ou "None"                   |
+-------------------+---------------------+-----------------------------+
| "async generator" | __name__            | nom                         |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | "cr_await"          | objet sur lequel on attend  |
|                   |                     | (*await*) présentement, ou  |
|                   |                     | "None"                      |
+-------------------+---------------------+-----------------------------+
|                   | "gi_frame"          | cadre                       |
+-------------------+---------------------+-----------------------------+
|                   | "ag_running"        | est-ce que le générateur    |
|                   |                     | est en cours d'exécution ?  |
+-------------------+---------------------+-----------------------------+
|                   | ag_suspended        | is the generator suspended? |
+-------------------+---------------------+-----------------------------+
|                   | "ag_code"           | code                        |
+-------------------+---------------------+-----------------------------+
| coroutine         | __name__            | nom                         |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | "cr_await"          | objet sur lequel on attend  |
|                   |                     | (*await*) présentement, ou  |
|                   |                     | "None"                      |
+-------------------+---------------------+-----------------------------+
|                   | "cr_frame"          | cadre                       |
+-------------------+---------------------+-----------------------------+
|                   | "cr_running"        | est-ce que la coroutine est |
|                   |                     | en cours d'exécution ?      |
+-------------------+---------------------+-----------------------------+
|                   | cr_suspended        | is the coroutine suspended? |
+-------------------+---------------------+-----------------------------+
|                   | "cr_code"           | code                        |
+-------------------+---------------------+-----------------------------+
|                   | "cr_origin"         | lieu de création de la      |
|                   |                     | coroutine, ou "None". Voir  |
|                   |                     | "sys.set_coroutine_origin_  |
|                   |                     | tracking_depth()"           |
+-------------------+---------------------+-----------------------------+
| builtin           | __doc__             | texte de documentation      |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | nom originel de cette       |
|                   |                     | fonction ou méthode         |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | nom qualifié                |
+-------------------+---------------------+-----------------------------+
|                   | __self__            | instance à laquelle est     |
|                   |                     | liée une méthode, ou "None" |
+-------------------+---------------------+-----------------------------+

Modifié dans la version 3.5: ajout des attributs "__qualname" et
"gi_yieldfrom" aux générateurs.L'attribut "__name__" du générateur est
maintenant déterminé par le nom de la fonction, plutôt que le nom du
code, et peut maintenant être modifié.

Modifié dans la version 3.7: Ajout de l'attribut "cr_origin" aux
coroutines.

Modifié dans la version 3.10: Add "__builtins__" attribute to
functions.

Modifié dans la version 3.11: Add "gi_suspended" attribute to
generators.

Modifié dans la version 3.11: Add "cr_suspended" attribute to
coroutines.

Modifié dans la version 3.12: Add "ag_suspended" attribute to async
generators.

Modifié dans la version 3.14: Add "f_generator" attribute to frames.

inspect.getmembers(object[, predicate])

   Renvoie tous les membres d'un objet sous la forme d'une liste de
   paires "(nom, valeur)", ordonnée par nom. Si l'argument *predicate*
   (qui sera appelé avec la "valeur" de chaque membre) est fourni,
   seuls les membres pour lequel le prédicat est vrai seront inclus.

   Note:

     "getmembers()" will only return class attributes defined in the
     metaclass when the argument is a class and those attributes have
     been listed in the metaclass' custom "__dir__()".

inspect.getmembers_static(object[, predicate])

   Return all the members of an object in a list of "(name, value)"
   pairs sorted by name without triggering dynamic lookup via the
   descriptor protocol, __getattr__ or __getattribute__. Optionally,
   only return members that satisfy a given predicate.

   Note:

     "getmembers_static()" may not be able to retrieve all members
     that getmembers can fetch (like dynamically created attributes)
     and may find members that getmembers can't (like descriptors that
     raise AttributeError). It can also return descriptor objects
     instead of instance members in some cases.

   Ajouté dans la version 3.11.

inspect.getmodulename(path)

   Renvoie le nom du module indiqué par le fichier *path*, excluant le
   nom des paquets englobants. L'extension du fichier est vérifiée
   parmi toutes les entrées renvoyées par
   "importlib.machinery.all_suffixes()". S'il y a une correspondance,
   le chemin final est renvoyé, sans l'extension. Autrement, "None"
   est renvoyé.

   Notez que cette fonction renvoie un nom significatif *seulement*
   pour les modules Python - les chemins qui réfèrent à des paquets
   Python donnent toujours "None".

   Modifié dans la version 3.3: La fonction est basée directement sur
   "importlib".

inspect.ismodule(object)

   Renvoie "True" si l'objet est un module.

inspect.isclass(object)

   Renvoie "True" si l'objet est une classe, qu'il s'agisse d'un objet
   natif ou qu'elle soit écrite en Python.

inspect.ismethod(object)

   Renvoie "True" si l'objet est une méthode liée écrite en Python.

inspect.ispackage(object)

   Return "True" if the object is a *package*.

   Ajouté dans la version 3.14.

inspect.isfunction(object)

   Renvoie "True" si l'objet est une fonction Python, ce qui inclut
   les fonctions créées par une expression *lambda*.

inspect.isgeneratorfunction(object)

   Renvoie "True" si l'objet est un générateur.

   Modifié dans la version 3.8: les fonctions englobées dans
   "functools.partial()" renvoient maintenant "True" si la fonction
   englobée est un générateur Python.

   Modifié dans la version 3.13: Functions wrapped in
   "functools.partialmethod()" now return "True" if the wrapped
   function is a Python generator function.

inspect.isgenerator(object)

   Renvoie "True" si l'objet est un générateur.

inspect.iscoroutinefunction(object)

   Return "True" if the object is a *coroutine function* (a function
   defined with an "async def" syntax), a "functools.partial()"
   wrapping a *coroutine function*, or a sync function marked with
   "markcoroutinefunction()".

   Ajouté dans la version 3.5.

   Modifié dans la version 3.8: les fonctions englobées par
   "functools.partial()" renvoient maintenant "True" si la fonction
   englobée est une *coroutine*.

   Modifié dans la version 3.12: Sync functions marked with
   "markcoroutinefunction()" now return "True".

   Modifié dans la version 3.13: Functions wrapped in
   "functools.partialmethod()" now return "True" if the wrapped
   function is a *coroutine function*.

inspect.markcoroutinefunction(func)

   Decorator to mark a callable as a *coroutine function* if it would
   not otherwise be detected by "iscoroutinefunction()".

   This may be of use for sync functions that return a *coroutine*, if
   the function is passed to an API that requires
   "iscoroutinefunction()".

   When possible, using an "async def" function is preferred. Also
   acceptable is calling the function and testing the return with
   "iscoroutine()".

   Ajouté dans la version 3.12.

inspect.iscoroutine(object)

   Renvoie "True" si l'objet est une *coroutine* créée par une
   fonction "async def".

   Ajouté dans la version 3.5.

inspect.isawaitable(object)

   Renvoie "True" si l'objet peut être utilisé par une expression
   "await".

   Can also be used to distinguish generator-based coroutines from
   regular generators:

      import types

      def gen():
          yield
      @types.coroutine
      def gen_coro():
          yield

      assert not isawaitable(gen())
      assert isawaitable(gen_coro())

   Ajouté dans la version 3.5.

inspect.isasyncgenfunction(object)

   Return "True" if the object is an *asynchronous generator*
   function, for example:

      >>> async def agen():
      ...     yield 1
      ...
      >>> inspect.isasyncgenfunction(agen)
      True

   Ajouté dans la version 3.6.

   Modifié dans la version 3.8: Functions wrapped in
   "functools.partial()" now return "True" if the wrapped function is
   an *asynchronous generator* function.

   Modifié dans la version 3.13: Functions wrapped in
   "functools.partialmethod()" now return "True" if the wrapped
   function is a *asynchronous generator* function.

inspect.isasyncgen(object)

   Renvoie "True" si l'objet est un *itérateur de générateur
   asynchrone* créé par une fonction *génératrice asynchrone*.

   Ajouté dans la version 3.6.

inspect.istraceback(object)

   Renvoie "True" si l'objet est une trace d'exécution.

inspect.isframe(object)

   Renvoie "True" si l'objet est un cadre.

inspect.iscode(object)

   Renvoie "True" si l'objet est un code.

inspect.isbuiltin(object)

   Renvoie "True" si l'objet est une fonction native ou une méthode
   liée native.

inspect.ismethodwrapper(object)

   Return "True" if the type of object is a "MethodWrapperType".

   These are instances of "MethodWrapperType", such as "__str__()",
   "__eq__()" and "__repr__()".

   Ajouté dans la version 3.11.

inspect.isroutine(object)

   Renvoie "True" si l'objet est une fonction, qu'elle soit définie
   par l'utilisateur, native, ou une méthode.

inspect.isabstract(object)

   Renvoie "True" si l'objet est une classe de base abstraite.

inspect.ismethoddescriptor(object)

   Renvoie "True" si l'objet est un descripteur de méthode sauf si
   "ismethod()", "isclass()", "isfunction()" ou "isbuiltin()" sont
   vrais ("True").

   This, for example, is true of "int.__add__".  An object passing
   this test has a "__get__()" method, but not a "__set__()" method or
   a "__delete__()" method.  Beyond that, the set of attributes
   varies.  A "__name__" attribute is usually sensible, and "__doc__"
   often is.

   Methods implemented via descriptors that also pass one of the other
   tests return "False" from the "ismethoddescriptor()" test, simply
   because the other tests promise more -- you can, e.g., count on
   having the "__func__" attribute (etc) when an object passes
   "ismethod()".

   Modifié dans la version 3.13: This function no longer incorrectly
   reports objects with "__get__()" and "__delete__()", but not
   "__set__()", as being method descriptors (such objects are data
   descriptors, not method descriptors).

inspect.isdatadescriptor(object)

   Renvoie "True" si l'objet est un descripteur de données.

   Data descriptors have a "__set__" or a "__delete__" method.
   Examples are properties (defined in Python), getsets, and members.
   The latter two are defined in C and there are more specific tests
   available for those types, which is robust across Python
   implementations.  Typically, data descriptors will also have
   "__name__" and "__doc__" attributes (properties, getsets, and
   members have both of these attributes), but this is not guaranteed.

inspect.isgetsetdescriptor(object)

   Renvoie "True" si l'objet est un descripteur *getset*.

   *getsets* sont des attributs définis dans des extensions de modules
   via des structures "PyGetSetDef". Pour les implémentations Python
   ne possédant pas ces types, cette méthode renvoie toujours "False".

inspect.ismemberdescriptor(object)

   Renvoie "True" si l'objet est un membre descripteur.

   Les membres descripteurs sont des attributs définis dans des
   extensions de modules via des structures "PyMemberDef". Pour les
   implémentations Python ne possédant pas ces types, cette méthode
   renvoie toujours "False".


Récupération du code source
===========================

inspect.getdoc(object)

   Get the documentation string for an object, cleaned up with
   "cleandoc()". If the documentation string for an object is not
   provided and the object is a class, a method, a property or a
   descriptor, retrieve the documentation string from the inheritance
   hierarchy. Return "None" if the documentation string is invalid or
   missing.

   Modifié dans la version 3.5: les chaînes de documentation sont
   maintenant héritées si elles ne sont pas surchargées.

inspect.getcomments(object)

   Renvoie en une chaîne de caractères toute ligne de commentaire qui
   précède immédiatement le code source de l'objet (pour une classe,
   fonction ou méthode) ou en début d'un fichier de code source Python
   (si l'objet est un module). Si le code source de l'objet n'est pas
   disponible, renvoie "None". Cela peut se produire si l'objet a été
   défini en C ou dans un interpréteur interactif.

inspect.getfile(object)

   Renvoie le nom du fichier (texte ou binaire) dans lequel un objet a
   été défini. Cette méthode échoue avec "TypeError" si l'objet est un
   module, une classe ou une fonction native.

inspect.getmodule(object)

   Try to guess which module an object was defined in. Return "None"
   if the module cannot be determined.

inspect.getsourcefile(object)

   Return the name of the Python source file in which an object was
   defined or "None" if no way can be identified to get the source.
   This will fail with a "TypeError" if the object is a built-in
   module, class, or function.

inspect.getsourcelines(object)

   Return a list of source lines and starting line number for an
   object. The argument may be a module, class, method, function,
   traceback, frame, or code object.  The source code is returned as a
   list of the lines corresponding to the object and the line number
   indicates where in the original source file the first line of code
   was found.  An "OSError" is raised if the source code cannot be
   retrieved. A "TypeError" is raised if the object is a built-in
   module, class, or function.

   Modifié dans la version 3.3: "OSError" est levé plutôt que
   "IOError", qui est maintenant un alias de ce premier.

inspect.getsource(object)

   Return the text of the source code for an object. The argument may
   be a module, class, method, function, traceback, frame, or code
   object.  The source code is returned as a single string.  An
   "OSError" is raised if the source code cannot be retrieved. A
   "TypeError" is raised if the object is a built-in module, class, or
   function.

   Modifié dans la version 3.3: "OSError" est levé plutôt que
   "IOError", qui est maintenant un alias de ce premier.

inspect.cleandoc(doc)

   Nettoie les indentations des chaînes de documentation qui sont
   indentées de manières à s'aligner avec les blocs de code.

   Enlève tous les espaces blancs en début de ligne à partir de la
   première. Tout espace blanc en début de ligne qui puisse être
   enlevé de manière uniforme à partir de la seconde ligne le sera.
   Les lignes vides en début et en fin de document seront ensuite
   enlevées. Les tabulations seront converties en espaces.


Introspection des appelables avec l'objet Signature
===================================================

Ajouté dans la version 3.3.

The "Signature" object represents the call signature of a callable
object and its return annotation. To retrieve a "Signature" object,
use the "signature()" function.

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)

   Return a "Signature" object for the given *callable*:

      >>> from inspect import signature
      >>> def foo(a, *, b:int, **kwargs):
      ...     pass

      >>> sig = signature(foo)

      >>> str(sig)
      '(a, *, b: int, **kwargs)'

      >>> str(sig.parameters['b'])
      'b: int'

      >>> sig.parameters['b'].annotation
      <class 'int'>

   La fonction accepte une grande étendue d'appelables Python, des
   fonctions et classes jusqu'aux objets "functools.partials()".

   If some of the annotations are strings (e.g., because "from
   __future__ import annotations" was used), "signature()" will
   attempt to automatically un-stringize the annotations using
   "annotationlib.get_annotations()".  The *globals*, *locals*, and
   *eval_str* parameters are passed into
   "annotationlib.get_annotations()" when resolving the annotations;
   see the documentation for "annotationlib.get_annotations()" for
   instructions on how to use these parameters. A member of the
   "annotationlib.Format" enum can be passed to the
   *annotation_format* parameter to control the format of the returned
   annotations. For example, use
   "annotation_format=annotationlib.Format.STRING" to return
   annotations in string format.

   Raises "ValueError" if no signature can be provided, and
   "TypeError" if that type of object is not supported.  Also, if the
   annotations are stringized, and *eval_str* is not false, the
   "eval()" call(s) to un-stringize the annotations in
   "annotationlib.get_annotations()" could potentially raise any kind
   of exception.

   A slash (/) in the signature of a function denotes that the
   parameters prior to it are positional-only. For more info, see the
   FAQ entry on positional-only parameters.

   Modifié dans la version 3.5: The *follow_wrapped* parameter was
   added. Pass "False" to get a signature of *callable* specifically
   ("callable.__wrapped__" will not be used to unwrap decorated
   callables.)

   Modifié dans la version 3.10: The *globals*, *locals*, and
   *eval_str* parameters were added.

   Modifié dans la version 3.14: The *annotation_format* parameter was
   added.

   Note:

     Certains appelables ne peuvent bénéficier d'introspection dans
     certains environnements Python. Par exemple, en CPython,
     certaines fonctions natives définies en C ne fournissent aucune
     métadonnée sur leurs arguments.

   **Particularité de l'implémentation CPython :** If the passed
   object has a "__signature__" attribute, we may use it to create the
   signature. The exact semantics are an implementation detail and are
   subject to unannounced changes. Consult the source code for current
   semantics.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

   A "Signature" object represents the call signature of a function
   and its return annotation.  For each parameter accepted by the
   function it stores a "Parameter" object in its "parameters"
   collection.

   L'argument optionnel *parameters* est une séquence d'objets
   "Parameters", qui permet de vérifier qu'il n'y a pas de duplication
   de noms de paramètres, que les paramètres sont dans le bon ordre
   (positionnels d'abord, positionnels ou nommés ensuite et que les
   paramètres avec valeurs par défaut sont placés après ceux qui n'en
   ont pas).

   The optional *return_annotation* argument can be an arbitrary
   Python object. It represents the "return" annotation of the
   callable.

   "Signature" objects are *immutable*.  Use "Signature.replace()" or
   "copy.replace()" to make a modified copy.

   Modifié dans la version 3.5: "Signature" objects are now picklable
   and *hashable*.

   empty

      Un marqueur spécial, accessible via "Signature.empty", indiquant
      l'absence d'une annotation de type renvoyé.

   parameters

      Une table de correspondance ordonnée des noms de paramètres avec
      les objets "Parameter". Les paramètres apparaissent dans l'ordre
      strict de leur définition, incluant les paramètres exclusivement
      nommés.

      Modifié dans la version 3.7: Python ne garantit explicitement la
      préservation de l'ordre des paramètres exclusivement nommés que
      depuis la version 3.7, bien qu'en pratique cet ordre a toujours
      été préservé sous Python 3.

   return_annotation

      L'annotation du type renvoyé par l'appelable. Si l'appelable n'a
      pas d'annotation de type, cet attribut est évalué à
      "Signature.empty".

   bind(*args, **kwargs)

      Crée une table de correspondance entre les arguments
      positionnels et nommés avec les paramètres. Renvoie
      "BoundArguments" si "*args" et "**kwargs" concordent avec la
      signature, autrement lève une "TypeError".

   bind_partial(*args, **kwargs)

      Fonctionne de manière similaire à "Signature.bind()", mais
      permet l'omission de certains arguments (semblable au
      comportement de "functools.partial()"). Renvoie
      "BoundArguments", ou lève une "TypeError" si l'argument passé ne
      correspond pas à la signature.

   replace(*[, parameters][, return_annotation])

      Create a new "Signature" instance based on the instance
      "replace()" was invoked on. It is possible to pass different
      *parameters* and/or *return_annotation* to override the
      corresponding properties of the base signature.  To remove
      "return_annotation" from the copied "Signature", pass in
      "Signature.empty".

         >>> def test(a, b):
         ...     pass
         ...
         >>> sig = signature(test)
         >>> new_sig = sig.replace(return_annotation="new return anno")
         >>> str(new_sig)
         "(a, b) -> 'new return anno'"

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

   format(*, max_width=None, quote_annotation_strings=True)

      Create a string representation of the "Signature" object.

      If *max_width* is passed, the method will attempt to fit the
      signature into lines of at most *max_width* characters. If the
      signature is longer than *max_width*, all parameters will be on
      separate lines.

      If *quote_annotation_strings* is False, *annotations* in the
      signature are displayed without opening and closing quotation
      marks if they are strings. This is useful if the signature was
      created with the "STRING" format or if "from __future__ import
      annotations" was used.

      Ajouté dans la version 3.13.

      Modifié dans la version 3.14: The *unquote_annotations*
      parameter was added.

   classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

      Return a "Signature" (or its subclass) object for a given
      callable *obj*.

      This method simplifies subclassing of "Signature":

         class MySignature(Signature):
             pass
         sig = MySignature.from_callable(sum)
         assert isinstance(sig, MySignature)

      Its behavior is otherwise identical to that of "signature()".

      Ajouté dans la version 3.5.

      Modifié dans la version 3.10: The *globals*, *locals*, and
      *eval_str* parameters were added.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

   "Parameter" objects are *immutable*. Instead of modifying a
   "Parameter" object, you can use "Parameter.replace()" or
   "copy.replace()" to create a modified copy.

   Modifié dans la version 3.5: Parameter objects are now picklable
   and *hashable*.

   empty

      Un marqueur spécial, accessible via "Parameters.empty" indiquant
      l'absence de valeurs par défaut et d'annotations.

   name

      Le nom du paramètre (chaîne de caractères). Le nom doit être un
      identifiant Python valide.

      CPython génère un nom de paramètre implicite de forme ".0" sur
      les objets de code utilisés pour implémenter les compréhensions
      et expressions génératrices.

      Modifié dans la version 3.6: These parameter names are now
      exposed by this module as names like "implicit0".

   default

      La valeur par défaut de ce paramètre. Si le paramètre n'a pas de
      valeur par défaut, cet attribut vaut "Parameter.empty".

   annotation

      L'annotation du paramètre. Si le paramètre n'a pas d'annotation,
      cet attribut est défini à "Parameter.empty".

   kind

      Describes how argument values are bound to the parameter.  The
      possible values are accessible via "Parameter" (like
      "Parameter.KEYWORD_ONLY"), and support comparison and ordering,
      in the following order:

      +--------------------------+------------------------------------------------+
      | Nom                      | Signification                                  |
      |==========================|================================================|
      | *POSITIONAL_ONLY*        | La valeur doit être donnée comme argument      |
      |                          | positionnel. Les arguments exclusivement       |
      |                          | positionnels sont ceux qui apparaissent avant  |
      |                          | une entrée "/" (si présente) dans une          |
      |                          | définition de fonction Python.                 |
      +--------------------------+------------------------------------------------+
      | *POSITIONAL_OR_KEYWORD*  | La valeur peut être donnée comme argument      |
      |                          | nommé ou positionnel (ce qui est l'affectation |
      |                          | de variable standard pour les fonctions        |
      |                          | implémentées en Python).                       |
      +--------------------------+------------------------------------------------+
      | *VAR_POSITIONAL*         | Un *n*-uplet d'arguments positionnels qui ne   |
      |                          | sont affectés à aucun autre paramètre. Cela    |
      |                          | correspond à un paramètre "*args" dans une     |
      |                          | définition de fonction Python.                 |
      +--------------------------+------------------------------------------------+
      | *KEYWORD_ONLY*           | La valeur doit être donnée comme argument      |
      |                          | nommé. Les arguments exclusivement nommés sont |
      |                          | ceux qui apparaissent après un "*" ou "*args"  |
      |                          | dans une définition de fonction Python.        |
      +--------------------------+------------------------------------------------+
      | *VAR_KEYWORD*            | Un dictionnaire d'arguments nommés qui ne sont |
      |                          | liés à aucun autre paramètre. Cela correspond  |
      |                          | à une expression "**kwargs" dans une           |
      |                          | définition de fonction Python.                 |
      +--------------------------+------------------------------------------------+

      Example: print all keyword-only arguments without default
      values:

         >>> def foo(a, b, *, c, d=10):
         ...     pass

         >>> sig = signature(foo)
         >>> for param in sig.parameters.values():
         ...     if (param.kind == param.KEYWORD_ONLY and
         ...                        param.default is param.empty):
         ...         print('Parameter:', param)
         Parameter: c

   kind.description

      Describes an enum value of "Parameter.kind".

      Ajouté dans la version 3.8.

      Example: print all descriptions of arguments:

         >>> def foo(a, b, *, c, d=10):
         ...     pass

         >>> sig = signature(foo)
         >>> for param in sig.parameters.values():
         ...     print(param.kind.description)
         positional or keyword
         positional or keyword
         keyword-only
         keyword-only

   replace(*[, name][, kind][, default][, annotation])

      Create a new "Parameter" instance based on the instance replaced
      was invoked on.  To override a "Parameter" attribute, pass the
      corresponding argument.  To remove a default value or/and an
      annotation from a "Parameter", pass "Parameter.empty".

         >>> from inspect import Parameter
         >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
         >>> str(param)
         'foo=42'

         >>> str(param.replace()) # Will create a shallow copy of 'param'
         'foo=42'

         >>> str(param.replace(default=Parameter.empty, annotation='spam'))
         "foo: 'spam'"

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

   Modifié dans la version 3.4: In Python 3.3 "Parameter" objects were
   allowed to have "name" set to "None" if their "kind" was set to
   "POSITIONAL_ONLY". This is no longer permitted.

class inspect.BoundArguments

   Le résultat d'un appel à "Signature.bind()" ou
   "Signature.bind_partial()". Contient la correspondance entre les
   arguments et les paramètres de la fonction.

   arguments

      Une correspondance mutable entre les noms de paramètres et les
      valeurs des arguments. Contient seulement les arguments liés
      explicitement. Les changements dans "arguments" sont reflétés
      dans "args" et "kwargs".

      Doit être utilisé en combinaison avec "Signature.parameters"
      pour le traitement d'arguments.

      Note:

        Les arguments pour lesquels "Signature.bind()" ou
        "Signature.bind_partial()" supposent une valeur par défaut
        sont ignorés. Au besoin, utiliser
        "BoundArguments.apply_defaults()" pour les inclure.

      Modifié dans la version 3.9: "arguments" est maintenant de type
      "dict". Anciennement, il était de type
      "collections.OrderedDict".

   args

      Un *n*-uplets des valeurs d'arguments positionnels. Évalué
      dynamiquement à partir de l'attribut "arguments".

   kwargs

      A dict of keyword arguments values.  Dynamically computed from
      the "arguments" attribute.  Arguments that can be passed
      positionally are included in "args" instead.

   signature

      Une référence à l'objet "Signature" de la classe parente.

   apply_defaults()

      Assigne les valeurs par défaut pour les arguments manquants.

      Pour les arguments positionnels variables ("*args") la valeur
      par défaut est un *n*-uplet vide.

      Pour les arguments nommés variables ("**kwargs") la valeur par
      défaut est un dictionnaire vide.

         >>> def foo(a, b='ham', *args): pass
         >>> ba = inspect.signature(foo).bind('spam')
         >>> ba.apply_defaults()
         >>> ba.arguments
         {'a': 'spam', 'b': 'ham', 'args': ()}

      Ajouté dans la version 3.5.

   The "args" and "kwargs" properties can be used to invoke functions:

      def test(a, *, b):
          ...

      sig = signature(test)
      ba = sig.bind(10, b=20)
      test(*ba.args, **ba.kwargs)

Voir aussi:

  **PEP 362** — *Function Signature Object*.
     La spécification détaillée, détails d'implémentation et exemples.


Classes et fonctions
====================

inspect.getclasstree(classes, unique=False)

   Organise la liste de classes donnée en une hiérarchie de listes
   imbriquées. Lorsqu'une liste imbriquée apparaît, elle contient les
   classes dérivées de la classe dont l'entrée précède immédiatement
   cette liste. Chaque entrée est une paire contenant la classe et un
   *n*-uplet de ses classes de base. Si l'argument *unique* est vrai,
   exactement une entrée apparaît dans la structure renvoyée pour
   chaque classe de la liste donnée en argument. Autrement, les
   classes utilisant l'héritage multiple et ses descendantes
   apparaissent plusieurs fois.

inspect.getfullargspec(func)

   Obtenir les noms et les valeurs par défaut des paramètres de
   fonction Python. Un *n-uplet nommé* est renvoyé :

   "FullArgSpec(args, varargs, varkw, defaults, kwonlyargs,
   kwonlydefaults, annotations)"

   *args* est une liste de noms de paramètres positionnels. *varargs*
   est le nom du paramètre "*" ou "None" si les arguments positionnels
   arbitraires ne sont pas acceptés. *varkw* est le nom du paramètre
   "**", ou "None" si les paramètres arbitraires nommés ne sont pas
   acceptés. *defaults* est un *n*-uplet des valeurs des arguments par
   défaut correspondant aux derniers *n* arguments positionnels, ou
   "None" si aucun défaut n'est défini. *kwonlyargs* est une liste
   d'arguments exclusivement nommés, ordonnée selon l'ordre de
   déclaration. *kwonlydefaults* est un dictionnaire de correspondance
   entre les noms de paramètres de *kwonlyargs* et les valeurs par
   défaut utilisées si aucun argument n'est donné. *annotations* est
   un dictionnaire de correspondance entre les noms de paramètres et
   les annotations. La clef spéciale ""return"" est utilisée pour
   obtenir la valeur de retour de l'annotation la fonction (si elle
   existe).

   Notez que "signature()" et Signature Object fournissent l'API
   recommandé pour l’introspection d'appelables et prennent en charge
   des comportements additionnels (comme les arguments exclusivement
   positionnels) qui sont parfois rencontrés dans les APIs des modules
   d'extension. Cette fonction et maintenue principalement pour
   maintenir la compatibilité avec l'API du module "inspect" de Python
   2.

   Modifié dans la version 3.4: cette fonction est maintenant basée
   sur "signature()", mais ignore toujours les attributs "_wrapped_"
   et inclue le premier paramètre (déjà lié) dans la signature des
   méthodes liées.

   Modifié dans la version 3.6: This method was previously documented
   as deprecated in favour of "signature()" in Python 3.5, but that
   decision has been reversed in order to restore a clearly supported
   standard interface for single-source Python 2/3 code migrating away
   from the legacy "getargspec()" API.

   Modifié dans la version 3.7: Python ne garantit explicitement la
   préservation de l'ordre des paramètres exclusivement nommés que
   depuis la version 3.7, bien qu'en pratique cet ordre a toujours été
   préservé sous Python 3.

inspect.getargvalues(frame)

   Obtenir de l'information sur les arguments passés à un cadre
   particulier. Un *n-uplet nommé* "ArgInfo(args, varargs, keywords,
   locals)" est renvoyé. *args* est une liste de noms d'arguments.
   *varags* et *keywords* sont les noms des arguments "*" et "**" ou
   "None". *locals* est le dictionnaire des variables locales du cadre
   courant.

   Note:

     Cette fonction fût dépréciée par inadvertance en Python 3.5.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

   Formatage lisible des quatre valeurs renvoyées par
   "getargvalues()". Les arguments format* sont des fonctions de
   formatage optionnelles qui sont appelées pour convertir les noms et
   valeurs en chaînes de caractères.

   Note:

     Cette fonction fût dépréciée par inadvertance en Python 3.5.

inspect.getmro(cls)

   Renvoie un *n*-uplet des classes de base de *cls*, incluant *cls*,
   selon le l'ordre de résolution des méthodes (*method resolution
   order*). Aucune classe n'apparaît plus d'une fois dans ce
   *n*-uplet. Notez que le l'ordre de résolution des méthodes dépend
   du type de *cls*. Exception faite d'une utilisation très
   particulière de la métaclasse définie par l'usager, *cls* sera
   toujours le premier élément du tuple.

inspect.getcallargs(func, /, *args, **kwds)

   Bind the *args* and *kwds* to the argument names of the Python
   function or method *func*, as if it was called with them. For bound
   methods, bind also the first argument (typically named "self") to
   the associated instance. A dict is returned, mapping the argument
   names (including the names of the "*" and "**" arguments, if any)
   to their values from *args* and *kwds*. In case of invoking *func*
   incorrectly, i.e. whenever "func(*args, **kwds)" would raise an
   exception because of incompatible signature, an exception of the
   same type and the same or similar message is raised. For example:

      >>> from inspect import getcallargs
      >>> def f(a, b=1, *pos, **named):
      ...     pass
      ...
      >>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
      True
      >>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
      True
      >>> getcallargs(f)
      Traceback (most recent call last):
      ...
      TypeError: f() missing 1 required positional argument: 'a'

   Ajouté dans la version 3.2.

   Obsolète depuis la version 3.5: utilisez plutôt "Signature.bind()"
   et "Signature.bind_partial()".

inspect.getclosurevars(func)

   Obtenir la correspondance de nom de références externes d'une
   fonction ou méthode Python *func* avec leur valeur courante. Un
   *n-uplet nommé* "ClosureVars(nonlocals, globals, builtins,
   unbound)" est renvoyé. *nonlocals* établit une correspondance des
   noms capturés par les fermetures lexicales, *globals* au module de
   la fonction et *builtins* aux noms natifs visibles depuis le corps
   de la fonction. *unbound* est un ensemble de noms référencés dans
   la fonction ne trouvant aucune résolution dans les valeurs globales
   du module courant ni à travers le lexique natif.

   "TypeError" est levée si *func* n'est ni une fonction ni une
   méthode Python.

   Ajouté dans la version 3.3.

inspect.unwrap(func, *, stop=None)

   Obtenir l'objet englobé par *func*. Suit une chaîne d'attributs de
   "__wrapped__", renvoyant le dernier objet de la chaîne.

   *stop* est une fonction de *callback* optionnelle qui accepte un
   objet de la chaîne englobée comme son seul argument et permet
   d'arrêter le déballage avant la fin si la fonction de *callback*
   renvoie une valeur vraie. Si la fonction *callback* ne renvoie
   jamais une valeur vraie, le dernier objet de la chaîne est renvoyé
   comme d'habitude. Par exemple, "signature()" utilise ceci pour
   arrêter le déballage si un objet dans la chaîne définit un attribut
   "__signature__".

   "ValueError" est levée si un cycle est rencontré.

   Ajouté dans la version 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)

   Compute the annotations dict for an object.

   This is an alias for "annotationlib.get_annotations()"; see the
   documentation of that function for more information.

   Prudence:

     This function may execute arbitrary code contained in
     annotations. See Security implications of introspecting
     annotations for more information.

   Ajouté dans la version 3.10.

   Modifié dans la version 3.14: This function is now an alias for
   "annotationlib.get_annotations()". Calling it as
   "inspect.get_annotations" will continue to work.


La pile d'interpréteur
======================

Some of the following functions return "FrameInfo" objects. For
backwards compatibility these objects allow tuple-like operations on
all attributes except "positions". This behavior is considered
deprecated and may be removed in the future.

class inspect.FrameInfo

   frame

      The frame object that the record corresponds to.

   filename

      The file name associated with the code being executed by the
      frame this record corresponds to.

   lineno

      The line number of the current line associated with the code
      being executed by the frame this record corresponds to.

   function

      The function name that is being executed by the frame this
      record corresponds to.

   code_context

      A list of lines of context from the source code that's being
      executed by the frame this record corresponds to.

   index

      The index of the current line being executed in the
      "code_context" list.

   positions

      A "dis.Positions" object containing the start line number, end
      line number, start column offset, and end column offset
      associated with the instruction being executed by the frame this
      record corresponds to.

   Modifié dans la version 3.5: Return a *named tuple* instead of a
   "tuple".

   Modifié dans la version 3.11: "FrameInfo" is now a class instance
   (that is backwards compatible with the previous *named tuple*).

class inspect.Traceback

   filename

      The file name associated with the code being executed by the
      frame this traceback corresponds to.

   lineno

      The line number of the current line associated with the code
      being executed by the frame this traceback corresponds to.

   function

      The function name that is being executed by the frame this
      traceback corresponds to.

   code_context

      A list of lines of context from the source code that's being
      executed by the frame this traceback corresponds to.

   index

      The index of the current line being executed in the
      "code_context" list.

   positions

      A "dis.Positions" object containing the start line number, end
      line number, start column offset, and end column offset
      associated with the instruction being executed by the frame this
      traceback corresponds to.

   Modifié dans la version 3.11: "Traceback" is now a class instance
   (that is backwards compatible with the previous *named tuple*).

Note:

  Conserver des références à des objets cadre, tel que trouvé dans le
  1er élément des enregistrements de cadres que ces fonctions
  renvoient, peut créer des cycles de référence dans votre programme.
  Lorsqu'un cycle de référence a été créé, la durée de vie de tous les
  objets pouvant être accessibles par ces objets peut être grandement
  augmentée, même si le détecteur de cycle (optionnel) de Python est
  activé. Si ces cycles doivent être créés, il est important de
  s'assurer qu'ils soient explicitement brisés pour éviter la
  destruction reportée des objets et l'augmentation résultante de
  l'utilisation de la mémoire.Bien que le détecteur trouvera ces
  cycles, la destruction des cadres (et variables locales) peut être
  fait de manière déterministe en enlevant les cycles dans une clause
  "finally". Cela est important si le détecteur de cycle a été
  désactivé lors de la compilation du code Python ou en utilisant
  "gc.disable()". Par exemple :

     def handle_stackframe_without_leak():
         frame = inspect.currentframe()
         try:
             # do something with the frame
         finally:
             del frame

  Pour conserver ces cadres (par exemple pour imprimer une trace
  d'exécution plus tard), vous pouvez briser ces cycles de référence
  en utilisant la méthode "frame.clear()".

L'argument optionnel *context* supporté par la plupart de ces méthodes
spécifie le nombre de lignes de contexte à renvoyer, qui sera centré
autour de la ligne courante.

inspect.getframeinfo(frame, context=1)

   Get information about a frame or traceback object.  A "Traceback"
   object is returned.

   Modifié dans la version 3.11: A "Traceback" object is returned
   instead of a named tuple.

inspect.getouterframes(frame, context=1)

   Get a list of "FrameInfo" objects for a frame and all outer frames.
   These frames represent the calls that lead to the creation of
   *frame*. The first entry in the returned list represents *frame*;
   the last entry represents the outermost call on *frame*'s stack.

   Modifié dans la version 3.5: une liste de *n-uplet nommé*
   "FrameInfo(frame, filename, lineno, function, code_context, index)"
   est renvoyée.

   Modifié dans la version 3.11: A list of "FrameInfo" objects is
   returned.

inspect.getinnerframes(traceback, context=1)

   Get a list of "FrameInfo" objects for a traceback's frame and all
   inner frames.  These frames represent calls made as a consequence
   of *frame*. The first entry in the list represents *traceback*; the
   last entry represents where the exception was raised.

   Modifié dans la version 3.5: une liste de *n-uplet nommé*
   "FrameInfo(frame, filename, lineno, function, code_context, index)"
   est renvoyée.

   Modifié dans la version 3.11: A list of "FrameInfo" objects is
   returned.

inspect.currentframe()

   Renvoie l'objet cadre de la pile pour le cadre de l’appelant.

   cette fonction nécessite que l'interpréteur Python implémente une
   pile de cadres d'appel, ce qui n'est pas forcément le cas de toutes
   les implémentations Python. Si le code s'exécute dans une
   implémentation Python n'implémentant pas la pile de cadres, cette
   fonction renvoie "None".

inspect.stack(context=1)

   Return a list of "FrameInfo" objects for the caller's stack.  The
   first entry in the returned list represents the caller; the last
   entry represents the outermost call on the stack.

   Modifié dans la version 3.5: une liste de *n-uplet nommé*
   "FrameInfo(frame, filename, lineno, function, code_context, index)"
   est renvoyée.

   Modifié dans la version 3.11: A list of "FrameInfo" objects is
   returned.

inspect.trace(context=1)

   Return a list of "FrameInfo" objects for the stack between the
   current frame and the frame in which an exception currently being
   handled was raised in.  The first entry in the list represents the
   caller; the last entry represents where the exception was raised.

   Modifié dans la version 3.5: une liste de *n-uplet nommé*
   "FrameInfo(frame, filename, lineno, function, code_context, index)"
   est renvoyée.

   Modifié dans la version 3.11: A list of "FrameInfo" objects is
   returned.


Recherche dynamique d'attributs
===============================

Both "getattr()" and "hasattr()" can trigger code execution when
fetching or checking for the existence of attributes. Descriptors,
like properties, will be invoked and "__getattr__()" and
"__getattribute__()" may be called.

Pour les cas où une introspection passive est désirée, comme des
outils de documentation, cela peut être inconvenable.
"getattr_static()" possède la même signature que "getattr()", mais
évite l'exécution de code lors de la recherche d'attributs.

inspect.getattr_static(obj, attr, default=None)

   Retrieve attributes without triggering dynamic lookup via the
   descriptor protocol, "__getattr__()" or "__getattribute__()".

   Note : cette fonction ne retrouve pas forcément tous les attributs
   renvoyés par *getattr* (tel que des attributs générés
   dynamiquement) et pourrait retrouver des attributs non retrouvés
   par *getattr* (tel que des descripteurs qui lèvent un
   *AttributeError*). Elle peut aussi donner des objets descripteurs,
   plutôt que des membres d'instance.

   Si l'instance "__dict__" est cachée (*shadowed*) par un autre
   membre (par exemple une propriété), cette fonction ne pourra pas
   retrouver les membres de l'instance.

   Ajouté dans la version 3.2.

"getattr_static()" ne résout pas les descripteurs, par exemple *slot
descriptors* ou les descripteurs *getset* des objets implémentés en C.
Le descripteur de l'objet est renvoyé plutôt que l'attribut sous-
jacent.

Vous pouvez gérer ces cas à l'aide du code suivant. Notez que pour des
descripteurs arbitraires *getset* les invoquant, de l'exécution de
code pourrait être lancée :

   # example code for resolving the builtin descriptor types
   class _foo:
       __slots__ = ['foo']

   slot_descriptor = type(_foo.foo)
   getset_descriptor = type(type(open(__file__)).name)
   wrapper_descriptor = type(str.__dict__['__add__'])
   descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

   result = getattr_static(some_object, 'foo')
   if type(result) in descriptor_types:
       try:
           result = result.__get__()
       except AttributeError:
           # descriptors can raise AttributeError to
           # indicate there is no underlying value
           # in which case the descriptor itself will
           # have to do
           pass


Current State of Generators, Coroutines, and Asynchronous Generators
====================================================================

Lors de l'implémentation d'ordonnanceur de coroutine et autres
utilisations avancées de générateurs, il est utile de déterminer si un
générateur est présentement en cours d'exécution, en attente de
démarrage ou de continuation, ou s'il a déjà terminé.
"getgeneratorstate()" permet d'aisément déterminer l'état courant d'un
générateur.

inspect.getgeneratorstate(generator)

   Donne l'état courant d'un générateur-itérateur.

   Les états possibles :

   * GEN_CREATED : En attente de démarrage d'exécution.

   * GEN_RUNNING : En cours d'exécution par l'interpréteur.

   * GEN_SUSPENDED : Présentement suspendu à une expression *yield*.

   * GEN_CLOSED : L'exécution est complétée.

   Ajouté dans la version 3.2.

inspect.getcoroutinestate(coroutine)

   Donne l'état courant d'un objet coroutine. L'utilisation est prévue
   avec des objets coroutine créés avec des fonctions "async def",
   mais accepte n'importe quel objet semblable à une coroutine qui
   définisse des attributs "cr_running" "cr_frame".

   Les états possibles :

   * CORO_CREATED : En attente de démarrage d'exécution.

   * CORO_RUNNING : En cours d'exécution par l'interpréteur.

   * CORO_SUSPENDED : Suspendu à une expression *await*.

   * CORO_CLOSED : Exécution complétée.

   Ajouté dans la version 3.5.

inspect.getasyncgenstate(agen)

   Get current state of an asynchronous generator object.  The
   function is intended to be used with asynchronous iterator objects
   created by "async def" functions which use the "yield" statement,
   but will accept any asynchronous generator-like object that has
   "ag_running" and "ag_frame" attributes.

   Les états possibles :

   * AGEN_CREATED: Waiting to start execution.

   * AGEN_RUNNING: Currently being executed by the interpreter.

   * AGEN_SUSPENDED: Currently suspended at a yield expression.

   * AGEN_CLOSED: Execution has completed.

   Ajouté dans la version 3.12.

L'état courant interne du générateur peut aussi être vérifié. Ceci est
utile pour des tests, afin d'assurer que l'état interne est mise à
jour tel que prévu :

inspect.getgeneratorlocals(generator)

   Donne une correspondance de variables locales dans *generator* avec
   les valeurs courantes. Un dictionnaire est renvoyé, établissant la
   correspondance entre variables et valeurs. Ceci est équivalent à
   appeler "locals()" dans le corps du générateur et les mêmes
   restrictions s'appliquent.

   Si *generator* est un *générateur* sans cadre courant associé,
   alors un dictionnaire vide est renvoyé. "TypeError" est levé sir
   *generator* n'est pas un objet générateur Python.

   Cette fonction repose sur l'exposition d'une pile de cadres Python
   par le générateur pour l'introspection, ce qui n'est pas garanti
   dans toutes les implémentations Python. Dans un tel cas, cette
   fonction renvoie toujours un dictionnaire vide.

   Ajouté dans la version 3.3.

inspect.getcoroutinelocals(coroutine)

   Cette fonction est semblable à "getgeneratorlocals()", mais
   fonctionne pour des objets coroutines créés avec des fonctions
   "async def".

   Ajouté dans la version 3.5.

inspect.getasyncgenlocals(agen)

   This function is analogous to "getgeneratorlocals()", but works for
   asynchronous generator objects created by "async def" functions
   which use the "yield" statement.

   Ajouté dans la version 3.12.


Bit d'option des objets code
============================

Python code objects have a "co_flags" attribute, which is a bitmap of
the following flags:

inspect.CO_OPTIMIZED

   L'objet code est optimisé, utilisant des variables locales rapides.

inspect.CO_NEWLOCALS

   If set, a new dict will be created for the frame's "f_locals" when
   the code object is executed.

inspect.CO_VARARGS

   L'objet code possède un paramètre de variable positionnel ("*args"
   ou semblable).

inspect.CO_VARKEYWORDS

   L'objet code possède une paramètre par mot-clé variable ("**kwargs"
   ou semblable).

inspect.CO_NESTED

   L'option est définie lorsque le code est une fonction imbriquée.

inspect.CO_GENERATOR

   L'option est définie lorsque l'objet code est une fonction
   génératrice, c'est-à-dire qu'un objet générateur est renvoyé
   lorsque le code objet est exécuté.

inspect.CO_COROUTINE

   L'option est définie lorsque le code objet est une fonction
   coroutine. Lors que le code objet est exécuté, il renvoie un objet
   coroutine. Voir **PEP 492** pour plus de détails.

   Ajouté dans la version 3.5.

inspect.CO_ITERABLE_COROUTINE

   L'option est utilisée pour transformer un générateur en une
   coroutine basée sur un générateur. Les objets générateurs avec
   cette option peuvent être utilisés dans une expression "await" et
   un objet coroutine "yield from". Voir **PEP 492** pour plus de
   détails.

   Ajouté dans la version 3.5.

inspect.CO_ASYNC_GENERATOR

   L'option est définie lorsque l'objet code est une fonction
   génératrice asynchrone. Lorsque l'objet code est exécuté, il
   renvoie un objet générateur asynchrone. Voir **PEP 525** pour les
   détails.

   Ajouté dans la version 3.6.

inspect.CO_HAS_DOCSTRING

   The flag is set when there is a docstring for the code object in
   the source code. If set, it will be the first item in "co_consts".

   Ajouté dans la version 3.14.

inspect.CO_METHOD

   The flag is set when the code object is a function defined in class
   scope.

   Ajouté dans la version 3.14.

Note:

  The flags are specific to CPython, and may not be defined in other
  Python implementations.  Furthermore, the flags are an
  implementation detail, and can be removed or deprecated in future
  Python releases. It's recommended to use public APIs from the
  "inspect" module for any introspection needs.


Buffer flags
============

class inspect.BufferFlags

   This is an "enum.IntFlag" that represents the flags that can be
   passed to the "__buffer__()" method of objects implementing the
   buffer protocol.

   The meaning of the flags is explained at Buffer request types.

   SIMPLE

   WRITABLE

   FORMAT

   ND

   STRIDES

   C_CONTIGUOUS

   F_CONTIGUOUS

   ANY_CONTIGUOUS

   INDIRECT

   CONTIG

   CONTIG_RO

   STRIDED

   STRIDED_RO

   RECORDS

   RECORDS_RO

   FULL

   FULL_RO

   READ

   WRITE

   Ajouté dans la version 3.12.


Command-line interface
======================

The "inspect" module also provides a basic introspection capability
from the command line.

Par défaut, il accepte le nom d'un module et affiche la source de ce
module. Une classe ou fonction à l'intérieur du module peut également
être affichée en ajoutant un ":" et le nom qualifié de l'objet désiré.

--details

   Affiche de l'information à propos de l'objet spécifié plutôt que du
   code source.
