inspect
--- Inspect live objects¶
Code source : Lib/inspect.py
Le module inspect
implémente plusieurs fonctions permettant d'obtenir de l'information à propos d'objets tels que les modules, classes, méthodes, fonctions, traces de piles, cadres d'exécution et objets code. Par exemple, il permet d'inspecter le contenu d'une classe, de retrouver le code source d'une méthode, d'extraire et de mettre en forme une liste d'arguments pour une fonction, ou obtenir toute l'information nécessaire pour afficher une pile d'appels détaillée.
Ce module donne accès à 4 types de services : vérification de typage, obtention de code source, inspection de classes et de fonctions et examen de la pile d'exécution.
Types et membres¶
The getmembers()
function retrieves the members of an object such as a
class or module. The functions whose names begin with "is" are mainly
provided as convenient choices for the second argument to getmembers()
.
They also help you determine when you can expect to find the following special
attributes (see Attributs des modules importés for module attributes):
Type |
Attribut |
Description |
---|---|---|
classe |
__doc__ |
texte de documentation |
__name__ |
nom de la classe lors de sa définition |
|
__qualname__ |
nom qualifié |
|
__module__ |
nom du module contenant la classe lors de sa définition |
|
__type_params__ |
A tuple containing the type parameters of a generic class |
|
méthode |
__doc__ |
texte de documentation |
__name__ |
nom de la méthode lors de sa définition |
|
__qualname__ |
nom qualifié |
|
__func__ |
objet fonction contenant l'implémentation de la méthode |
|
__self__ |
instance à laquelle cette méthode est liée, ou |
|
__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 ; |
|
__type_params__ |
A tuple containing the type parameters of a generic function |
|
__module__ |
nom du module contenant la fonction lors de sa définition |
|
traceback |
tb_frame |
objet cadre à ce niveau |
tb_lasti |
index de la dernière instruction lancée dans le code intermédiaire ( |
|
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 ( |
|
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 |
|
f_trace_lines |
indicate whether a tracing event is triggered for each source source line |
|
f_trace_opcodes |
indicate whether per-opcode events are requested |
|
clear() |
used to clear all references to local variables |
|
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 ( |
|
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_lnotab |
tableau de correspondance encodée des numéros de ligne aux numéros d'indices du code intermédiaire ( |
|
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 |
|
co_lines() |
returns an iterator that yields successive bytecode ranges |
|
co_positions() |
returns an iterator of source code positions for each bytecode instruction |
|
replace() |
returns a copy of the code object with new values |
|
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 |
|
async generator |
__name__ |
nom |
__qualname__ |
nom qualifié |
|
ag_await |
objet sur lequel on attend (await) présentement, ou |
|
ag_frame |
cadre |
|
ag_running |
est-ce que le générateur est en cours d'exécution ? |
|
ag_code |
code |
|
coroutine |
__name__ |
nom |
__qualname__ |
nom qualifié |
|
cr_await |
objet sur lequel on attend (await) présentement, ou |
|
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 |
|
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 |
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 lavaleur
de chaque membre) est fourni, seuls les membres pour lequel le prédicat est vrai seront inclus.Note
getmembers()
will only return class attributes defined in the metaclass when the argument is a class and those attributes have been listed in the metaclass' custom__dir__()
.
- inspect.getmembers_static(object[, predicate])¶
Return all the members of an object in a list of
(name, value)
pairs sorted by name without triggering dynamic lookup via the descriptor protocol, __getattr__ or __getattribute__. Optionally, only return members that satisfy a given predicate.Note
getmembers_static()
may not be able to retrieve all members that getmembers can fetch (like dynamically created attributes) and may find members that getmembers can't (like descriptors that raise AttributeError). It can also return descriptor objects instead of instance members in some cases.Ajouté dans la version 3.11.
- inspect.getmodulename(path)¶
Renvoie le nom du module indiqué par le fichier path, excluant le nom des paquets englobants. L'extension du fichier est vérifiée parmi toutes les entrées renvoyées par
importlib.machinery.all_suffixes()
. S'il y a une correspondance, le chemin final est renvoyé, sans l'extension. Autrement,None
est renvoyé.Notez que cette fonction renvoie un nom significatif seulement pour les modules Python - les chemins qui réfèrent à des paquets Python donnent toujours
None
.Modifié dans la version 3.3: La fonction est basée directement sur
importlib
.
- inspect.ismodule(object)¶
Renvoie
True
si l'objet est un module.
- inspect.isclass(object)¶
Renvoie
True
si l'objet est une classe, qu'il s'agisse d'un objet natif ou qu'elle soit écrite en Python.
- inspect.ismethod(object)¶
Renvoie
True
si l'objet est une méthode liée écrite en Python.
- inspect.isfunction(object)¶
Renvoie
True
si l'objet est une fonction Python, ce qui inclut les fonctions créées par une expression lambda.
- inspect.isgeneratorfunction(object)¶
Renvoie
True
si l'objet est un générateur.Modifié dans la version 3.8: les fonctions englobées dans
functools.partial()
renvoient maintenantTrue
si la fonction englobée est un générateur Python.Modifié dans la version 3.13: Functions wrapped in
functools.partialmethod()
now returnTrue
if the wrapped function is a Python generator function.
- 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 anasync def
syntax), afunctools.partial()
wrapping a coroutine function, or a sync function marked withmarkcoroutinefunction()
.Ajouté dans la version 3.5.
Modifié dans la version 3.8: les fonctions englobées par
functools.partial()
renvoient maintenantTrue
si la fonction englobée est une coroutine.Modifié dans la version 3.12: Sync functions marked with
markcoroutinefunction()
now returnTrue
.Modifié dans la version 3.13: Functions wrapped in
functools.partialmethod()
now returnTrue
if the wrapped function is a coroutine function.
- inspect.markcoroutinefunction(func)¶
Decorator to mark a callable as a coroutine function if it would not otherwise be detected by
iscoroutinefunction()
.This may be of use for sync functions that return a coroutine, if the function is passed to an API that requires
iscoroutinefunction()
.When possible, using an
async def
function is preferred. Also acceptable is calling the function and testing the return withiscoroutine()
.Ajouté dans la version 3.12.
- inspect.iscoroutine(object)¶
Renvoie
True
si l'objet est une coroutine créée par une fonctionasync def
.Ajouté dans la version 3.5.
- inspect.isawaitable(object)¶
Renvoie
True
si l'objet peut être utilisé par une expressionawait
.Can also be used to distinguish generator-based coroutines from regular generators:
import types def gen(): yield @types.coroutine def gen_coro(): yield assert not isawaitable(gen()) assert isawaitable(gen_coro())
Ajouté dans la version 3.5.
- inspect.isasyncgenfunction(object)¶
Return
True
if the object is an asynchronous generator function, for example:>>> async def agen(): ... yield 1 ... >>> inspect.isasyncgenfunction(agen) True
Ajouté dans la version 3.6.
Modifié dans la version 3.8: Functions wrapped in
functools.partial()
now returnTrue
if the wrapped function is an asynchronous generator function.Modifié dans la version 3.13: Functions wrapped in
functools.partialmethod()
now returnTrue
if the wrapped function is a coroutine function.
- inspect.isasyncgen(object)¶
Renvoie
True
si l'objet est un itérateur de générateur asynchrone créé par une fonction génératrice asynchrone.Ajouté dans la version 3.6.
- inspect.istraceback(object)¶
Renvoie
True
si l'objet est une trace d'exécution.
- inspect.isframe(object)¶
Renvoie
True
si l'objet est un cadre.
- inspect.iscode(object)¶
Renvoie
True
si l'objet est un code.
- inspect.isbuiltin(object)¶
Renvoie
True
si l'objet est une fonction native ou une méthode liée native.
- inspect.ismethodwrapper(object)¶
Return
True
if the type of object is aMethodWrapperType
.These are instances of
MethodWrapperType
, such as__str__()
,__eq__()
and__repr__()
.Ajouté dans la version 3.11.
- inspect.isroutine(object)¶
Renvoie
True
si l'objet est une fonction, qu'elle soit définie par l'utilisateur, native, ou une méthode.
- inspect.isabstract(object)¶
Renvoie
True
si l'objet est une classe de base abstraite.
- inspect.ismethoddescriptor(object)¶
Renvoie
True
si l'objet est un descripteur de méthode sauf siismethod()
,isclass()
,isfunction()
ouisbuiltin()
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 or a__delete__()
method. 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 theismethoddescriptor()
test, simply because the other tests promise more -- you can, e.g., count on having the__func__
attribute (etc) when an object passesismethod()
.Modifié dans la version 3.13: This function no longer incorrectly reports objects with
__get__()
and__delete__()
, but not__set__()
, as being method descriptors (such objects are data descriptors, not method descriptors).
- 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 toujoursFalse
.
- 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 toujoursFalse
.
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. ReturnNone
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 aTypeError
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. ATypeError
is raised if the object is a built-in module, class, or function.
- 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. ATypeError
is raised if the object is a built-in module, class, or function.
- inspect.cleandoc(doc)¶
Nettoie les indentations des chaînes de documentation qui sont indentées de manières à s'aligner avec les blocs de code.
Enlève tous les espaces blancs en début de ligne à partir de la première. Tout espace blanc en début de ligne qui puisse être enlevé de manière uniforme à partir de la seconde ligne le sera. Les lignes vides en début et en fin de document seront ensuite enlevées. Les tabulations seront converties en espaces.
Introspection des appelables avec l'objet Signature¶
Ajouté dans la version 3.3.
The Signature
object represents the call signature of a callable object
and its return annotation. To retrieve a Signature
object,
use the signature()
function.
- inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)¶
Return a
Signature
object for the given callable:>>> from inspect import signature >>> def foo(a, *, b:int, **kwargs): ... pass >>> sig = signature(foo) >>> str(sig) '(a, *, b: int, **kwargs)' >>> str(sig.parameters['b']) 'b: int' >>> sig.parameters['b'].annotation <class 'int'>
La fonction accepte une grande étendue d'appelables Python, des fonctions et classes jusqu'aux objets
functools.partials()
.If some of the annotations are strings (e.g., because
from __future__ import annotations
was used),signature()
will attempt to automatically un-stringize the annotations usingannotationlib.get_annotations()
. The globals, locals, and eval_str parameters are passed intoannotationlib.get_annotations()
when resolving the annotations; see the documentation forannotationlib.get_annotations()
for instructions on how to use these parameters.Raises
ValueError
if no signature can be provided, andTypeError
if that type of object is not supported. Also, if the annotations are stringized, and eval_str is not false, theeval()
call(s) to un-stringize the annotations inannotationlib.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 aParameter
object in itsparameters
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. UseSignature.replace()
orcopy.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 uneTypeError
.
- bind_partial(*args, **kwargs)¶
Fonctionne de manière similaire à
Signature.bind()
, mais permet l'omission de certains arguments (semblable au comportement defunctools.partial()
). RenvoieBoundArguments
, ou lève uneTypeError
si l'argument passé ne correspond pas à la signature.
- replace(*[, parameters][, return_annotation])¶
Create a new
Signature
instance based on the instancereplace()
was invoked on. It is possible to pass different parameters and/or return_annotation to override the corresponding properties of the base signature. To removereturn_annotation
from the copiedSignature
, pass inSignature.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'"
Signature
objects are also supported by the generic functioncopy.replace()
.
- format(*, max_width=None)¶
Create a string representation of the
Signature
object.If max_width is passed, the method will attempt to fit the signature into lines of at most max_width characters. If the signature is longer than max_width, all parameters will be on separate lines.
Ajouté dans la version 3.13.
- classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)¶
Return a
Signature
(or its subclass) object for a given callable obj.This method simplifies subclassing of
Signature
:class MySignature(Signature): pass sig = MySignature.from_callable(sum) assert isinstance(sig, MySignature)
Its behavior is otherwise identical to that of
signature()
.Ajouté dans la version 3.5.
Modifié dans la version 3.10: The globals, locals, and eval_str parameters were added.
- class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)¶
Parameter
objects are immutable. Instead of modifying aParameter
object, you can useParameter.replace()
orcopy.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
(likeParameter.KEYWORD_ONLY
), and support comparison and ordering, in the following order:Nom
Signification
POSITIONAL_ONLY
La valeur doit être donnée comme argument positionnel. Les arguments exclusivement positionnels sont ceux qui apparaissent avant une entrée
/
(si présente) dans une définition de fonction Python.POSITIONAL_OR_KEYWORD
La valeur peut être donnée comme argument nommé ou positionnel (ce qui est l'affectation de variable standard pour les fonctions implémentées en Python).
VAR_POSITIONAL
Un n-uplet d'arguments positionnels qui ne sont affectés à aucun autre paramètre. Cela correspond à un paramètre
*args
dans une définition de fonction Python.KEYWORD_ONLY
La valeur doit être donnée comme argument nommé. Les arguments exclusivement nommés sont ceux qui apparaissent après un
*
ou*args
dans une définition de fonction Python.VAR_KEYWORD
Un dictionnaire d'arguments nommés qui ne sont liés à aucun autre paramètre. Cela correspond à une expression
**kwargs
dans une définition de fonction Python.Example: print all keyword-only arguments without default values:
>>> def foo(a, b, *, c, d=10): ... pass >>> sig = signature(foo) >>> for param in sig.parameters.values(): ... if (param.kind == param.KEYWORD_ONLY and ... param.default is param.empty): ... print('Parameter:', param) Parameter: c
- kind.description¶
Describes an enum value of
Parameter.kind
.Ajouté dans la version 3.8.
Example: print all descriptions of arguments:
>>> def foo(a, b, *, c, d=10): ... pass >>> sig = signature(foo) >>> for param in sig.parameters.values(): ... print(param.kind.description) positional or keyword positional or keyword keyword-only keyword-only
- replace(*[, name][, kind][, default][, annotation])¶
Create a new
Parameter
instance based on the instance replaced was invoked on. To override aParameter
attribute, pass the corresponding argument. To remove a default value or/and an annotation from aParameter
, passParameter.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'"
Parameter
objects are also supported by the generic functioncopy.replace()
.
Modifié dans la version 3.4: In Python 3.3
Parameter
objects were allowed to havename
set toNone
if theirkind
was set toPOSITIONAL_ONLY
. This is no longer permitted.
- class inspect.BoundArguments¶
Le résultat d'un appel à
Signature.bind()
ouSignature.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 dansargs
etkwargs
.Doit être utilisé en combinaison avec
Signature.parameters
pour le traitement d'arguments.Note
Les arguments pour lesquels
Signature.bind()
ouSignature.bind_partial()
supposent une valeur par défaut sont ignorés. Au besoin, utiliserBoundArguments.apply_defaults()
pour les inclure.Modifié dans la version 3.9:
arguments
est maintenant de typedict
. Anciennement, il était de typecollections.OrderedDict
.
- args¶
Un n-uplets des valeurs d'arguments positionnels. Évalué dynamiquement à partir de l'attribut
arguments
.
- kwargs¶
A dict of keyword arguments values. Dynamically computed from the
arguments
attribute. Arguments that can be passed positionally are included inargs
instead.
- apply_defaults()¶
Assigne les valeurs par défaut pour les arguments manquants.
Pour les arguments positionnels variables (
*args
) la valeur par défaut est un n-uplet vide.Pour les arguments nommés variables (
**kwargs
) la valeur par défaut est un dictionnaire vide.>>> def foo(a, b='ham', *args): pass >>> ba = inspect.signature(foo).bind('spam') >>> ba.apply_defaults() >>> ba.arguments {'a': 'spam', 'b': 'ham', 'args': ()}
Ajouté dans la version 3.5.
The
args
andkwargs
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
*
ouNone
si les arguments positionnels arbitraires ne sont pas acceptés. varkw est le nom du paramètre**
, ouNone
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, ouNone
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 moduleinspect
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'APIgetargspec()
.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**
ouNone
. 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. wheneverfunc(*args, **kwds)
would raise an exception because of incompatible signature, an exception of the same type and the same or similar message is raised. For example:>>> from inspect import getcallargs >>> def f(a, b=1, *pos, **named): ... pass ... >>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)} True >>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()} True >>> getcallargs(f) Traceback (most recent call last): ... TypeError: f() missing 1 required positional argument: 'a'
Ajouté dans la version 3.2.
Obsolète depuis la version 3.5: utilisez plutôt
Signature.bind()
etSignature.bind_partial()
.
- inspect.getclosurevars(func)¶
Obtenir la correspondance de nom de références externes d'une fonction ou méthode Python func avec leur valeur courante. Un n-uplet nommé
ClosureVars(nonlocals, globals, builtins, unbound)
est renvoyé. nonlocals établit une correspondance des noms capturés par les fermetures lexicales, globals au module de la fonction et builtins aux noms natifs visibles depuis le corps de la fonction. unbound est un ensemble de noms référencés dans la fonction ne trouvant aucune résolution dans les valeurs globales du module courant ni à travers le lexique natif.TypeError
est levée si func n'est ni une fonction ni une méthode Python.Ajouté dans la version 3.3.
- inspect.unwrap(func, *, stop=None)¶
Obtenir l'objet englobé par func. Suit une chaîne d'attributs de
__wrapped__
, renvoyant le dernier objet de la chaîne.stop est une fonction de callback optionnelle qui accepte un objet de la chaîne englobée comme son seul argument et permet d'arrêter le déballage avant la fin si la fonction de callback renvoie une valeur vraie. Si la fonction callback ne renvoie jamais une valeur vraie, le dernier objet de la chaîne est renvoyé comme d'habitude. Par exemple,
signature()
utilise ceci pour arrêter le déballage si un objet dans la chaîne définit un attribut__signature__
.ValueError
est levée si un cycle est rencontré.Ajouté dans la version 3.4.
- inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)¶
Compute the annotations dict for an object.
This is an alias for
annotationlib.get_annotations()
; see the documentation of that function for more information.Ajouté dans la version 3.10.
Modifié dans la version 3.14: This function is now an alias for
annotationlib.get_annotations()
. Calling it asinspect.get_annotations
will continue to work.
La pile d'interpréteur¶
Some of the following functions return
FrameInfo
objects. For backwards compatibility these objects allow
tuple-like operations on all attributes except positions
. This behavior
is considered deprecated and may be removed in the future.
- class inspect.FrameInfo¶
- frame¶
The frame object that the record corresponds to.
- filename¶
The file name associated with the code being executed by the frame this record corresponds to.
- lineno¶
The line number of the current line associated with the code being executed by the frame this record corresponds to.
- function¶
The function name that is being executed by the frame this record corresponds to.
- code_context¶
A list of lines of context from the source code that's being executed by the frame this record corresponds to.
- index¶
The index of the current line being executed in the
code_context
list.
- positions¶
A
dis.Positions
object containing the start line number, end line number, start column offset, and end column offset associated with the instruction being executed by the frame this record corresponds to.
Modifié dans la version 3.5: Return a named tuple instead of a
tuple
.Modifié dans la version 3.11:
FrameInfo
is now a class instance (that is backwards compatible with the previous named tuple).
- class inspect.Traceback¶
- filename¶
The file name associated with the code being executed by the frame this traceback corresponds to.
- lineno¶
The line number of the current line associated with the code being executed by the frame this traceback corresponds to.
- function¶
The function name that is being executed by the frame this traceback corresponds to.
- code_context¶
A list of lines of context from the source code that's being executed by the frame this traceback corresponds to.
- index¶
The index of the current line being executed in the
code_context
list.
- positions¶
A
dis.Positions
object containing the start line number, end line number, start column offset, and end column offset associated with the instruction being executed by the frame this traceback corresponds to.
Modifié dans la version 3.11:
Traceback
is now a class instance (that is backwards compatible with the previous named tuple).
Note
Conserver des références à des objets cadre, tel que trouvé dans le 1er élément des enregistrements de cadres que ces fonctions renvoient, peut créer des cycles de référence dans votre programme. Lorsqu'un cycle de référence a été créé, la durée de vie de tous les objets pouvant être accessibles par ces objets peut être grandement augmentée, même si le détecteur de cycle (optionnel) de Python est activé. Si ces cycles doivent être créés, il est important de s'assurer qu'ils soient explicitement brisés pour éviter la destruction reportée des objets et l'augmentation résultante de l'utilisation de la mémoire.
Bien que le détecteur trouvera ces cycles, la destruction des cadres (et variables locales) peut être fait de manière déterministe en enlevant les cycles dans une clause finally
. Cela est important si le détecteur de cycle a été désactivé lors de la compilation du code Python ou en utilisant gc.disable()
. Par exemple :
def handle_stackframe_without_leak():
frame = inspect.currentframe()
try:
# do something with the frame
finally:
del frame
Pour conserver ces cadres (par exemple pour imprimer une trace d'exécution plus tard), vous pouvez briser ces cycles de référence en utilisant la méthode frame.clear()
.
L'argument optionnel context supporté par la plupart de ces méthodes spécifie le nombre de lignes de contexte à renvoyer, qui sera centré autour de la ligne courante.
- inspect.getframeinfo(frame, context=1)¶
Get information about a frame or traceback object. A
Traceback
object is returned.Modifié dans la version 3.11: A
Traceback
object is returned instead of a named tuple.
- inspect.getouterframes(frame, context=1)¶
Get a list of
FrameInfo
objects for a frame and all outer frames. These frames represent the calls that lead to the creation of frame. The first entry in the returned list represents frame; the last entry represents the outermost call on frame's stack.Modifié dans la version 3.5: une liste de n-uplet nommé
FrameInfo(frame, filename, lineno, function, code_context, index)
est renvoyée.Modifié dans la version 3.11: A list of
FrameInfo
objects is returned.
- inspect.getinnerframes(traceback, context=1)¶
Get a list of
FrameInfo
objects for a traceback's frame and all inner frames. These frames represent calls made as a consequence of frame. The first entry in the list represents traceback; the last entry represents where the exception was raised.Modifié dans la version 3.5: une liste de n-uplet nommé
FrameInfo(frame, filename, lineno, function, code_context, index)
est renvoyée.Modifié dans la version 3.11: A list of
FrameInfo
objects is returned.
- inspect.currentframe()¶
Renvoie l'objet cadre de la pile pour le cadre de l’appelant.
Particularité de l'implémentation CPython : cette fonction nécessite que l'interpréteur Python implémente une pile de cadres d'appel, ce qui n'est pas forcément le cas de toutes les implémentations Python. Si le code s'exécute dans une implémentation Python n'implémentant pas la pile de cadres, cette fonction renvoie
None
.
- inspect.stack(context=1)¶
Return a list of
FrameInfo
objects for the caller's stack. The first entry in the returned list represents the caller; the last entry represents the outermost call on the stack.Modifié dans la version 3.5: une liste de n-uplet nommé
FrameInfo(frame, filename, lineno, function, code_context, index)
est renvoyée.Modifié dans la version 3.11: A list of
FrameInfo
objects is returned.
- inspect.trace(context=1)¶
Return a list of
FrameInfo
objects for the stack between the current frame and the frame in which an exception currently being handled was raised in. The first entry in the list represents the caller; the last entry represents where the exception was raised.Modifié dans la version 3.5: une liste de n-uplet nommé
FrameInfo(frame, filename, lineno, function, code_context, index)
est renvoyée.Modifié dans la version 3.11: A list of
FrameInfo
objects is returned.
Recherche dynamique d'attributs¶
Both getattr()
and hasattr()
can trigger code execution when
fetching or checking for the existence of attributes. Descriptors, like
properties, will be invoked and __getattr__()
and
__getattribute__()
may be called.
Pour les cas où une introspection passive est désirée, comme des outils de documentation, cela peut être inconvenable. getattr_static()
possède la même signature que getattr()
, mais évite l'exécution de code lors de la recherche d'attributs.
- inspect.getattr_static(obj, attr, default=None)¶
Retrieve attributes without triggering dynamic lookup via the descriptor protocol,
__getattr__()
or__getattribute__()
.Note : cette fonction ne retrouve pas forcément tous les attributs renvoyés par getattr (tel que des attributs générés dynamiquement) et pourrait retrouver des attributs non retrouvés par getattr (tel que des descripteurs qui lèvent un AttributeError). Elle peut aussi donner des objets descripteurs, plutôt que des membres d'instance.
Si l'instance
__dict__
est cachée (shadowed) par un autre membre (par exemple une propriété), cette fonction ne pourra pas retrouver les membres de l'instance.Ajouté dans la version 3.2.
getattr_static()
ne résout pas les descripteurs, par exemple slot descriptors ou les descripteurs getset des objets implémentés en C. Le descripteur de l'objet est renvoyé plutôt que l'attribut sous-jacent.
Vous pouvez gérer ces cas à l'aide du code suivant. Notez que pour des descripteurs arbitraires getset les invoquant, de l'exécution de code pourrait être lancée :
# example code for resolving the builtin descriptor types
class _foo:
__slots__ = ['foo']
slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)
result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
try:
result = result.__get__()
except AttributeError:
# descriptors can raise AttributeError to
# indicate there is no underlying value
# in which case the descriptor itself will
# have to do
pass
Current State of Generators, Coroutines, and Asynchronous Generators¶
Lors de l'implémentation d'ordonnanceur de coroutine et autres utilisations avancées de générateurs, il est utile de déterminer si un générateur est présentement en cours d'exécution, en attente de démarrage ou de continuation, ou s'il a déjà terminé. getgeneratorstate()
permet d'aisément déterminer l'état courant d'un générateur.
- inspect.getgeneratorstate(generator)¶
Donne l'état courant d'un générateur-itérateur.
Les états possibles :
GEN_CREATED : En attente de démarrage d'exécution.
GEN_RUNNING : En cours d'exécution par l'interpréteur.
GEN_SUSPENDED : Présentement suspendu à une expression yield.
GEN_CLOSED : L'exécution est complétée.
Ajouté dans la version 3.2.
- inspect.getcoroutinestate(coroutine)¶
Donne l'état courant d'un objet coroutine. L'utilisation est prévue avec des objets coroutine créés avec des fonctions
async def
, mais accepte n'importe quel objet semblable à une coroutine qui définisse des attributscr_running
cr_frame
.Les états possibles :
CORO_CREATED : En attente de démarrage d'exécution.
CORO_RUNNING : En cours d'exécution par l'interpréteur.
CORO_SUSPENDED : Suspendu à une expression await.
CORO_CLOSED : Exécution complétée.
Ajouté dans la version 3.5.
- inspect.getasyncgenstate(agen)¶
Get current state of an asynchronous generator object. The function is intended to be used with asynchronous iterator objects created by
async def
functions which use theyield
statement, but will accept any asynchronous generator-like object that hasag_running
andag_frame
attributes.Les états possibles :
AGEN_CREATED: Waiting to start execution.
AGEN_RUNNING: Currently being executed by the interpreter.
AGEN_SUSPENDED: Currently suspended at a yield expression.
AGEN_CLOSED: Execution has completed.
Ajouté dans la version 3.12.
L'état courant interne du générateur peut aussi être vérifié. Ceci est utile pour des tests, afin d'assurer que l'état interne est mise à jour tel que prévu :
- inspect.getgeneratorlocals(generator)¶
Donne une correspondance de variables locales dans generator avec les valeurs courantes. Un dictionnaire est renvoyé, établissant la correspondance entre variables et valeurs. Ceci est équivalent à appeler
locals()
dans le corps du générateur et les mêmes restrictions s'appliquent.Si generator est un générateur sans cadre courant associé, alors un dictionnaire vide est renvoyé.
TypeError
est levé sir generator n'est pas un objet générateur Python.Particularité de l'implémentation CPython : Cette fonction repose sur l'exposition d'une pile de cadres Python par le générateur pour l'introspection, ce qui n'est pas garanti dans toutes les implémentations Python. Dans un tel cas, cette fonction renvoie toujours un dictionnaire vide.
Ajouté dans la version 3.3.
- inspect.getcoroutinelocals(coroutine)¶
Cette fonction est semblable à
getgeneratorlocals()
, mais fonctionne pour des objets coroutines créés avec des fonctionsasync def
.Ajouté dans la version 3.5.
- inspect.getasyncgenlocals(agen)¶
This function is analogous to
getgeneratorlocals()
, but works for asynchronous generator objects created byasync def
functions which use theyield
statement.Ajouté dans la version 3.12.
Bit d'option des objets code¶
Python code objects have a co_flags
attribute,
which is a bitmap of the following flags:
- inspect.CO_OPTIMIZED¶
L'objet code est optimisé, utilisant des variables locales rapides.
- inspect.CO_NEWLOCALS¶
If set, a new dict will be created for the frame's
f_locals
when the code object is executed.
- inspect.CO_VARARGS¶
L'objet code possède un paramètre de variable positionnel (
*args
ou semblable).
- inspect.CO_VARKEYWORDS¶
L'objet code possède une paramètre par mot-clé variable (
**kwargs
ou semblable).
- inspect.CO_NESTED¶
L'option est définie lorsque le code est une fonction imbriquée.
- inspect.CO_GENERATOR¶
L'option est définie lorsque l'objet code est une fonction génératrice, c'est-à-dire qu'un objet générateur est renvoyé lorsque le code objet est exécuté.
- inspect.CO_COROUTINE¶
L'option est définie lorsque le code objet est une fonction coroutine. Lors que le code objet est exécuté, il renvoie un objet coroutine. Voir PEP 492 pour plus de détails.
Ajouté dans la version 3.5.
- inspect.CO_ITERABLE_COROUTINE¶
L'option est utilisée pour transformer un générateur en une coroutine basée sur un générateur. Les objets générateurs avec cette option peuvent être utilisés dans une expression
await
et un objet coroutineyield from
. Voir PEP 492 pour plus de détails.Ajouté dans la version 3.5.
- inspect.CO_ASYNC_GENERATOR¶
L'option est définie lorsque l'objet code est une fonction génératrice asynchrone. Lorsque l'objet code est exécuté, il renvoie un objet générateur asynchrone. Voir PEP 525 pour les détails.
Ajouté dans la version 3.6.
Note
Ces options sont spécifiques à CPython et pourraient ne pas être définies dans d'autres implémentations Python. De plus, les options constituent des détails d'implémentation et pourraient être enlevées ou dépréciées dans des versions ultérieures. Il est recommandé d'utiliser les APIs publiques de inspect
pour tous les besoins d'introspection.
Buffer flags¶
- class inspect.BufferFlags¶
This is an
enum.IntFlag
that represents the flags that can be passed to the__buffer__()
method of objects implementing the buffer protocol.The meaning of the flags is explained at Buffer request types.
- SIMPLE¶
- WRITABLE¶
- FORMAT¶
- ND¶
- STRIDES¶
- C_CONTIGUOUS¶
- F_CONTIGUOUS¶
- ANY_CONTIGUOUS¶
- INDIRECT¶
- CONTIG¶
- CONTIG_RO¶
- STRIDED¶
- STRIDED_RO¶
- RECORDS¶
- RECORDS_RO¶
- FULL¶
- FULL_RO¶
- READ¶
- WRITE¶
Ajouté dans la version 3.12.
Interface en ligne de commande¶
Le module inspect
fournit également des capacités d'introspection de base en ligne de commande.
Par défaut, il accepte le nom d'un module et affiche la source de ce module. Une classe ou fonction à l'intérieur du module peut également être affichée en ajoutant un ":" et le nom qualifié de l'objet désiré.
- --details¶
Affiche de l'information à propos de l'objet spécifié plutôt que du code source.