# `inspect` --- Inspect live objects

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 (see Attributs des modules importés 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_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_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
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_code | code
| gi_yieldfrom | objet pointé par l'itérateur `yield from`, ou `None`
async generator | __name__ | nom
| __qualname__ | nom qualifié
| ag_await | objet sur lequel on attend (await) présentement, ou `None`
| ag_frame | cadre
| ag_running | est-ce que le générateur est en cours d'exécution ?
| 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_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()` 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.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)

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

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.

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, but 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()`.

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.

  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

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)

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

  For objects defined in modules using stringized annotations (`from __future__ import annotations`), `signature()` will attempt to automatically un-stringize the annotations using `get_annotations()`. The globals, locals, and eval_str parameters are passed into `get_annotations()` when resolving the annotations; see the documentation for `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 in `get_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.

  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.

  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()` 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'"

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

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

  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

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

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

  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.

  Ajouté dans la version 3.10.

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

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

  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.

  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.

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.

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

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