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 (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
méthode	__doc__	texte de documentation
	__name__	nom de la méthode lors de sa définition
	__qualname__	nom qualifié
	__func__	objet fonction contenant l'implémentation de la méthode
	__self__	instance à laquelle cette méthode est liée, ou None
	__module__	nom du module contenant la méthode lors de sa définition
fonction	__doc__	texte de documentation
	__name__	nom de la fonction lors de sa définition
	__qualname__	nom qualifié
	__code__	objet code contenant le code intermédiaire d'une fonction compilée
	__defaults__	n-uplet de valeurs par défaut pour arguments positionnels ou nommés
	__kwdefaults__	tableau de correspondance de valeurs par défaut pour les paramètres nommés
	__globals__	espace de nommage global lors de la définition de la fonction
	__builtins__	builtins namespace
	__annotations__	tableau de correspondance des paramètres à leur annotation ; "return" est un mot-clé réservé pour les annotations de type renvoyé.
	__module__	nom du module contenant la fonction lors de sa définition
traceback	tb_frame	objet cadre à ce niveau
	tb_lasti	index de la dernière instruction lancée dans le code intermédiaire (bytecode)
	tb_lineno	numéro de ligne courant dans le code source Python
	tb_next	trace de pile interne suivante (appel par le cadre courant)
cadre	f_back	trace d'exécution externe suivante (le contexte appelant du cadre courant)
	f_builtins	espace de nommage natif du cadre courant
	f_code	objet code exécuté dans le cadre courant
	f_globals	espace de nommage global tel que vu par cadre courant
	f_lasti	index de la dernière instruction lancée dans le code intermédiaire (bytecode)
	f_lineno	numéro de ligne courant dans le code source Python
	f_locals	espace de nommage local du cadre courant
	f_trace	fonction de traçage du cadre courant, ou None
code	co_argcount	nombre d'arguments (excluant les arguments keyword-only, * ou **)
	co_code	texte du code intermédiaire compilé
	co_cellvars	n-uplet du nom des cellules variables (référencées par leur contexte)
	co_consts	n-uplet des constantes utilisées dans le code intermédiaire (bytecode)
	co_filename	nom du fichier dans lequel cet objet code a été créé
	co_firstlineno	numéro de la première ligne dans le code source Python
	co_flags	bitmap des options CO_*, voir plus ici
	co_lnotab	tableau de correspondance encodée des numéros de ligne aux numéros d'indices du code intermédiaire (bytecode)
	co_freevars	n-uplet des noms de variables libres (référencées par la fermeture (closure en anglais) d'une fonction)
	co_posonlyargcount	nombre d'arguments positionnels
	co_kwonlyargcount	nombre d'arguments keywords-only (excluant les arguments **)
	co_name	nom de l'objet code lors de sa définition
	co_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
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.

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

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.

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

Nouveau 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

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.ismethodwrapper(object)

Return True if the type of object is a MethodWrapperType.

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

Nouveau 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

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

Nouveau 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 a enum value of Parameter.kind.

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

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

Nouveau dans la version 3.2.

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

inspect.getclosurevars(func)

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

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

Nouveau dans la version 3.3.

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

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

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

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

Nouveau dans la version 3.4.

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

Compute the annotations dict for an object.

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

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

This function handles several details for you:

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

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

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

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

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

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

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

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

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

• If obj is a module, globals defaults to obj.__dict__.

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

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

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

Nouveau dans la version 3.10.

La pile d'interpréteur

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.

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

Current State of Generators and Coroutines

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

inspect.getgeneratorstate(generator)

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

Les états possibles :

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

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

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

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

Nouveau dans la version 3.2.

inspect.getcoroutinestate(coroutine)

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

Les états possibles :

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

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

• CORO_SUSPENDED : Suspendu à une expression await.

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

Nouveau dans la version 3.5.

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

inspect.getgeneratorlocals(generator)

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

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

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

Nouveau dans la version 3.3.

inspect.getcoroutinelocals(coroutine)

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

Nouveau dans la version 3.5.

Bit d'option des objets code

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.

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.