28.12.1. Types and members¶

Thegetmembers() function retrieves the members of an object such as aclass or module. The sixteen functions whose names begin with “is” are mainlyprovided as convenient choices for the second argument togetmembers().They also help you determine when you can expect to find the following specialattributes:

inspect.getmembers(object[,predicate])¶

Return all the members of an object in a list of (name, value) pairs sorted byname. If the optionalpredicate argument is supplied, only members for whichthe predicate returns a true value are included.

Note

getmembers() does not return metaclass attributes when the argumentis a class (this behavior is inherited from thedir() function).

inspect.getmoduleinfo(path)¶

Returns anamed tupleModuleInfo(name,suffix,mode,module_type)of values that describe how Python will interpret the file identified bypath if it is a module, orNone if it would not be identified as amodule. In that tuple,name is the name of the module without the name ofany enclosing package,suffix is the trailing part of the file name (whichmay not be a dot-delimited extension),mode is theopen() mode thatwould be used ('r' or'rb'), andmodule_type is an integer givingthe type of the module.module_type will have a value which can becompared to the constants defined in theimp module; see thedocumentation for that module for more information on module types.

Deprecated since version 3.3:You may check the file path’s suffix against the supported suffixeslisted inimportlib.machinery to infer the same information.

inspect.getmodulename(path)¶

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

Note that this functiononly returns a meaningful name for actualPython modules - paths that potentially refer to Python packages willstill returnNone.

Changed in version 3.3:This function is now based directly onimportlib rather than thedeprecatedgetmoduleinfo().

inspect.ismodule(object)¶

Return true if the object is a module.

inspect.isclass(object)¶

Return true if the object is a class, whether built-in or created in Pythoncode.

inspect.ismethod(object)¶

Return true if the object is a bound method written in Python.

inspect.isfunction(object)¶

Return true if the object is a Python function, which includes functionscreated by alambda expression.

inspect.isgeneratorfunction(object)¶

Return true if the object is a Python generator function.

inspect.isgenerator(object)¶

Return true if the object is a generator.

inspect.istraceback(object)¶

Return true if the object is a traceback.

inspect.isframe(object)¶

Return true if the object is a frame.

inspect.iscode(object)¶

Return true if the object is a code.

inspect.isbuiltin(object)¶

Return true if the object is a built-in function or a bound built-in method.

inspect.isroutine(object)¶

Return true if the object is a user-defined or built-in function or method.

inspect.isabstract(object)¶

Return true if the object is an abstract base class.

inspect.ismethoddescriptor(object)¶

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

This, for example, is true ofint.__add__. An object passing this testhas a__get__ attribute but not a__set__ attribute, butbeyond that the set of attributes varies.__name__ is usuallysensible, and__doc__ often is.

Methods implemented via descriptors that also pass one of the other testsreturn false from theismethoddescriptor() test, simply because theother tests promise more – you can, e.g., count on having the__func__ attribute (etc) when an object passesismethod().

inspect.isdatadescriptor(object)¶

Return true if the object is a data descriptor.

Data descriptors have both a__get__ and a__set__ attribute.Examples are properties (defined in Python), getsets, and members. Thelatter two are defined in C and there are more specific tests available forthose types, which is robust across Python implementations. Typically, datadescriptors will also have__name__ and__doc__ attributes(properties, getsets, and members have both of these attributes), but this isnot guaranteed.

inspect.isgetsetdescriptor(object)¶

Return true if the object is a getset descriptor.

CPython implementation detail: getsets are attributes defined in extension modules viaPyGetSetDef structures. For Python implementations without suchtypes, this method will always returnFalse.

inspect.ismemberdescriptor(object)¶

Return true if the object is a member descriptor.

CPython implementation detail: Member descriptors are attributes defined in extension modules viaPyMemberDef structures. For Python implementations without suchtypes, this method will always returnFalse.

28.12.2. Retrieving source code¶

inspect.getdoc(object)¶

Get the documentation string for an object, cleaned up withcleandoc().

