Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# `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
| __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 of local variables
| 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.

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

  CPython implementation detail: 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.

  CPython implementation detail: 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.

  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.

`inspect.``getsourcefile`(object)

  Return the name of the Python source file in which an object was defined. This will fail with a `TypeError` if the object is a built-in module, class, or function.

`inspect.``getsourcelines`(object)

  Renvoie une liste de lignes du code source et le numéro de la première ligne d'un objet. L'argument peut être un module, classe, méthode, fonction, trace d'exécution, cadre ou objet code. Le code source est renvoyé comme une liste des lignes correspondant à l'objet, et le numéro de ligne indique la position à laquelle la première ligne de code a été trouvée. Une `OSError` est levée si le code source ne peut être retrouvé.

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

`inspect.``getsource`(object)

  Renvoie le texte du code source pour un objet. L'argument peut être un module, classe, méthode, fonction, trace de pile, cadre ou objet code. Le code source est renvoyé comme une seule chaîne de caractères. `OSError` est levé si le code source ne peut être retrouvé.

  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)

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

  Raises `ValueError` if no signature can be provided, and `TypeError` if that type of object is not supported.

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

  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: les objets Signature sont pickable (sérialisables avec Pickle) et hachables.

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

    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.

    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.

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: les objets Parameters sont pickable (sérialisables avec Pickle) et hachable.

  `empty`

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

  `name`

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

    CPython implementation detail: 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`

    Décrit comment les valeurs d'argument sont liées au paramètre. Les valeurs possibles (accessibles par `Parameter`, tel que `Parameter.KEYWORD_ONLY`) :

    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.

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

  CPython implementation detail: 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.

  CPython implementation detail: 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.