Types and members¶

Thegetmembers() function retrieves the members of an object such as aclass or module. The 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 by name. If the optionalpredicate argument—which will becalled with thevalue object of each member—is supplied, only membersfor which the predicate returns a true value are included.

Note

getmembers() will only return class attributes defined in themetaclass when the argument is a class and those attributes have beenlisted in the metaclass’ custom__dir__().

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:The function is based directly onimportlib.

inspect.ismodule(object)¶

ReturnTrue if the object is a module.

inspect.isclass(object)¶

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

inspect.ismethod(object)¶

ReturnTrue if the object is a bound method written in Python.

inspect.isfunction(object)¶

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

inspect.isgeneratorfunction(object)¶

ReturnTrue if the object is a Python generator function.

Changed in version 3.8:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is a Python generator function.

inspect.isgenerator(object)¶

ReturnTrue if the object is a generator.

inspect.iscoroutinefunction(object)¶

ReturnTrue if the object is acoroutine function(a function defined with anasyncdef syntax).

New in version 3.5.

Changed in version 3.8:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is acoroutine function.

inspect.iscoroutine(object)¶

ReturnTrue if the object is acoroutine created by anasyncdef function.

New in version 3.5.

inspect.isawaitable(object)¶

ReturnTrue if the object can be used inawait expression.

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

defgen():yield@types.coroutinedefgen_coro():yieldassertnotisawaitable(gen())assertisawaitable(gen_coro())

New in version 3.5.

inspect.isasyncgenfunction(object)¶

ReturnTrue if the object is anasynchronous generator function,for example:

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

New in version 3.6.

Changed in version 3.8:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is aasynchronous generator function.

inspect.isasyncgen(object)¶

ReturnTrue if the object is anasynchronous generator iteratorcreated by anasynchronous generator function.

New in version 3.6.

inspect.istraceback(object)¶

ReturnTrue if the object is a traceback.

inspect.isframe(object)¶

ReturnTrue if the object is a frame.

inspect.iscode(object)¶

ReturnTrue if the object is a code.

inspect.isbuiltin(object)¶

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

inspect.isroutine(object)¶

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

inspect.isabstract(object)¶

ReturnTrue if the object is an abstract base class.

inspect.ismethoddescriptor(object)¶

ReturnTrue 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__() method but not a__set__()method, but beyond that the set of attributes varies. A__name__ attribute is usuallysensible, and__doc__ often is.

Methods implemented via descriptors that also pass one of the other testsreturnFalse 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)¶

ReturnTrue if the object is a data descriptor.

Data descriptors have a__set__ or a__delete__ method.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)¶

ReturnTrue 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)¶

ReturnTrue 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.

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 isa class, a method, a property or a descriptor, retrieve the documentationstring from the inheritance hierarchy.

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 theobject’s source code (for a class, function, or method), or at the top of thePython source file (if the object is a module). If the object’s source codeis unavailable, returnNone. This could happen if the object has beendefined 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 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.

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

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,*,follow_wrapped=True)¶

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.

RaisesValueError if no signature can be provided, andTypeError if that type of object is not supported.

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

New in version 3.5:follow_wrapped parameter. PassFalse to get a signature ofcallable specifically (callable.__wrapped__ will not be used tounwrap decorated callables.)

Note

Some callables may not be introspectable in certain implementations ofPython. For example, in CPython, some built-in functions defined inC provide no 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.

Changed in version 3.5:Signature objects are picklable and hashable.

empty¶

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

parameters¶

An ordered mapping of parameters’ names to the correspondingParameter objects. Parameters appear in strict definitionorder, including keyword-only parameters.

Changed in version 3.7:Python only explicitly guaranteed that it preserved the declarationorder of keyword-only parameters as of version 3.7, although in practicethis 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.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'"

classmethodfrom_callable(obj,*,follow_wrapped=True)¶

Return aSignature (or its subclass) object for a given callableobj. Passfollow_wrapped=False to get a signature ofobjwithout unwrapping its__wrapped__ chain.

This method simplifies subclassing ofSignature:

classMySignature(Signature):passsig=MySignature.from_callable(min)assertisinstance(sig,MySignature)

New in version 3.5.

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.

Changed in version 3.5:Parameter objects are picklable and hashable.

empty¶

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

name¶

The name of the parameter as a string. The name must be a validPython identifier.

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

Changed in version 3.6:These parameter names are exposed by this module as names likeimplicit0.

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. Positional only parameters arethose which appear before a/ entry (ifpresent) in a Python function definition.
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