inspect.getcomments(object)¶

Return in a single string any lines of comments immediately preceding theobject’s source code (for a class, function, or method), or at the top of thePython source file (if the object is a module).

inspect.getfile(object)¶

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

inspect.getmodule(object)¶

Try to guess which module an object was defined in.

inspect.getsourcefile(object)¶

Return the name of the Python source file in which an object was defined. Thiswill fail with aTypeError if the object is a built-in module, class, orfunction.

inspect.getsourcelines(object)¶

Return a list of source lines and starting line number for an object. Theargument may be a module, class, method, function, traceback, frame, or codeobject. The source code is returned as a list of the lines corresponding to theobject and the line number indicates where in the original source file the firstline of code was found. AnOSError is raised if the source code cannotbe retrieved.

Changed in version 3.3:OSError is raised instead ofIOError, now an alias of theformer.

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 isreturned as a single string. AnOSError is raised if the source codecannot be retrieved.

Changed in version 3.3:OSError is raised instead ofIOError, now an alias of theformer.

inspect.cleandoc(doc)¶

Clean up indentation from docstrings that are indented to line up with blocksof code. Any whitespace that can be uniformly removed from the second lineonwards is removed. Also, all tabs are expanded to spaces.

28.12.3. Introspecting callables with the Signature object¶

The Signature object represents the call signature of a callable object and itsreturn annotation. To retrieve a Signature object, use thesignature()function.

inspect.signature(callable)¶

Return aSignature object 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 tofunctools.partial() objects.

Note

Some callables may not be introspectable in certain implementations ofPython. For example, in CPython, built-in functions defined in C provideno metadata about their arguments.

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

A Signature object represents the call signature of a function and its returnannotation. For each parameter accepted by the function it stores aParameter object in itsparameters collection.

The optionalparameters argument is a sequence ofParameterobjects, which is validated to check that there are no parameters withduplicate names, and that the parameters are in the right order, i.e.positional-only first, then positional-or-keyword, and that parameters withdefaults follow parameters without defaults.

The optionalreturn_annotation argument, can be an arbitrary Python object,is the “return” annotation of the callable.

Signature objects areimmutable. UseSignature.replace() to make amodified copy.

empty¶

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

parameters¶

An ordered mapping of parameters’ names to the correspondingParameter objects.

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.ReturnsBoundArguments if*args and**kwargs match thesignature, or raises aTypeError.

bind_partial(*args,**kwargs)¶

Works the same way asSignature.bind(), but allows the omission ofsome required arguments (mimicsfunctools.partial() behavior.)ReturnsBoundArguments, or raises aTypeError if thepassed arguments do not match the signature.

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

Create a new Signature instance based on the instance replace was invokedon. It is possible to pass differentparameters and/orreturn_annotation to override the corresponding properties of the basesignature. To remove return_annotation from the copied Signature, pass inSignature.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'"

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

Parameter objects areimmutable. Instead of modifying a Parameter object,you can useParameter.replace() to create a modified copy.

empty¶

A special class-level marker to specify absence of default values andannotations.

name¶

The name of the parameter as a string. Must be a valid python identifiername (with the exception ofPOSITIONAL_ONLY parameters, which can haveit set toNone).

default¶

The default value for the parameter. If the parameter has no defaultvalue, 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. Possible values(accessible viaParameter, likeParameter.KEYWORD_ONLY):

Name	Meaning
POSITIONAL_ONLY	Value must be supplied as a positionalargument. Python has no explicit syntax for definingpositional-only parameters, but many built-inand extension module functions (especiallythose that accept only one or two parameters)accept them.
POSITIONAL_OR_KEYWORD	Value may be supplied as either a keyword orpositional argument (this is the standardbinding behaviour for functions implementedin Python.)
VAR_POSITIONAL	A tuple of positional arguments that aren’tbound to any other parameter. Thiscorresponds to a*args parameter in aPython function definition.
KEYWORD_ONLY	Value must be supplied as a keyword argument.Keyword only parameters are those whichappear after a* or*args entry in aPython function definition.
VAR_KEYWORD	A dict of keyword arguments that aren’t boundto any other parameter. This corresponds to a**kwargs parameter in a Python functiondefinition.

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

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

