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 (seeImport-related attributes on module objects for module attributes):

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.

備註

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.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 descriptorprotocol, __getattr__ or __getattribute__. Optionally, only return membersthat satisfy a given predicate.

備註

getmembers_static() may not be able to retrieve all membersthat getmembers can fetch (like dynamically created attributes)and may find members that getmembers can't (like descriptorsthat raise AttributeError). It can also return descriptor objectsinstead of instance members in some cases.

在 3.11 版被加入.

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.

在 3.3 版的變更:此函式直接基於importlib。

inspect.ismodule(object)¶

如果物件是模組，則回傳True。

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

如果物件是 Python 產生器函式，則回傳True。

在 3.8 版的變更:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is a Python generator function.

在 3.13 版的變更:Functions wrapped infunctools.partialmethod() now returnTrueif the wrapped function is a Python generator function.

inspect.isgenerator(object)¶

如果物件是產生器，則回傳True。

inspect.iscoroutinefunction(object)¶

ReturnTrue if the object is acoroutine function (a functiondefined with anasyncdef syntax), afunctools.partial()wrapping acoroutine function, or a sync function marked withmarkcoroutinefunction().

在 3.5 版被加入.

在 3.8 版的變更:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is acoroutine function.

在 3.12 版的變更:Sync functions marked withmarkcoroutinefunction() now returnTrue.

在 3.13 版的變更:Functions wrapped infunctools.partialmethod() now returnTrueif the wrapped function is acoroutine function.

inspect.markcoroutinefunction(func)¶

Decorator to mark a callable as acoroutine function if it would nototherwise be detected byiscoroutinefunction().

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

When possible, using anasyncdef function is preferred. Alsoacceptable is calling the function and testing the return withiscoroutine().

在 3.12 版被加入.

inspect.iscoroutine(object)¶

ReturnTrue if the object is acoroutine created by anasyncdef function.

在 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:

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

在 3.5 版被加入.

inspect.isasyncgenfunction(object)¶

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

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

在 3.6 版被加入.

在 3.8 版的變更:Functions wrapped infunctools.partial() now returnTrue if thewrapped function is anasynchronous generator function.

在 3.13 版的變更:Functions wrapped infunctools.partialmethod() now returnTrueif the wrapped function is acoroutine function.

inspect.isasyncgen(object)¶

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

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

如果物件是程式碼，則回傳True。

inspect.isbuiltin(object)¶

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

inspect.ismethodwrapper(object)¶

ReturnTrue if the type of object is aMethodWrapperType.

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

在 3.11 版被加入.

inspect.isroutine(object)¶

如果物件是使用者定義或內建的函式或方法，則回傳True。

inspect.isabstract(object)¶

如果物件是抽象基底類別，則回傳True。

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 or a__delete__() method. Beyond that, the set ofattributes 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().

在 3.13 版的變更:This function no longer incorrectly reports objects with__get__()and__delete__(), but not__set__(), as being methoddescriptors (such objects are data descriptors, not method descriptors).

inspect.isdatadescriptor(object)¶

如果物件是資料描述器，則回傳True。

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 實作細節： getsets are attributes defined in extension modules viaPyGetSetDef structures. For Python implementations without suchtypes, this method will always returnFalse.

inspect.ismemberdescriptor(object)¶

如果物件是成員描述器，則回傳True。

CPython 實作細節： Member descriptors are attributes defined in extension modules viaPyMemberDef structures. For Python implementations without suchtypes, this method will always returnFalse.

取得原始碼¶

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.ReturnNone if the documentation string is invalid or missing.

在 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. ReturnNoneif the module cannot be determined.

inspect.getsourcefile(object)¶

Return the name of the Python source file in which an object was definedorNone if no way can be identified to get the source. 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.ATypeError is raised if the object is a built-in module, class, orfunction.

在 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.ATypeError is raised if the object is a built-in module, class, orfunction.

在 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¶

TheSignature object represents the call signature of a callable objectand its return annotation. To retrieve aSignature object,use thesignature()function.

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

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.

For objects defined in modules using stringized annotations(from__future__importannotations),signature() willattempt to automatically un-stringize the annotations usingget_annotations(). Theglobals,locals, andeval_str parameters are passedintoget_annotations() when resolving theannotations; see the documentation forget_annotations()for instructions on how to use these parameters.

RaisesValueError if no signature can be provided, andTypeError if that type of object is not supported. Also,if the annotations are stringized, andeval_str is 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 priorto it are positional-only. For more info, seethe FAQ entry on positional-only parameters.

在 3.5 版的變更:Thefollow_wrapped parameter was added.PassFalse to get a signature ofcallable specifically (callable.__wrapped__ will not be used tounwrap decorated callables.)

