`inspect`— Inspect live objects¶

Source code:Lib/inspect.py

Theinspectmodule provides several useful functions to help get information about live objects such as modules, classes, methods, functions, tracebacks, frame objects, and code objects. For example, it can help you examine the contents of a class, retrieve the source code of a method, extract and format the argument list for a function, or get all the information you need to display a detailed traceback.

There are four main kinds of services provided by this module: type checking, getting source code, inspecting classes and functions, and examining the interpreter stack.

Types and members¶

Thegetmembers()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 togetmembers(). They also help you determine when you can expect to find the following special attributes (seeImport-related module attributesfor module attributes):

Type	Attribute	Description
class	__doc__	documentation string
	__name__	name with which this class was defined
	__qualname__	qualified name
	__module__	name of module in which this class was defined
	__type_params__	A tuple containing the type parametersof a generic class
method	__doc__	documentation string
	__name__	name with which this method was defined
	__qualname__	qualified name
	__func__	function object containing implementation of method
	__self__	instance to which this method is bound, or `None`
	__module__	name of module in which this method was defined
function	__doc__	documentation string
	__name__	name with which this function was defined
	__qualname__	qualified name
	__code__	code object containing compiled function bytecode
	__defaults__	tuple of any default values for positional or keyword parameters
	__kwdefaults__	mapping of any default values for keyword-only parameters
	__globals__	global namespace in which this function was defined
	__builtins__	builtins namespace
	__annotations__	mapping of parameters names to annotations; `"return"`key is reserved for return annotations.
	__type_params__	A tuple containing the type parametersof a generic function
	__module__	name of module in which this function was defined
traceback	tb_frame	frame object at this level
	tb_lasti	index of last attempted instruction in bytecode
	tb_lineno	current line number in Python source code
	tb_next	next inner traceback object (called by this level)
frame	f_back	next outer frame object (this frame’s caller)
	f_builtins	builtins namespace seen by this frame
	f_code	code object being executed in this frame
	f_globals	global namespace seen by this frame
	f_lasti	index of last attempted instruction in bytecode
	f_lineno	current line number in Python source code
	f_locals	local namespace seen by this frame
	f_trace	tracing function for this frame, or`None`
code	co_argcount	number of arguments (not including keyword only arguments, * or ** args)
	co_code	string of raw compiled bytecode
	co_cellvars	tuple of names of cell variables (referenced by containing scopes)
	co_consts	tuple of constants used in the bytecode
	co_filename	name of file in which this code object was created
	co_firstlineno	number of first line in Python source code
	co_flags	bitmap of`CO_*`flags, read morehere
	co_lnotab	encoded mapping of line numbers to bytecode indices
	co_freevars	tuple of names of free variables (referenced via a function’s closure)
	co_posonlyargcount	number of positional only arguments
	co_kwonlyargcount	number of keyword only arguments (not including ** arg)
	co_name	name with which this code object was defined
	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	number of local variables
	co_stacksize	virtual machine stack space required
	co_varnames	tuple of names of arguments and local variables
generator	__name__	name
	__qualname__	qualified name
	gi_frame	frame
	gi_running	is the generator running?
	gi_code	code
	gi_yieldfrom	object being iterated by `yieldfrom`,or `None`
async generator	__name__	name
	__qualname__	qualified name
	ag_await	object being awaited on, or`None`
	ag_frame	frame
	ag_running	is the generator running?
	ag_code	code
coroutine	__name__	name
	__qualname__	qualified name
	cr_await	object being awaited on, or`None`
	cr_frame	frame
	cr_running	is the coroutine running?
	cr_code	code
	cr_origin	where coroutine was created, or`None`.See `sys.set_coroutine_origin_tracking_depth()`
builtin	__doc__	documentation string
	__name__	original name of this function or method
	__qualname__	qualified name
	__self__	instance to which a method is bound, or `None`

Changed in version 3.5:Add__qualname__andgi_yieldfromattributes to generators.

The__name__attribute of generators is now set from the function name, instead of the code name, and it can now be modified.

Changed in version 3.7:Addcr_originattribute to coroutines.

Changed in version 3.10:Add__builtins__attribute to functions.