Create a new Parameter instance based on the instance replaced was invokedon. To override aParameter attribute, pass the correspondingargument. To remove a default value or/and an annotation from aParameter, 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'"

classinspect.BoundArguments¶

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

arguments¶

An ordered, mutable mapping (collections.OrderedDict) ofparameters’ names to arguments’ values. Contains only explicitly boundarguments. Changes inarguments will reflect inargs andkwargs.

Should be used in conjunction withSignature.parameters for anyargument processing purposes.

Note

Arguments for whichSignature.bind() orSignature.bind_partial() relied on a default value are skipped.However, if needed, it is easy to include them.

>>>deffoo(a,b=10):...pass>>>sig=signature(foo)>>>ba=sig.bind(5)>>>ba.args,ba.kwargs((5,), {})>>>forparaminsig.parameters.values():...ifparam.namenotinba.arguments:...ba.arguments[param.name]=param.default>>>ba.args,ba.kwargs((5, 10), {})

args¶

A tuple of positional arguments values. Dynamically computed from thearguments attribute.

kwargs¶

A dict of keyword arguments values. Dynamically computed from thearguments attribute.

Theargs andkwargs properties can be used to invokefunctions:

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

28.12.4. Classes and functions¶

inspect.getclasstree(classes,unique=False)¶

Arrange the given list of classes into a hierarchy of nested lists. Where anested list appears, it contains classes derived from the class whose entryimmediately precedes the list. Each entry is a 2-tuple containing a class and atuple of its base classes. If theunique argument is true, exactly one entryappears in the returned structure for each class in the given list. Otherwise,classes using multiple inheritance and their descendants will appear multipletimes.

inspect.getargspec(func)¶

Get the names and default values of a Python function’s arguments. Anamed tupleArgSpec(args,varargs,keywords,defaults) isreturned.args is a list of the argument names.varargs andkeywordsare the names of the* and** arguments orNone.defaults is atuple of default argument values orNone if there are no defaultarguments; if this tuple hasn elements, they correspond to the lastn elements listed inargs.

Deprecated since version 3.0:Usegetfullargspec() instead, which provides information aboutkeyword-only arguments and annotations.

inspect.getfullargspec(func)¶

Get the names and default values of a Python function’s arguments. Anamed tuple is returned:

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

args is a list of the argument names.varargs andvarkw are the namesof the* and** arguments orNone.defaults is ann-tupleof the default values of the lastn arguments, orNone if there are nodefault arguments.kwonlyargs is a list ofkeyword-only argument names.kwonlydefaults is a dictionary mapping namesfrom kwonlyargs to defaults.annotations is a dictionary mapping argumentnames to annotations.

The first four items in the tuple correspond togetargspec().

Note

Consider using the newSignature Objectinterface, which provides a better way of introspecting functions.

inspect.getargvalues(frame)¶

Get information about arguments passed into a particular frame. Anamed tupleArgInfo(args,varargs,keywords,locals) isreturned.args is a list of the argument names.varargs andkeywordsare the names of the* and** arguments orNone.locals is thelocals dictionary of the given frame.

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

Format a pretty argument spec from the values returned bygetargspec() orgetfullargspec().

The first seven arguments are (args,varargs,varkw,defaults,kwonlyargs,kwonlydefaults,annotations). Theother five arguments are the corresponding optional formatting functionsthat are called to turn names and values into strings. The last argumentis an optional function to format the sequence of arguments. For example:

>>>frominspectimportformatargspec,getfullargspec>>>deff(a:int,b:float):...pass...>>>formatargspec(*getfullargspec(f))'(a: int, b: float)'

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

Format a pretty argument spec from the four values returned bygetargvalues(). The format* arguments are the corresponding optionalformatting functions that are called to turn names and values into strings.

