inspect — Inspection d'objets

Code source : Lib/inspect.py

---

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

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

Types et membres

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

Type	Attribut	Description
module	__doc__	texte de documentation
	__file__	nom de fichier (inexistant pour les fonctions natives)
classe	__doc__	texte de documentation
	__name__	nom de la classe lors de sa définition
	__qualname__	nom qualifié
	__module__	nom du module contenant la classe lors de sa définition
méthode	__doc__	texte de documentation
	__name__	nom de la méthode lors de sa définition
	__qualname__	nom qualifié
	__func__	objet fonction contenant l'implémentation de la méthode
	__self__	instance à laquelle cette méthode est liée, ou None
	__module__	nom du module contenant la méthode lors de sa définition
fonction	__doc__	texte de documentation
	__name__	nom de la fonction lors de sa définition
	__qualname__	nom qualifié
	__code__	objet code contenant le code intermédiaire d'une fonction compilée
	__defaults__	n-uplet de valeurs par défaut pour arguments positionnels ou nommés
	__kwdefaults__	tableau de correspondance de valeurs par défaut pour les paramètres nommés
	__globals__	espace de nommage global lors de la définition de la fonction
	__builtins__	builtins namespace
	__annotations__	tableau de correspondance des paramètres à leur annotation ; "return" est un mot-clé réservé pour les annotations de type renvoyé.
	__module__	nom du module contenant la fonction lors de sa définition
traceback	tb_frame	objet cadre à ce niveau
	tb_lasti	index de la dernière instruction lancée dans le code intermédiaire (bytecode)
	tb_lineno	numéro de ligne courant dans le code source Python
	tb_next	trace de pile interne suivante (appel par le cadre courant)
cadre	f_back	trace d'exécution externe suivante (le contexte appelant du cadre courant)
	f_builtins	espace de nommage natif du cadre courant
	f_code	objet code exécuté dans le cadre courant
	f_globals	espace de nommage global tel que vu par cadre courant
	f_lasti	index de la dernière instruction lancée dans le code intermédiaire (bytecode)
	f_lineno	numéro de ligne courant dans le code source Python
	f_locals	espace de nommage local du cadre courant
	f_trace	fonction de traçage du cadre courant, ou None