inspect.getmembers(object[,predicate])¶: Return all the members of an object in a list of(name,value) pairs sorted by name. If the optionalpredicateargument—which will be called with thevalueobject of each member—is supplied, only members for which the predicate returns a true value are included.

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.

Added in version 3.11.

inspect.getmodulename(path)¶

Return the name of the module named by the filepath,without including the names of enclosing packages. The file extension is checked against all of the entries inimportlib.machinery.all_suffixes().If it matches, the final path component is returned with the extension removed. Otherwise,Noneis returned.

Note that this functiononlyreturns a meaningful name for actual Python modules - paths that potentially refer to Python packages will still returnNone.

Changed in version 3.3:The function is based directly onimportlib.

inspect.ismodule(object)¶: ReturnTrueif the object is a module.

inspect.isclass(object)¶: ReturnTrueif the object is a class, whether built-in or created in Python code.

inspect.ismethod(object)¶: ReturnTrueif the object is a bound method written in Python.

inspect.isfunction(object)¶: ReturnTrueif the object is a Python function, which includes functions created by alambdaexpression.

inspect.isgeneratorfunction(object)¶: ReturnTrueif the object is a Python generator function.

Changed in version 3.8:Functions wrapped infunctools.partial()now returnTrueif the wrapped function is a Python generator function.

inspect.isgenerator(object)¶: ReturnTrueif the object is a generator.

inspect.iscoroutinefunction(object)¶: ReturnTrueif the object is acoroutine function(a function defined with anasyncdefsyntax), afunctools.partial() wrapping acoroutine function,or a sync function marked with markcoroutinefunction().

Added in version 3.5.

Changed in version 3.8:Functions wrapped infunctools.partial()now returnTrueif the wrapped function is acoroutine function.

Changed in version 3.12:Sync functions marked withmarkcoroutinefunction()now return True.

inspect.markcoroutinefunction(func)¶

Decorator to mark a callable as acoroutine functionif it would not otherwise be detected byiscoroutinefunction().

This may be of use for sync functions that return acoroutine,if the function is passed to an API that requiresiscoroutinefunction().

When possible, using anasyncdeffunction is preferred. Also acceptable is calling the function and testing the return with iscoroutine().

Added in version 3.12.

inspect.iscoroutine(object)¶: ReturnTrueif the object is acoroutinecreated by an asyncdeffunction.

Added in version 3.5.

inspect.isawaitable(object)¶

ReturnTrueif the object can be used inawaitexpression.

Can also be used to distinguish generator-based coroutines from regular generators:

importtypes

defgen():
yield
@types.coroutine
defgen_coro():
yield

assertnotisawaitable(gen())
assertisawaitable(gen_coro())

Added in version 3.5.

inspect.isasyncgenfunction(object)¶

ReturnTrueif the object is anasynchronous generatorfunction, for example:

>>>asyncdefagen():
...yield1
...
>>>inspect.isasyncgenfunction(agen)
True

Added in version 3.6.

Changed in version 3.8:Functions wrapped infunctools.partial()now returnTrueif the wrapped function is anasynchronous generatorfunction.

inspect.isasyncgen(object)¶: ReturnTrueif the object is anasynchronous generator iterator created by anasynchronous generatorfunction.

Added in version 3.6.

inspect.istraceback(object)¶: ReturnTrueif the object is a traceback.

inspect.isframe(object)¶: ReturnTrueif the object is a frame.

inspect.iscode(object)¶: ReturnTrueif the object is a code.

inspect.isbuiltin(object)¶: ReturnTrueif the object is a built-in function or a bound built-in method.

inspect.ismethodwrapper(object)¶

ReturnTrueif the type of object is aMethodWrapperType.

These are instances ofMethodWrapperType,such as__str__(), __eq__()and__repr__().

Added in version 3.11.

inspect.isroutine(object)¶: ReturnTrueif the object is a user-defined or built-in function or method.

inspect.isabstract(object)¶: ReturnTrueif the object is an abstract base class.

inspect.ismethoddescriptor(object)¶

ReturnTrueif the object is a method descriptor, but not if ismethod(),isclass(),isfunction()orisbuiltin() are true.

This, for example, is true ofint.__add__.An object passing this test has a__get__()method but not a__set__() method, but beyond that the set of attributes varies. A __name__attribute is usually sensible, and__doc__often is.

