"inspect" — Inspection d'objets
*******************************

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

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

Le module "inspect" implémente plusieurs fonctions permettant
d'obtenir de l'information à propos d'objets tels que les modules,
classes, méthodes, fonctions, traces de piles, cadres d'exécution et
objets code. Par exemple, il permet d'inspecter le contenu d'une
classe, de retrouver le code source d'une méthode, d'extraire et de
mettre en forme une liste d'arguments pour une fonction, ou obtenir
toute l'information nécessaire pour afficher une pile d'appels
détaillée.

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:

+-------------+---------------------+-----------------------------+
| Type        | Attribut            | Description                 |
|=============|=====================|=============================|
| module      | __doc__             | texte de documentation      |
+-------------+---------------------+-----------------------------+
|             | __file__            | nom de fichier (inexistant  |
|             |                     | pour les fonctions natives) |
+-------------+---------------------+-----------------------------+
| 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                  |
+-------------+---------------------+-----------------------------+
| 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é.                    |
+-------------+---------------------+-----------------------------+
|             | __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_trace             | fonction de traçage du      |
|             |                     | cadre courant, ou "None"    |
+-------------+---------------------+-----------------------------+
| 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_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                     |
+-------------+---------------------+-----------------------------+
| générateur  | __name__            | nom                         |
+-------------+---------------------+-----------------------------+
|             | __qualname__        | nom qualifié                |
+-------------+---------------------+-----------------------------+
|             | gi_frame            | cadre                       |
+-------------+---------------------+-----------------------------+
|             | gi_running          | est-ce que le générateur    |
|             |                     | est en cours d'exécution ?  |
+-------------+---------------------+-----------------------------+
|             | gi_code             | code                        |
+-------------+---------------------+-----------------------------+
|             | gi_yieldfrom        | objet pointé par            |
|             |                     | l'itérateur "yield from",   |
|             |                     | ou "None"                   |
+-------------+---------------------+-----------------------------+
| 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_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.

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()" renvoie les attributs de classe définis dans la
     métaclasse seulement lorsque l'argument est une classe et que ces
     attributs ont été listés dans la méthode personnalisée
     "__dir__()" de cette métaclasse.

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

   Renvoie "True" si l'objet est une *fonction coroutine* (une
   fonction définie avec une syntaxe "async def").

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

inspect.iscoroutine(object)

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

   Nouveau dans la version 3.5.

inspect.isawaitable(object)

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

   Peut aussi être utilisé pour distinguer les coroutines basées sur
   un générateur des générateurs normaux :

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

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

   Nouveau dans la version 3.5.

inspect.isasyncgenfunction(object)

   Renvoie "True" si l'objet est un *générateur asynchrone*, par
   exemple :

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

   Nouveau dans la version 3.6.

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

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

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

   Cela est par exemple vrai pour "int.__add__". Un objet qui passe ce
   test a une méthode "__get__()", pas de méthode "__set__()", sans
   être regardant sur les  autres les attributs. Un attribut
   "__name__" sera souvent présent et "__doc__" également.

   Les méthodes implémentées via descripteurs et qui passent l'un ou
   l'autre des tests renvoie "False" pour "ismethoddescriptor()",
   simplement parce que les autres tests garantissent davantage — vous
   pouvez supposer l'existence d'un attribut "__func__" (etc.)
   lorsqu'un objet renvoie "True" pour "ismethod()" .

inspect.isdatadescriptor(object)

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

   Les descripteurs de données ont une méthode "__set__" ou
   "__delete__". Par exemple les propriétés (définies en Python),
   *getsets* et les membres. Les 2 derniers sont définis en C et il
   existe des tests plus spécifiques disponibles pour ceux-ci qui sont
   robustes à travers les implémentations Python. Normalement, les
   descripteurs de données auront aussi les attributs "__name__" et
   "__doc__" (les propriétés, *getsets* et membres auront les deux),
   mais cela n'est pas garanti.

inspect.isgetsetdescriptor(object)

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

   **Particularité de l'implémentation CPython :** *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.

   **Particularité de l'implémentation CPython :** 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
===================================================

Nouveau dans la version 3.3.