inspect.getmro(cls)¶

Return a tuple of class cls’s base classes, including cls, in method resolutionorder. No class appears more than once in this tuple. Note that the methodresolution order depends on cls’s type. Unless a very peculiar user-definedmetatype is in use, cls will be the first element of the tuple.

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

Bind theargs andkwds to the argument names of the Python function ormethodfunc, as if it was called with them. For bound methods, bind also thefirst argument (typically namedself) to the associated instance. A dictis returned, mapping the argument names (including the names of the* and** arguments, if any) to their values fromargs andkwds. In case ofinvokingfunc incorrectly, i.e. wheneverfunc(*args,**kwds) would raisean exception because of incompatible signature, an exception of the same typeand 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'

New in version 3.2.

Note

Consider using the newSignature.bind() instead.

inspect.getclosurevars(func)¶

Get the mapping of external name references in a Python function ormethodfunc to their current values. Anamed tupleClosureVars(nonlocals,globals,builtins,unbound)is returned.nonlocals maps referenced names to lexical closurevariables,globals to the function’s module globals andbuiltins tothe builtins visible from the function body.unbound is the set of namesreferenced in the function that could not be resolved at all given thecurrent module globals and builtins.

TypeError is raised iffunc is not a Python function or method.

New in version 3.3.

28.12.5. The interpreter stack¶

When the following functions return “frame records,” each record is a tuple ofsix items: the frame object, the filename, the line number of the current line,the function name, a list of lines of context from the source code, and theindex of the current line within that list.

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

The optionalcontext argument supported by most of these functions specifiesthe number of lines of context to return, which are centered around the currentline.

inspect.getframeinfo(frame,context=1)¶

Get information about a frame or traceback object. Anamed tupleTraceback(filename,lineno,function,code_context,index) is returned.

inspect.getouterframes(frame,context=1)¶

Get a list of frame records for a frame and all outer frames. These framesrepresent the calls that lead to the creation offrame. The first entry in thereturned list representsframe; the last entry represents the outermost callonframe‘s stack.

inspect.getinnerframes(traceback,context=1)¶

Get a list of frame records for a traceback’s frame and all inner frames. Theseframes represent calls made as a consequence offrame. The first entry in thelist representstraceback; the last entry represents where the exception wasraised.

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. Ifrunning in an implementation without Python stack frame support thisfunction returnsNone.

inspect.stack(context=1)¶

Return a list of frame records for the caller’s stack. The first entry in thereturned list represents the caller; the last entry represents the outermostcall on the stack.

inspect.trace(context=1)¶

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

28.12.6. Fetching attributes statically¶

Bothgetattr() andhasattr() can trigger code execution whenfetching or checking for the existence of attributes. Descriptors, likeproperties, will be invoked and__getattr__() and__getattribute__()may be called.

For cases where you want passive introspection, like documentation tools, thiscan 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 thedescriptor protocol,__getattr__() or__getattribute__().

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

If the instance__dict__ is shadowed by another member (forexample a property) then this function will be unable to find instancemembers.

New in version 3.2.

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

You can handle these with code like the following. Note thatfor arbitrary getset descriptors invoking these may triggercode execution:

# example code for resolving the builtin descriptor typesclass_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 dopass

28.12.7. Current State of a Generator¶

When implementing coroutine schedulers and for other advanced uses ofgenerators, it is useful to determine whether a generator is currentlyexecuting, is waiting to start or resume or execution, or has alreadyterminated.getgeneratorstate() allows the current state of agenerator 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.

New in version 3.2.

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

inspect.getgeneratorlocals(generator)¶

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

Ifgenerator is agenerator with no currently associated frame,then an empty dictionary is returned.TypeError is raised ifgenerator is not a Python generator object.

CPython implementation detail: This function relies on the generator exposing a Python stack framefor introspection, which isn’t guaranteed to be the case in allimplementations of Python. In such cases, this function will alwaysreturn an empty dictionary.

New in version 3.3.