kind.description¶

Describes a enum value of Parameter.kind.

New 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 keywordpositional or keywordkeyword-onlykeyword-only

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

Changed in version 3.4:In Python 3.3 Parameter objects were allowed to havename settoNone if theirkind was 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¶

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, useBoundArguments.apply_defaults() to addthem.

args¶

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

kwargs¶

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

signature¶

A reference to the parentSignature object.

apply_defaults()¶

Set default values for missing arguments.

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

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

>>>deffoo(a,b='ham',*args):pass>>>ba=inspect.signature(foo).bind('spam')>>>ba.apply_defaults()>>>ba.argumentsOrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

New in version 3.5.

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)

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 parameters. Anamed tupleArgSpec(args,varargs,keywords,defaults) isreturned.args is a list of the parameter names.varargs andkeywordsare the names of the* and** parameters 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() for an updated API that is usually a drop-inreplacement, but also correctly handles function annotations andkeyword-only parameters.

Alternatively, usesignature() andSignature Object, which provide amore structured introspection API for callables.

inspect.getfullargspec(func)¶

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

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

args is a list of the positional parameter names.varargs is the name of the* parameter orNone if arbitrarypositional arguments are not accepted.varkw is the name of the** parameter orNone if arbitrarykeyword arguments are not accepted.defaults is ann-tuple of default argument values corresponding to thelastn positional parameters, orNone if there are no such defaultsdefined.kwonlyargs is a list of keyword-only parameter names in declaration order.kwonlydefaults is a dictionary mapping parameter names fromkwonlyargsto the default values used if no argument is supplied.annotations is a dictionary mapping parameter names to annotations.The special key"return" is used to report the function return valueannotation (if any).

Note thatsignature() andSignature Object provide the recommendedAPI for callable introspection, and support additional behaviours (likepositional-only arguments) that are sometimes encountered in extension moduleAPIs. This function is retained primarily for use in code that needs tomaintain compatibility with the Python 2inspect module API.

Changed in version 3.4:This function is now based onsignature(), but still ignores__wrapped__ attributes and includes the already bound firstparameter in the signature output for bound methods.

Changed in version 3.6:This method was previously documented as deprecated in favour ofsignature() in Python 3.5, but that decision has been reversedin order to restore a clearly supported standard interface forsingle-source Python 2/3 code migrating away from the legacygetargspec() API.

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

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.

Note

This function was inadvertently marked as deprecated in Python 3.5.

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

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

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

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

For example:

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

Deprecated since version 3.5:Usesignature() andSignature Object, which provide abetter introspecting API for callables.

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.

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

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

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

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

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

ValueError is raised if a cycle is encountered.

New in version 3.4.

The interpreter stack¶

When the following functions return “frame records,” each record is anamed tupleFrameInfo(frame,filename,lineno,function,code_context,index).The tuple contains the frame object, the filename, the line number of thecurrent 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.

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

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.

Changed in version 3.5:A list ofnamed tuplesFrameInfo(frame,filename,lineno,function,code_context,index)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. 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.

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

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.

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

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

Current State of Generators and Coroutines¶

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.

inspect.getcoroutinestate(coroutine)¶

Get current state of a coroutine object. The function is intended to beused with coroutine objects created byasyncdef functions, butwill accept any coroutine-like object that hascr_running andcr_frame attributes.

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.

New in version 3.5.

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.

inspect.getcoroutinelocals(coroutine)¶

This function is analogous togetgeneratorlocals(), butworks for coroutine objects created byasyncdef functions.

New in version 3.5.

Code Objects Bit Flags¶

Python code objects have aco_flags attribute, which is a bitmap ofthe 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 whenthe 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_NOFREE¶

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

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 492 for more details.

New in version 3.5.

inspect.CO_ITERABLE_COROUTINE¶

The flag is used to transform generators into generator-basedcoroutines. Generator objects with this flag can be used inawait expression, and canyieldfrom coroutine objects.SeePEP 492 for more details.

New in version 3.5.

inspect.CO_ASYNC_GENERATOR¶

The flag is set when the code object is an asynchronous generatorfunction. When the code object is executed it returns anasynchronous generator object. SeePEP 525 for more details.

New in version 3.6.

Command Line Interface¶

Theinspect module also provides a basic introspection capabilityfrom the command line.

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

--details¶

Print information about the specified object rather than the source code