L'objet Signature représente la signature de l'appel et de la valeur
renvoyée d'un objet appelable. Utilisez la fonction "signature()" pour
obtenir ces signatures.

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

   Renvoie un objet "Signature" pour un "appelable" :

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

   For objects defined in modules using stringized annotations ("from
   __future__ import annotations"), "signature()" will attempt to
   automatically un-stringize the annotations using
   "inspect.get_annotations()".  The "global", "locals", and
   "eval_str" parameters are passed into "inspect.get_annotations()"
   when resolving the annotations; see the documentation for
   "inspect.get_annotations()" for instructions on how to use these
   parameters.

   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 could potentially
   raise any kind of exception.

   Une barre oblique ("/") dans la signature d'une fonction dénote que
   les paramètres qui précèdent sont exclusivement positionnels. Pour
   plus d'information, voir l'entrée de la FAQ sur les arguments
   exclusivement positionnels.

   Nouveau dans la version 3.5: paramètre "follow_wrapped". Passez
   "False" pour obtenir une signature "callable" plus spécifiquement
   ("callable.__wrapped__" ne sera pas utilisé pour dépouiller un
   appelable décoré.)

   Nouveau dans la version 3.10: "globals", "locals", and "eval_str"
   parameters.

   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.

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

   L'objet Signature représente la signature d'appel d'une fonction et
   son annotation de type. Pour chaque paramètre accepté par une
   fonction, il conserve un objet "Parameter" dans sa collection
   "parameters".

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

   L'argument optionnel *return_annotation* pouvant être un objet
   Python arbitraire, est l'annotation du type renvoyé par appelable.

   Les objets Signatures sont *immuables*. Utilisez
   "Signature.replace()" pour en faire une copie modifiée.

   Modifié dans la version 3.5: Signature objects are 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])

      Crée une nouvelle instance de Signature sur la base de
      l'instance sur laquelle la méthode est invoquée. Il est possible
      de passer différents paramètres et/ou annotations de type pour
      remplacer les propriétés correspondantes de la signature de
      base. Pour enlever les annotations de type de la copie de la
      Signature, lui passer "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'"

   classmethod from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)

      Return a "Signature" (or its subclass) object for a given
      callable "obj".  Pass "follow_wrapped=False" to get a signature
      of "obj" without unwrapping its "__wrapped__" chain. "globalns"
      and "localns" will be used as the namespaces when resolving
      annotations.

      Cette méthode simplifie l'héritage de "Signature" :

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

      Nouveau dans la version 3.5.

      Nouveau dans la version 3.10: "globalns" and "localns"
      parameters.

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

   Les objets *Parameter* sont *immuables*. Utilisez
   "Parameter.replace()" pour créer une copie modifiée.

   Modifié dans la version 3.5: Parameter objects are 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.

      **Particularité de l'implémentation CPython :** 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: ces paramètres sont exposés par ce
      module par des noms de forme "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.                 |
      +--------------------------+------------------------------------------------+

      Exemple : afficher tous les arguments exclusivement nommés sans
      valeur par défaut :

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

      Décrit une énumération de valeurs de "Parameter.kind".

      Nouveau dans la version 3.8.

      Exemple : afficher toutes les descriptions d'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])

      Crée une nouvelle instance de *Parameter* sur la base de
      l'instance sur laquelle la méthode est invoquée. Pour redéfinir
      un attribut "Parameter", lui passer l'argument correspondant.
      Pour enlever les valeurs par défaut et/ou les annotations de
      retour de la copie du Parameter, lui passer "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'"

   Modifié dans la version 3.4: en Python 3.3, un objet Parameter
   pouvait avoir "name" à "None" si son attribut "kind" valait
   "POSITIONAL_ONLY". Cela n'est plus possible.

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

      Un dictionnaire des valeurs des arguments nommés. Évalué
      dynamiquement à partir de l'attribut "arguments".

   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': ()}

      Nouveau dans la version 3.5.

   Les propriétés "args" et "kwargs" peuvent être utilisées pour
   l'appel de fonctions :

      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.getargspec(func)

   Get the names and default values of a Python function's parameters.
   A *named tuple* "ArgSpec(args, varargs, keywords, defaults)" is
   returned. *args* is a list of the parameter names. *varargs* and
   *keywords* are the names of the "*" and "**" parameters or "None".
   *defaults* is a tuple of default argument values or "None" if there
   are no default arguments; if this tuple has *n* elements, they
   correspond to the last *n* elements listed in *args*.

   Obsolète depuis la version 3.0: Use "getfullargspec()" for an
   updated API that is usually a drop-in replacement, but also
   correctly handles function annotations and keyword-only
   parameters.Alternatively, use "signature()" and Signature Object,
   which provide a more structured introspection API for callables.

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: cette méthode fût précédemment
   documentée comme dépréciée en faveur de "signature()" en Python
   3.5, mais cette décision fût renversée afin de ré-introduire une
   interface standard clairement supportée pour du code unifié Python
   2/3 migrant pour se départir de l'API "getargspec()".

   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.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

   Format a pretty argument spec from the values returned by
   "getfullargspec()".

   The first seven arguments are ("args", "varargs", "varkw",
   "defaults", "kwonlyargs", "kwonlydefaults", "annotations").

   The other six arguments are functions that are called to turn
   argument names, "*" argument name, "**" argument name, default
   values, return annotation and individual annotations into strings,
   respectively.

   Par exemple :

   >>> from inspect import formatargspec, getfullargspec
   >>> def f(a: int, b: float):
   ...     pass
   ...
   >>> formatargspec(*getfullargspec(f))
   '(a: int, b: float)'

   Obsolète depuis la version 3.5: Use "signature()" and Signature
   Object, which provide a better introspecting API for callables.

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)

   Lie *args* et *kwds* aux arguments nommés de la fonction ou méthode
   Python *func*, comme si elle était appelée avec ceux-ci. Pour les
   méthodes liées, lie aussi le premier argument (normalement appelé
   "self") à l'instance associée. Un dictionnaire est renvoyé, une
   correspondance entre les noms des arguments (incluant les noms des
   arguments "*" et "**", s'ils existent) et leurs valeurs obtenues de
   *args* et *kwds*. Lors d'une invocation incorrecte de *func*, i.e.
   lorsque "func(*args, **kwds)" lèverait une exception en raison de
   signature incompatible, une exception du même type et de message
   identique ou similaire est levée. Par exemple :

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

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

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

   Nouveau dans la version 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)

   Compute the annotations dict for an object.

   "obj" may be a callable, class, or module. Passing in an object of
   any other type raises "TypeError".

   Returns a dict.  "get_annotations()" returns a new dict every time
   it's called; calling it twice on the same object will return two
   different but equivalent dicts.

   This function handles several details for you:

   * If "eval_str" is true, values of type "str" will be un-stringized
     using "eval()".  This is intended for use with stringized
     annotations ("from __future__ import annotations").

   * If "obj" doesn't have an annotations dict, returns an empty dict.
     (Functions and methods always have an annotations dict; classes,
     modules, and other types of callables may not.)

   * Ignores inherited annotations on classes.  If a class doesn't
     have its own annotations dict, returns an empty dict.

   * All accesses to object members and dict values are done using
     "getattr()" and "dict.get()" for safety.

   * Always, always, always returns a freshly created dict.

   "eval_str" controls whether or not values of type "str" are
   replaced with the result of calling "eval()" on those values:

   * If eval_str is true, "eval()" is called on values of type "str".
     (Note that "get_annotations" doesn't catch exceptions; if
     "eval()" raises an exception, it will unwind the stack past the
     "get_annotations" call.)

   * If eval_str is false (the default), values of type "str" are
     unchanged.

   "globals" and "locals" are passed in to "eval()"; see the
   documentation for "eval()" for more information.  If "globals" or
   "locals" is "None", this function may replace that value with a
   context-specific default, contingent on "type(obj)":

   * If "obj" is a module, "globals" defaults to "obj.__dict__".

   * If "obj" is a class, "globals" defaults to
     "sys.modules[obj.__module__].__dict__" and "locals" defaults to
     the "obj" class namespace.

   * If "obj" is a callable, "globals" defaults to "obj.__globals__",
     although if "obj" is a wrapped function (using
     "functools.update_wrapper()") it is first unwrapped.

   Calling "get_annotations" is best practice for accessing the
   annotations dict of any object.  See Bonnes pratiques concernant
   les annotations for more information on annotations best practices.

   Nouveau dans la version 3.10.


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