在 3.10 版的變更:Theglobals,locals, andeval_str parameters were added.

備註

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.

CPython 實作細節： If the passed object has a__signature__ attribute,we may use it to create the signature.The exact semantics are an implementation detail and are subject tounannounced changes. Consult the source code for current semantics.

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

ASignature object represents the call signature of a functionand 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.It represents the "return" annotation of the callable.

Signature objects areimmutable. UseSignature.replace() orcopy.replace() to make a modified copy.

在 3.5 版的變更:Signature objects 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 correspondingParameter objects. Parameters appear in strict definitionorder, including keyword-only parameters.

在 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 newSignature instance based on the instancereplace() was invoked on.It is possible to pass differentparameters and/orreturn_annotation to override the corresponding properties of the basesignature. To removereturn_annotation from the copiedSignature, 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'"

Signature objects are also supported by the generic functioncopy.replace().

format(*,max_width=None)¶

Create a string representation of theSignature object.

Ifmax_width is passed, the method will attempt to fitthe signature into lines of at mostmax_width characters.If the signature is longer thanmax_width,all parameters will be on separate lines.

在 3.13 版被加入.

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

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

This method simplifies subclassing ofSignature:

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

Its behavior is otherwise identical to that ofsignature().

在 3.5 版被加入.

在 3.10 版的變更:Theglobals,locals, andeval_str parameters were added.

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

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

在 3.5 版的變更:Parameter objects are now picklable andhashable.

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 實作細節： CPython generates implicit parameter names of the form.0 on thecode objects used to implement comprehensions and generatorexpressions.

在 3.6 版的變更:These parameter names are now 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. The possiblevalues are accessible viaParameter (likeParameter.KEYWORD_ONLY),and support comparison and ordering, in the following order:

名稱	意義
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 an enum value ofParameter.kind.

在 3.8 版被加入.

範例：列印所有引數的描述：

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

Parameter objects are also supported by the generic functioncopy.replace().

在 3.4 版的變更:In Python 3.3Parameter 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¶

A mutable mapping of parameters' names to arguments' values.Contains only explicitly bound arguments. Changes inargumentswill reflect inargs andkwargs.

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

備註

Arguments for whichSignature.bind() orSignature.bind_partial() relied on a default value are skipped.However, if needed, useBoundArguments.apply_defaults() to addthem.

在 3.9 版的變更:arguments is now of typedict. Formerly, it was oftypecollections.OrderedDict.

args¶

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

kwargs¶

A dict of keyword arguments values. Dynamically computed from thearguments attribute. Arguments that can be passed positionallyare included inargs instead.

signature¶

A reference to the parentSignature object.

apply_defaults()¶

為遺漏的引數設定預設值。

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.arguments{'a': 'spam', 'b': 'ham', 'args': ()}

在 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)

類別與函式¶

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

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

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

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

備註

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 bygetargvalues(). The format* arguments are the corresponding optionalformatting functions that are called to turn names and values into strings.

備註

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'

在 3.2 版被加入.

在 3.5 版之後被棄用:請改用Signature.bind() 與Signature.bind_partial()。

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.

如果func 不是 Python 函式或方法，則引發TypeError。

在 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。

在 3.4 版被加入.

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

Compute the annotations dict for an object.

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

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

This function handles several details for you:

• Ifeval_str is true, values of typestr willbe un-stringized usingeval(). This is intendedfor use with stringized annotations(from__future__importannotations).

• Ifobj doesn't have an annotations dict, returns anempty dict. (Functions and methods always have anannotations dict; classes, modules, and other types ofcallables may not.)

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

• All accesses to object members and dict values are doneusinggetattr() anddict.get() for safety.

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

eval_str controls whether or not values of typestr are replacedwith the result of callingeval() on those values:

• If eval_str is true,eval() is called on values of typestr.(Note thatget_annotations doesn't catch exceptions; ifeval()raises an exception, it will unwind the stack past theget_annotationscall.)

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

globals andlocals are passed in toeval(); see the documentationforeval() for more information. Ifglobals orlocalsisNone, this function may replace that value with a context-specificdefault, contingent ontype(obj):

• Ifobj is a module,globals defaults toobj.__dict__.

• Ifobj is a class,globals defaults tosys.modules[obj.__module__].__dict__ andlocals defaultsto theobj class namespace.

• Ifobj is a callable,globals defaults toobj.__globals__,although ifobj is a wrapped function (usingfunctools.update_wrapper()) it is first unwrapped.

Callingget_annotations is best practice for accessing theannotations dict of any object. See註釋 (annotation) 最佳實踐 formore information on annotations best practices.

在 3.10 版被加入.

直譯器堆疊¶

Some of the following functions returnFrameInfo objects. For backwards compatibility these objects allowtuple-like operations on all attributes exceptpositions. This behavioris considered deprecated and may be removed in the future.

classinspect.FrameInfo¶

frame¶

Theframe object that the record corresponds to.

filename¶

The file name associated with the code being executed by the frame this recordcorresponds to.

lineno¶

The line number of the current line associated with the code beingexecuted 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 framethis record corresponds to.

index¶

The index of the current line being executed in thecode_context list.

positions¶

Adis.Positions object containing the start line number, end linenumber, start column offset, and end column offset associated with theinstruction being executed by the frame this record corresponds to.

在 3.5 版的變更:Return anamed tuple instead of atuple.

在 3.11 版的變更:FrameInfo is 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 tracebackcorresponds to.

lineno¶

The line number of the current line associated with the code beingexecuted 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 framethis traceback corresponds to.

index¶

The index of the current line being executed in thecode_context list.

positions¶

Adis.Positions object containing the start line number, endline number, start column offset, and end column offset associated withthe instruction being executed by the frame this traceback correspondsto.

在 3.11 版的變更:Traceback is now a class instance(that is backwards compatible with the previousnamed tuple).

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. ATraceback objectis returned.

在 3.11 版的變更:ATraceback object is returned instead of a named tuple.

inspect.getouterframes(frame,context=1)¶

Get a list ofFrameInfo objects for a frame and all outer frames.These frames represent the calls that lead to the creation offrame. Thefirst entry in the returned list representsframe; the last entryrepresents the outermost call onframe's stack.

在 3.5 版的變更:A list ofnamed tuplesFrameInfo(frame,filename,lineno,function,code_context,index)is returned.

在 3.11 版的變更:回傳一個FrameInfo 物件串列。

inspect.getinnerframes(traceback,context=1)¶

Get a list ofFrameInfo objects for a traceback's frame and allinner frames. These frames represent calls made as a consequence offrame.The first entry in the list representstraceback; the last entry representswhere the exception was raised.

在 3.5 版的變更:A list ofnamed tuplesFrameInfo(frame,filename,lineno,function,code_context,index)is returned.

在 3.11 版的變更:回傳一個FrameInfo 物件串列。

inspect.currentframe()¶

Return the frame object for the caller's stack frame.

CPython 實作細節： 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 ofFrameInfo objects for the caller's stack. Thefirst entry in the returned list represents the caller; the last entryrepresents the outermost call on the stack.

在 3.5 版的變更:A list ofnamed tuplesFrameInfo(frame,filename,lineno,function,code_context,index)is returned.

在 3.11 版的變更:回傳一個FrameInfo 物件串列。

inspect.trace(context=1)¶

Return a list ofFrameInfo objects for the stack between the currentframe and the frame in which an exception currently being handled was raisedin. The first entry in the list represents the caller; the last entryrepresents where the exception was raised.

在 3.5 版的變更:A list ofnamed tuplesFrameInfo(frame,filename,lineno,function,code_context,index)is returned.

在 3.11 版的變更:回傳一個FrameInfo 物件串列。

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.

在 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, Coroutines, and Asynchronous Generators¶

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.

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

在 3.5 版被加入.

inspect.getasyncgenstate(agen)¶

Get current state of an asynchronous generator object. The function isintended to be used with asynchronous iterator objects created byasyncdef functions which use theyield statement,but will accept any asynchronous generator-like object that hasag_running andag_frame attributes.

Possible states are:

• AGEN_CREATED: 等待開始執行。

• AGEN_RUNNING: 目前正在被直譯器執行。

• AGEN_SUSPENDED: 目前於 yield 運算式暫停。

• AGEN_CLOSED: 執行已完成。

在 3.12 版被加入.

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 實作細節： 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.

在 3.3 版被加入.

inspect.getcoroutinelocals(coroutine)¶

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

在 3.5 版被加入.

inspect.getasyncgenlocals(agen)¶

This function is analogous togetgeneratorlocals(), butworks for asynchronous generator objects created byasyncdeffunctions which use theyield statement.

在 3.12 版被加入.

Code Objects Bit Flags¶

Python code objects have aco_flags attribute,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_localswhen 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 492 for more details.

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

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

在 3.6 版被加入.

Buffer flags¶

classinspect.BufferFlags¶

This is anenum.IntFlag that represents the flags thatcan be passed to the__buffer__() method of objectsimplementing 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¶

在 3.12 版被加入.

命令列介面¶

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