code	co_argcount	nombre d'arguments (excluant les arguments keyword-only, * ou **)
	co_code	texte du code intermédiaire compilé
	co_cellvars	n-uplet du nom des cellules variables (référencées par leur contexte)
	co_consts	n-uplet des constantes utilisées dans le code intermédiaire (bytecode)
	co_filename	nom du fichier dans lequel cet objet code a été créé
	co_firstlineno	numéro de la première ligne dans le code source Python
	co_flags	bitmap des options CO_*, voir plus ici
	co_lnotab	tableau de correspondance encodée des numéros de ligne aux numéros d'indices du code intermédiaire (bytecode)
	co_freevars	n-uplet des noms de variables libres (référencées par la fermeture (closure en anglais) d'une fonction)
	co_posonlyargcount	nombre d'arguments positionnels
	co_kwonlyargcount	nombre d'arguments keywords-only (excluant les arguments **)
	co_name	nom de l'objet code lors de sa définition
	co_names	tuple of names other than arguments and function locals
	co_nlocals	nombre de variables locales
	co_stacksize	espace requis pour la pile de la machine virtuelle
	co_varnames	n-uplet des noms des arguments et variables locales
générateur	__name__	nom
	__qualname__	nom qualifié
	gi_frame	cadre
	gi_running	est-ce que le générateur est en cours d'exécution ?
	gi_code	code
	gi_yieldfrom	objet pointé par l'itérateur yield from, ou None
coroutine	__name__	nom
	__qualname__	nom qualifié
	cr_await	objet sur lequel on attend (await) présentement, ou None
	cr_frame	cadre
	cr_running	est-ce que la coroutine est en cours d'exécution ?
	cr_code	code
	cr_origin	lieu de création de la coroutine, ou None. Voir sys.set_coroutine_origin_tracking_depth()
builtin	__doc__	texte de documentation
	__name__	nom originel de cette fonction ou méthode
	__qualname__	nom qualifié
	__self__	instance à laquelle est liée une méthode, ou None

Modifié dans la version 3.5: ajout des attributs __qualname et gi_yieldfrom aux générateurs.

L'attribut __name__ du générateur est maintenant déterminé par le nom de la fonction, plutôt que le nom du code, et peut maintenant être modifié.

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

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

inspect.getmembers(object[, predicate])

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

Note

getmembers() renvoie les attributs de classe définis dans la métaclasse seulement lorsque l'argument est une classe et que ces attributs ont été listés dans la méthode personnalisée __dir__() de cette métaclasse.

inspect.getmodulename(path)

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

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

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

inspect.ismodule(object)

Renvoie True si l'objet est un module.

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

inspect.isgeneratorfunction(object)

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

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

Nouveau dans la version 3.5.

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

inspect.iscoroutine(object)

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

Nouveau dans la version 3.5.

inspect.isawaitable(object)

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

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

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

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

Nouveau dans la version 3.5.

inspect.isasyncgenfunction(object)

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

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

Nouveau dans la version 3.6.

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

inspect.isasyncgen(object)

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

Nouveau dans la version 3.6.

inspect.istraceback(object)

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

inspect.isframe(object)

Renvoie True si l'objet est un cadre.

inspect.iscode(object)

Renvoie True si l'objet est un code.

inspect.isbuiltin(object)

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

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

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

inspect.isdatadescriptor(object)

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

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

inspect.isgetsetdescriptor(object)

Renvoie True si l'objet est un descripteur getset.

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

inspect.ismemberdescriptor(object)

Renvoie True si l'objet est un membre descripteur.

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

Récupération du code source

inspect.getdoc(object)

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

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

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

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

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

inspect.getsource(object)

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

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

inspect.cleandoc(doc)

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

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

Introspection des appelables avec l'objet Signature

Nouveau dans la version 3.3.

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

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

Renvoie un objet Signature pour un appelable :

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

>>> sig = signature(foo)

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

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

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

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

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

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

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

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

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

Note

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

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

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

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

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

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

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

empty

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

parameters

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

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

return_annotation

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

bind(*args, **kwargs)

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

bind_partial(*args, **kwargs)

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

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

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

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

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

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

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

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

Nouveau dans la version 3.5.

Nouveau dans la version 3.10: globalns and localns parameters.

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

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

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

empty

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

name

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

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

Modifié dans la version 3.6: ces paramètres sont exposés par ce module par des noms de forme implicit0.

default

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

annotation

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

kind

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

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

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

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

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

kind.description

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

Nouveau dans la version 3.8.

Exemple : afficher toutes les descriptions d'arguments :

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

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

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

Crée une nouvelle instance de Parameter sur la base de l'instance sur laquelle la méthode est invoquée. Pour redéfinir un attribut Parameter, lui passer l'argument correspondant. Pour enlever les valeurs par défaut et/ou les annotations de retour de la copie du Parameter, lui passer Parameter.empty.

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

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

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

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

class inspect.BoundArguments

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

arguments

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

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

Note

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

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

args

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

kwargs

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

signature

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

apply_defaults()

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

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

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

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

Nouveau dans la version 3.5.

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

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

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

Voir aussi

PEP 362 — Function Signature Object.

La spécification détaillée, détails d'implémentation et exemples.

Classes et fonctions

inspect.getclasstree(classes, unique=False)

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

inspect.getargspec(func)

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

Obsolète depuis la version 3.0: Use getfullargspec() for an updated API that is usually a drop-in replacement, but also correctly handles function annotations and keyword-only parameters.

Alternatively, use signature() and Signature Object, which provide a more structured introspection API for callables.

inspect.getfullargspec(func)

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

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

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

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

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

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

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

inspect.getargvalues(frame)

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

Note

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

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

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

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

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

Par exemple :

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

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

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

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

Note

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

inspect.getmro(cls)

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

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

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

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

Nouveau dans la version 3.2.

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

inspect.getclosurevars(func)

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

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

Nouveau dans la version 3.3.

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

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

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

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

Nouveau dans la version 3.4.

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

Compute the annotations dict for an object.

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

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

This function handles several details for you:

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

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

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

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

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

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

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

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

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

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

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

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

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

Nouveau dans la version 3.10.

La pile d'interpréteur

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

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

Note

Conserver des références à des objets cadre, tel que trouvé dans le 1er élément des enregistrements de cadres que ces fonctions renvoient, peut créer des cycles de référence dans votre programme. Lorsqu'un cycle de référence a été créé, la durée de vie de tous les objets pouvant être accessibles par ces objets peut être grandement augmentée, même si le détecteur de cycle (optionnel) de Python est activé. Si ces cycles doivent être créés, il est important de s'assurer qu'ils soient explicitement brisés pour éviter la destruction reportée des objets et l'augmentation résultante de l'utilisation de la mémoire.

Bien que le détecteur trouvera ces cycles, la destruction des cadres (et variables locales) peut être fait de manière déterministe en enlevant les cycles dans une clause finally. Cela est important si le détecteur de cycle a été désactivé lors de la compilation du code Python ou en utilisant gc.disable(). Par exemple :

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

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

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

inspect.getframeinfo(frame, context=1)

Get information about a frame or traceback object. A named tuple Traceback(filename, lineno, function, code_context, index) is returned.

inspect.getouterframes(frame, context=1)

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

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

inspect.getinnerframes(traceback, context=1)

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

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

inspect.currentframe()

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

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

inspect.stack(context=1)

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

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

inspect.trace(context=1)

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

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

Recherche dynamique d'attributs

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

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

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

Retrouve des attributs sans lancer une recherche dynamique via le protocole descripteur, __getattr__() ou __getattribute__().

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

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

Nouveau dans la version 3.2.

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

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

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

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

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

État courant de Générateurs et Coroutines

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

inspect.getgeneratorstate(generator)

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

Les états possibles :

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

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

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

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

Nouveau dans la version 3.2.

inspect.getcoroutinestate(coroutine)

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

Les états possibles :

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

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

• CORO_SUSPENDED : Suspendu à une expression await.

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

Nouveau dans la version 3.5.

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

inspect.getgeneratorlocals(generator)

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

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

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

Nouveau dans la version 3.3.

inspect.getcoroutinelocals(coroutine)

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

Nouveau dans la version 3.5.

Bit d'option des objets code

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

inspect.CO_OPTIMIZED

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

inspect.CO_NEWLOCALS

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

inspect.CO_VARARGS

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

inspect.CO_VARKEYWORDS

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

inspect.CO_NESTED

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

inspect.CO_GENERATOR

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

inspect.CO_NOFREE

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

inspect.CO_COROUTINE

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

Nouveau dans la version 3.5.

inspect.CO_ITERABLE_COROUTINE

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

Nouveau dans la version 3.5.

inspect.CO_ASYNC_GENERATOR

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

Nouveau dans la version 3.6.

Note

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

Interface en ligne de commande

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

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

--details

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