When the following functions return "frame records," each record is a
*named tuple* "FrameInfo(frame, filename, lineno, function,
code_context, index)". The tuple contains the frame object, the
filename, the line number of the current line, the function name, a
list of lines of context from the source code, and the index of the
current line within that list.

Modifié dans la version 3.5: Return a named tuple instead of a 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 *named tuple*
   "Traceback(filename, lineno, function, code_context, index)" is
   returned.

inspect.getouterframes(frame, context=1)

   Get a list of frame records 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.

inspect.getinnerframes(traceback, context=1)

   Get a list of frame records 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.

inspect.currentframe()

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

   **Particularité de l'implémentation CPython :** 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 frame records 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.

inspect.trace(context=1)

   Return a list of frame records 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.


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

"getattr()" et "hasattr()" peuvent tous deux engendrer l'exécution de
code lors la recherche ou vérification de l'existence d'attributs. Les
descripteurs, comme les propriétés, seront invoqués et "__getattr__()"
et "__getattribute__()" peuvent être appelés.

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)

   Retrouve des attributs sans lancer une recherche dynamique via le
   protocole descripteur, "__getattr__()" ou "__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.

   Nouveau 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


État courant de Générateurs et Coroutines
=========================================

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.

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

   Nouveau dans la version 3.5.

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.

   **Particularité de l'implémentation CPython :** 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.

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

   Nouveau dans la version 3.5.


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

Les objets de code Python ont un attribut "co_flags", ce qui est un
*bitmap* des valeurs suivantes :

inspect.CO_OPTIMIZED

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

inspect.CO_NEWLOCALS

   Si défini, un nouveau dictionnaire sera créé pour le "f_locals" du
   cadre courant lorsque l'objet code est exécuté.

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_NOFREE

   The flag is set if there are no free or cell variables.

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.

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

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

   Nouveau dans la version 3.6.

Note:

  Ces options sont spécifiques à CPython et pourraient ne pas être
  définies dans d'autres implémentations Python. De plus, les options
  constituent des détails d'implémentation et pourraient être enlevées
  ou dépréciées dans des versions ultérieures. Il est recommandé
  d'utiliser les APIs publiques de "inspect" pour tous les besoins
  d'introspection.


Interface en ligne de commande
==============================

Le module "inspect" fournit également des capacités d'introspection de
base en ligne de commande.

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.