Methods implemented via descriptors that also pass one of the other tests returnFalsefrom theismethoddescriptor()test, simply because the other tests promise more – you can, e.g., count on having the __func__attribute (etc) when an object passes ismethod().

inspect.isdatadescriptor(object)¶

ReturnTrueif the object is a data descriptor.

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)¶: ReturnTrueif the object is a getset descriptor.

CPython implementation detail:getsets are attributes defined in extension modules via PyGetSetDefstructures. For Python implementations without such types, this method will always returnFalse.

inspect.ismemberdescriptor(object)¶: ReturnTrueif the object is a member descriptor.

CPython implementation detail:Member descriptors are attributes defined in extension modules via PyMemberDefstructures. For Python implementations without such types, this method will always returnFalse.

Retrieving source code¶

inspect.getdoc(object)¶: Get the documentation string for an object, cleaned up withcleandoc(). 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. ReturnNoneif the documentation string is invalid or missing.

Changed in version 3.5:Documentation strings are now inherited if not overridden.

inspect.getcomments(object)¶: Return in a single string any lines of comments immediately preceding the object’s source code (for a class, function, or method), or at the top of the Python source file (if the object is a module). If the object’s source code is unavailable, returnNone.This could happen if the object has been defined in C or the interactive shell.

inspect.getfile(object)¶: Return the name of the (text or binary) file in which an object was defined. This will fail with aTypeErrorif the object is a built-in module, class, or function.

inspect.getmodule(object)¶: Try to guess which module an object was defined in. ReturnNone if the module cannot be determined.

inspect.getsourcefile(object)¶: Return the name of the Python source file in which an object was defined orNoneif no way can be identified to get the source. This will fail with aTypeErrorif 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. AnOSErroris raised if the source code cannot be retrieved. ATypeErroris raised if the object is a built-in module, class, or function.

Changed in version 3.3:OSErroris raised instead ofIOError,now an alias of the former.

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. AnOSErroris raised if the source code cannot be retrieved. ATypeErroris raised if the object is a built-in module, class, or function.

Changed in version 3.3:OSErroris raised instead ofIOError,now an alias of the former.

inspect.cleandoc(doc)¶

Clean up indentation from docstrings that are indented to line up with blocks of code.

All leading whitespace is removed from the first line. Any leading whitespace that can be uniformly removed from the second line onwards is removed. Empty lines at the beginning and end are subsequently removed. Also, all tabs are expanded to spaces.

Introspecting callables with the Signature object¶

Added in version 3.3.

TheSignatureobject represents the call signature of a callable object and its return annotation. To retrieve aSignatureobject, use thesignature() function.

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

Return aSignatureobject for the givencallable:

>>>frominspectimportsignature
>>>deffoo(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'>

Accepts a wide range of Python callables, from plain functions and classes to functools.partial()objects.

For objects defined in modules using stringized annotations (from__future__importannotations),signature()will attempt to automatically un-stringize the annotations using get_annotations().The globals,locals,andeval_strparameters are passed intoget_annotations()when resolving the annotations; see the documentation forget_annotations() for instructions on how to use these parameters.

RaisesValueErrorif no signature can be provided, and TypeErrorif that type of object is not supported. Also, if the annotations are stringized, andeval_stris not false, theeval()call(s) to un-stringize the annotations inget_annotations() could potentially raise any kind of exception.

A slash(/) in the signature of a function denotes that the parameters prior to it are positional-only. For more info, see the FAQ entry on positional-only parameters.

Changed in version 3.5:Thefollow_wrappedparameter was added. PassFalseto get a signature of callablespecifically (callable.__wrapped__will not be used to unwrap decorated callables.)

Changed in version 3.10:Theglobals,locals,andeval_strparameters were added.

Note

Some callables may not be introspectable in certain implementations of Python. For example, in CPython, some built-in functions defined in C provide no metadata about their arguments.

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

classinspect.Signature(parameters=None,*,return_annotation=Signature.empty)¶

ASignatureobject represents the call signature of a function and its return annotation. For each parameter accepted by the function it stores a Parameterobject in itsparameterscollection.

The optionalparametersargument is a sequence ofParameter objects, which is validated to check that there are no parameters with duplicate names, and that the parameters are in the right order, i.e. positional-only first, then positional-or-keyword, and that parameters with defaults follow parameters without defaults.

The optionalreturn_annotationargument can be an arbitrary Python object. It represents the “return” annotation of the callable.

Signatureobjects areimmutable.UseSignature.replace()to make a modified copy.

Changed in version 3.5:Signatureobjects are now picklable andhashable.

empty¶: A special class-level marker to specify absence of a return annotation.

parameters¶: An ordered mapping of parameters’ names to the corresponding Parameterobjects. Parameters appear in strict definition order, including keyword-only parameters.

Changed in version 3.7:Python only explicitly guaranteed that it preserved the declaration order of keyword-only parameters as of version 3.7, although in practice this order had always been preserved in Python 3.

return_annotation¶: The “return” annotation for the callable. If the callable has no “return” annotation, this attribute is set toSignature.empty.

bind(*args,**kwargs)¶: Create a mapping from positional and keyword arguments to parameters. ReturnsBoundArgumentsif*argsand**kwargsmatch the signature, or raises aTypeError.

bind_partial(*args,**kwargs)¶: Works the same way asSignature.bind(),but allows the omission of some required arguments (mimicsfunctools.partial()behavior.) ReturnsBoundArguments,or raises aTypeErrorif the passed arguments do not match the signature.

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

Create a newSignatureinstance based on the instance replace()was invoked on. It is possible to pass differentparametersand/or return_annotationto override the corresponding properties of the base signature. To removereturn_annotationfrom the copied Signature,pass in Signature.empty.

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

classmethodfrom_callable(obj,*,follow_wrapped=True,globals=None,locals=None,eval_str=False)¶

Return aSignature(or its subclass) object for a given callable obj.

This method simplifies subclassing ofSignature:

classMySignature(Signature):
pass
sig=MySignature.from_callable(sum)
assertisinstance(sig,MySignature)

Its behavior is otherwise identical to that ofsignature().

Added in version 3.5.

Changed in version 3.10:Theglobals,locals,andeval_strparameters were added.

classinspect.Parameter(name,kind,*,default=Parameter.empty,annotation=Parameter.empty)¶

Parameterobjects areimmutable. Instead of modifying aParameterobject, you can useParameter.replace()to create a modified copy.

Changed in version 3.5:Parameter objects are now picklable andhashable.

empty¶: A special class-level marker to specify absence of default values and annotations.

name¶: The name of the parameter as a string. The name must be a valid Python identifier.

CPython implementation detail:CPython generates implicit parameter names of the form.0on the code objects used to implement comprehensions and generator expressions.

Changed in version 3.6:These parameter names are now exposed by this module as names like implicit0.

default¶: The default value for the parameter. If the parameter has no default value, this attribute is set toParameter.empty.

annotation¶: The annotation for the parameter. If the parameter has no annotation, this attribute is set toParameter.empty.

kind¶

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

Name	Meaning
POSITIONAL_ONLY	Value must be supplied as a positional argument. Positional only parameters are those which appear before a`/`entry (if present) in a Python function definition.
POSITIONAL_OR_KEYWORD	Value may be supplied as either a keyword or positional argument (this is the standard binding behaviour for functions implemented in Python.)
VAR_POSITIONAL	A tuple of positional arguments that aren’t bound to any other parameter. This corresponds to a`*args`parameter in a Python function definition.
KEYWORD_ONLY	Value must be supplied as a keyword argument. Keyword only parameters are those which appear after a``or`args`entry in a Python function definition.
VAR_KEYWORD	A dict of keyword arguments that aren’t bound to any other parameter. This corresponds to a `**kwargs`parameter in a Python function definition.

Example: print all keyword-only arguments without default values:

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

>>>sig=signature(foo)
>>>forparaminsig.parameters.values():
...if(param.kind==param.KEYWORD_ONLYand
...param.defaultisparam.empty):
...print('Parameter:',param)
Parameter: c

kind.description¶

Describes an enum value ofParameter.kind.

Added in version 3.8.

Example: print all descriptions of arguments:

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

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

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

Create a newParameterinstance based on the instance replaced was invoked on. To override aParameterattribute, pass the corresponding argument. To remove a default value or/and an annotation from a Parameter,passParameter.empty.

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

Changed in version 3.4:In Python 3.3Parameterobjects were allowed to havenameset toNoneif theirkindwas set toPOSITIONAL_ONLY. This is no longer permitted.

classinspect.BoundArguments¶

Result of aSignature.bind()orSignature.bind_partial()call. Holds the mapping of arguments to the function’s parameters.

arguments¶

A mutable mapping of parameters’ names to arguments’ values. Contains only explicitly bound arguments. Changes inarguments will reflect inargsandkwargs.

Should be used in conjunction withSignature.parametersfor any argument processing purposes.

Note

Arguments for whichSignature.bind()or Signature.bind_partial()relied on a default value are skipped. However, if needed, useBoundArguments.apply_defaults()to add them.

Changed in version 3.9:argumentsis now of typedict.Formerly, it was of typecollections.OrderedDict.

args¶: A tuple of positional arguments values. Dynamically computed from the argumentsattribute.

kwargs¶: A dict of keyword arguments values. Dynamically computed from the argumentsattribute. Arguments that can be passed positionally are included inargsinstead.

signature¶: A reference to the parentSignatureobject.

apply_defaults()¶

Set default values for missing arguments.

For variable-positional arguments (*args) the default is an empty tuple.

For variable-keyword arguments (**kwargs) the default is an empty dict.

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

Added in version 3.5.

Theargsandkwargsproperties can be used to invoke functions:

deftest(a,*,b):
...

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

Classes and functions¶

inspect.getclasstree(classes,unique=False)¶: Arrange the given list of classes into a hierarchy of nested lists. Where a nested list appears, it contains classes derived from the class whose entry immediately precedes the list. Each entry is a 2-tuple containing a class and a tuple of its base classes. If theuniqueargument is true, exactly one entry appears in the returned structure for each class in the given list. Otherwise, classes using multiple inheritance and their descendants will appear multiple times.

inspect.getfullargspec(func)¶

Get the names and default values of a Python function’s parameters. A named tupleis returned:

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

argsis a list of the positional parameter names. varargsis the name of the*parameter orNoneif arbitrary positional arguments are not accepted. varkwis the name of the**parameter orNoneif arbitrary keyword arguments are not accepted. defaultsis ann-tuple of default argument values corresponding to the lastnpositional parameters, orNoneif there are no such defaults defined. kwonlyargsis a list of keyword-only parameter names in declaration order. kwonlydefaultsis a dictionary mapping parameter names fromkwonlyargs to the default values used if no argument is supplied. annotationsis a dictionary mapping parameter names to annotations. The special key"return"is used to report the function return value annotation (if any).

Note thatsignature()and Signature Objectprovide the recommended API for callable introspection, and support additional behaviours (like positional-only arguments) that are sometimes encountered in extension module APIs. This function is retained primarily for use in code that needs to maintain compatibility with the Python 2inspectmodule API.

Changed in version 3.4:This function is now based onsignature(),but still ignores __wrapped__attributes and includes the already bound first parameter in the signature output for bound methods.

Changed in version 3.6:This method was previously documented as deprecated in favour of signature()in Python 3.5, but that decision has been reversed in order to restore a clearly supported standard interface for single-source Python 2/3 code migrating away from the legacy getargspec()API.

Changed in version 3.7:Python only explicitly guaranteed that it preserved the declaration order of keyword-only parameters as of version 3.7, although in practice this order had always been preserved in Python 3.

inspect.getargvalues(frame)¶: Get information about arguments passed into a particular frame. A named tupleArgInfo(args,varargs,keywords,locals)is returned.argsis a list of the argument names.varargsandkeywords are the names of the*and**arguments orNone.localsis the locals dictionary of the given frame.

Note

This function was inadvertently marked as deprecated in Python 3.5.

inspect.formatargvalues(args[,varargs,varkw,locals,formatarg,formatvarargs,formatvarkw,formatvalue])¶: Format a pretty argument spec from the four values returned by getargvalues().The format* arguments are the corresponding optional formatting functions that are called to turn names and values into strings.

Note

This function was inadvertently marked as deprecated in Python 3.5.

inspect.getmro(cls)¶: Return a tuple of class cls’s base classes, including cls, in method resolution order. No class appears more than once in this tuple. Note that the method resolution order depends on cls’s type. Unless a very peculiar user-defined metatype is in use, cls will be the first element of the tuple.

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

Bind theargsandkwdsto the argument names of the Python function or methodfunc,as if it was called with them. For bound methods, bind also the first argument (typically namedself) to the associated instance. A dict is returned, mapping the argument names (including the names of the*and **arguments, if any) to their values fromargsandkwds.In case of invokingfuncincorrectly, 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:

>>>frominspectimportgetcallargs
>>>deff(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'

Added in version 3.2.

Deprecated since version 3.5:UseSignature.bind()andSignature.bind_partial()instead.

inspect.getclosurevars(func)¶

Get the mapping of external name references in a Python function or methodfuncto their current values. A named tupleClosureVars(nonlocals,globals,builtins,unbound) is returned.nonlocalsmaps referenced names to lexical closure variables,globalsto the function’s module globals andbuiltinsto the builtins visible from the function body.unboundis the set of names referenced in the function that could not be resolved at all given the current module globals and builtins.

TypeErroris raised iffuncis not a Python function or method.

Added in version 3.3.

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

Get the object wrapped byfunc.It follows the chain of__wrapped__ attributes returning the last object in the chain.

stopis an optional callback accepting an object in the wrapper chain as its sole argument that allows the unwrapping to be terminated early if the callback returns a true value. If the callback never returns a true value, the last object in the chain is returned as usual. For example, signature()uses this to stop unwrapping if any object in the chain has a__signature__attribute defined.

ValueErroris raised if a cycle is encountered.

Added in version 3.4.

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

Compute the annotations dict for an object.

objmay be a callable, class, or module. Passing in an object of any other type raisesTypeError.

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:

Ifeval_stris true, values of typestrwill be un-stringized usingeval().This is intended for use with stringized annotations (from__future__importannotations).
Ifobjdoesn’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 usinggetattr()anddict.get()for safety.
Always, always, always returns a freshly created dict.

eval_strcontrols whether or not values of typestrare replaced with the result of callingeval()on those values:

If eval_str is true,eval()is called on values of typestr. (Note thatget_annotationsdoesn’t catch exceptions; ifeval() raises an exception, it will unwind the stack past theget_annotations call.)
If eval_str is false (the default), values of typestrare unchanged.

globalsandlocalsare passed in toeval();see the documentation foreval()for more information. Ifglobalsorlocals isNone,this function may replace that value with a context-specific default, contingent ontype(obj):

Ifobjis a module,globalsdefaults toobj.__dict__.
Ifobjis a class,globalsdefaults to sys.modules[obj.__module__].__dict__andlocalsdefaults to theobjclass namespace.
Ifobjis a callable,globalsdefaults to obj.__globals__, although ifobjis a wrapped function (using functools.update_wrapper()) it is first unwrapped.

Callingget_annotationsis best practice for accessing the annotations dict of any object. SeeAnnotations Best Practicesfor more information on annotations best practices.

Added in version 3.10.

The interpreter stack¶

Some of the following functions return FrameInfoobjects. For backwards compatibility these objects allow tuple-like operations on all attributes exceptpositions.This behavior is considered deprecated and may be removed in the future.

classinspect.FrameInfo¶

frame¶: Theframe objectthat 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 thecode_contextlist.

positions¶: Adis.Positionsobject 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.

Changed in version 3.5:Return anamed tupleinstead of atuple.

Changed in version 3.11:FrameInfois now a class instance (that is backwards compatible with the previousnamed tuple).

classinspect.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 thecode_contextlist.

positions¶: Adis.Positionsobject 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.

Changed in version 3.11:Tracebackis now a class instance (that is backwards compatible with the previousnamed tuple).

Note

Keeping references to frame objects, as found in the first element of the frame records these functions return, can cause your program to create reference cycles. Once a reference cycle has been created, the lifespan of all objects which can be accessed from the objects which form the cycle can become much longer even if Python’s optional cycle detector is enabled. If such cycles must be created, it is important to ensure they are explicitly broken to avoid the delayed destruction of objects and increased memory consumption which occurs.

Though the cycle detector will catch these, destruction of the frames (and local variables) can be made deterministic by removing the cycle in a finallyclause. This is also important if the cycle detector was disabled when Python was compiled or usinggc.disable().For example:

defhandle_stackframe_without_leak():
frame=inspect.currentframe()
try:
# do something with the frame
finally:
delframe

If you want to keep the frame around (for example to print a traceback later), you can also break reference cycles by using the frame.clear()method.

The optionalcontextargument supported by most of these functions specifies the number of lines of context to return, which are centered around the current line.

inspect.getframeinfo(frame,context=1)¶: Get information about a frame or traceback object. ATracebackobject is returned.

Changed in version 3.11:ATracebackobject is returned instead of a named tuple.

inspect.getouterframes(frame,context=1)¶: Get a list ofFrameInfoobjects for a frame and all outer frames. These frames represent the calls that lead to the creation offrame.The first entry in the returned list representsframe;the last entry represents the outermost call onframe’s stack.

Changed in version 3.5:A list ofnamed tuples FrameInfo(frame,filename,lineno,function,code_context,index) is returned.

Changed in version 3.11:A list ofFrameInfoobjects is returned.

inspect.getinnerframes(traceback,context=1)¶: Get a list ofFrameInfoobjects for a traceback’s frame and all inner frames. These frames represent calls made as a consequence offrame. The first entry in the list representstraceback;the last entry represents where the exception was raised.

Changed in version 3.5:A list ofnamed tuples FrameInfo(frame,filename,lineno,function,code_context,index) is returned.

Changed in version 3.11:A list ofFrameInfoobjects is returned.

inspect.currentframe()¶: Return the frame object for the caller’s stack frame.

CPython implementation detail:This function relies on Python stack frame support in the interpreter, which isn’t guaranteed to exist in all implementations of Python. If running in an implementation without Python stack frame support this function returnsNone.

inspect.stack(context=1)¶: Return a list ofFrameInfoobjects 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.

Changed in version 3.5:A list ofnamed tuples FrameInfo(frame,filename,lineno,function,code_context,index) is returned.

Changed in version 3.11:A list ofFrameInfoobjects is returned.

inspect.trace(context=1)¶: Return a list ofFrameInfoobjects 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.

Changed in version 3.5:A list ofnamed tuples FrameInfo(frame,filename,lineno,function,code_context,index) is returned.

Changed in version 3.11:A list ofFrameInfoobjects is returned.

Fetching attributes statically¶

Bothgetattr()andhasattr()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.

For cases where you want passive introspection, like documentation tools, this can be inconvenient.getattr_static()has the same signature asgetattr() but avoids executing code when it fetches attributes.

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

Retrieve attributes without triggering dynamic lookup via the descriptor protocol,__getattr__() or__getattribute__().

Note: this function may not be able to retrieve all attributes that getattr can fetch (like dynamically created attributes) and may find attributes that getattr can’t (like descriptors that raise AttributeError). It can also return descriptors objects instead of instance members.

If the instance__dict__is shadowed by another member (for example a property) then this function will be unable to find instance members.

Added in version 3.2.

getattr_static()does not resolve descriptors, for example slot descriptors or getset descriptors on objects implemented in C. The descriptor object is returned instead of the underlying attribute.

You can handle these with code like the following. Note that for arbitrary getset descriptors invoking these may trigger code execution:

# 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')
iftype(result)indescriptor_types:
try:
result=result.__get__()
exceptAttributeError:
# 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¶

When implementing coroutine schedulers and for other advanced uses of generators, it is useful to determine whether a generator is currently executing, is waiting to start or resume or execution, or has already terminated.getgeneratorstate()allows the current state of a generator to be determined easily.

inspect.getgeneratorstate(generator)¶

Get current state of a generator-iterator.

Possible states are:

GEN_CREATED: Waiting to start execution.
GEN_RUNNING: Currently being executed by the interpreter.
GEN_SUSPENDED: Currently suspended at a yield expression.
GEN_CLOSED: Execution has completed.

Added in version 3.2.

inspect.getcoroutinestate(coroutine)¶

Get current state of a coroutine object. The function is intended to be used with coroutine objects created byasyncdeffunctions, but will accept any coroutine-like object that hascr_runningand cr_frameattributes.

Possible states are:

CORO_CREATED: Waiting to start execution.
CORO_RUNNING: Currently being executed by the interpreter.
CORO_SUSPENDED: Currently suspended at an await expression.
CORO_CLOSED: Execution has completed.

Added in 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 asyncdeffunctions which use theyieldstatement, but will accept any asynchronous generator-like object that has ag_runningandag_frameattributes.

Possible states are:

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.

Added in version 3.12.

The current internal state of the generator can also be queried. This is mostly useful for testing purposes, to ensure that internal state is being updated as expected:

inspect.getgeneratorlocals(generator)¶

Get the mapping of live local variables ingeneratorto their current values. A dictionary is returned that maps from variable names to values. This is the equivalent of callinglocals()in the body of the generator, and all the same caveats apply.

Ifgeneratoris ageneratorwith no currently associated frame, then an empty dictionary is returned.TypeErroris raised if generatoris not a Python generator object.

CPython implementation detail:This function relies on the generator exposing a Python stack frame for introspection, which isn’t guaranteed to be the case in all implementations of Python. In such cases, this function will always return an empty dictionary.

Added in version 3.3.

inspect.getcoroutinelocals(coroutine)¶: This function is analogous togetgeneratorlocals(),but works for coroutine objects created byasyncdeffunctions.

Added in version 3.5.

inspect.getasyncgenlocals(agen)¶: This function is analogous togetgeneratorlocals(),but works for asynchronous generator objects created byasyncdef functions which use theyieldstatement.

Added in version 3.12.

Code Objects Bit Flags¶

Python code objects have aco_flagsattribute, which is a bitmap of the following flags:

inspect.CO_OPTIMIZED¶: The code object is optimized, using fast locals.

inspect.CO_NEWLOCALS¶: If set, a new dict will be created for the frame’sf_locals when the code object is executed.

inspect.CO_VARARGS¶: The code object has a variable positional parameter (*args-like).

inspect.CO_VARKEYWORDS¶: The code object has a variable keyword parameter (**kwargs-like).

inspect.CO_NESTED¶: The flag is set when the code object is a nested function.

inspect.CO_GENERATOR¶: The flag is set when the code object is a generator function, i.e. a generator object is returned when the code object is executed.

inspect.CO_COROUTINE¶: The flag is set when the code object is a coroutine function. When the code object is executed it returns a coroutine object. SeePEP 492for more details.

Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE¶: The flag is used to transform generators into generator-based coroutines. Generator objects with this flag can be used in awaitexpression, and canyieldfromcoroutine objects. SeePEP 492for more details.

Added in version 3.5.

inspect.CO_ASYNC_GENERATOR¶: The flag is set when the code object is an asynchronous generator function. When the code object is executed it returns an asynchronous generator object. SeePEP 525for more details.

Added in version 3.6.

Note

The flags are specific to CPython, and may not be defined in other Python implementations. Furthermore, the flags are an implementation detail, and can be removed or deprecated in future Python releases. It’s recommended to use public APIs from theinspectmodule for any introspection needs.

Buffer flags¶

classinspect.BufferFlags¶

This is anenum.IntFlagthat represents the flags that can be passed to the__buffer__()method of objects implementing thebuffer protocol.

The meaning of the flags is explained atBuffer 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¶

Added in version 3.12.

Command Line Interface¶

Theinspectmodule also provides a basic introspection capability from the command line.

By default, accepts the name of a module and prints the source of that module. A class or function within the module can be printed instead by appended a colon and the qualified name of the target object.

--details¶: Print information about the specified object rather than the source code

`inspect`— Inspect live objects¶

Types and members¶

Retrieving source code¶

Introspecting callables with the Signature object¶

Classes and functions¶

The interpreter stack¶

Fetching attributes statically¶

Current State of Generators, Coroutines, and Asynchronous Generators¶

Code Objects Bit Flags¶

Buffer flags¶

Command Line Interface¶

Table of Contents

Previous topic

Next topic

This Page

inspect— Inspect live objects¶

Types and members¶

Retrieving source code¶

Introspecting callables with the Signature object¶

Classes and functions¶

The interpreter stack¶

Fetching attributes statically¶

Current State of Generators, Coroutines, and Asynchronous Generators¶

Code Objects Bit Flags¶

Buffer flags¶

Command Line Interface¶

`inspect`— Inspect live objects¶