1
:mod:`inspect` --- Inspect live objects
2
=======================================
5
:synopsis: Extract information and source code from live objects.
6
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
7
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
9
**Source code:** :source:`Lib/inspect.py`
13
The :mod:`inspect` module provides several useful functions to help get
14
information about live objects such as modules, classes, methods, functions,
15
tracebacks, frame objects, and code objects. For example, it can help you
16
examine the contents of a class, retrieve the source code of a method, extract
17
and format the argument list for a function, or get all the information you need
18
to display a detailed traceback.
20
There are four main kinds of services provided by this module: type checking,
21
getting source code, inspecting classes and functions, and examining the
30
The :func:`getmembers` function retrieves the members of an object such as a
31
class or module. The functions whose names begin with "is" are mainly
32
provided as convenient choices for the second argument to :func:`getmembers`.
33
They also help you determine when you can expect to find the following special
36
+-----------+-----------------+---------------------------+
37
| Type | Attribute | Description |
38
+===========+=================+===========================+
39
| module | __doc__ | documentation string |
40
+-----------+-----------------+---------------------------+
41
| | __file__ | filename (missing for |
42
| | | built-in modules) |
43
+-----------+-----------------+---------------------------+
44
| class | __doc__ | documentation string |
45
+-----------+-----------------+---------------------------+
46
| | __name__ | name with which this |
47
| | | class was defined |
48
+-----------+-----------------+---------------------------+
49
| | __qualname__ | qualified name |
50
+-----------+-----------------+---------------------------+
51
| | __module__ | name of module in which |
52
| | | this class was defined |
53
+-----------+-----------------+---------------------------+
54
| method | __doc__ | documentation string |
55
+-----------+-----------------+---------------------------+
56
| | __name__ | name with which this |
57
| | | method was defined |
58
+-----------+-----------------+---------------------------+
59
| | __qualname__ | qualified name |
60
+-----------+-----------------+---------------------------+
61
| | __func__ | function object |
62
| | | containing implementation |
64
+-----------+-----------------+---------------------------+
65
| | __self__ | instance to which this |
66
| | | method is bound, or |
68
+-----------+-----------------+---------------------------+
69
| function | __doc__ | documentation string |
70
+-----------+-----------------+---------------------------+
71
| | __name__ | name with which this |
72
| | | function was defined |
73
+-----------+-----------------+---------------------------+
74
| | __qualname__ | qualified name |
75
+-----------+-----------------+---------------------------+
76
| | __code__ | code object containing |
77
| | | compiled function |
78
| | | :term:`bytecode` |
79
+-----------+-----------------+---------------------------+
80
| | __defaults__ | tuple of any default |
81
| | | values for positional or |
82
| | | keyword parameters |
83
+-----------+-----------------+---------------------------+
84
| | __kwdefaults__ | mapping of any default |
85
| | | values for keyword-only |
87
+-----------+-----------------+---------------------------+
88
| | __globals__ | global namespace in which |
89
| | | this function was defined |
90
+-----------+-----------------+---------------------------+
91
| | __annotations__ | mapping of parameters |
92
| | | names to annotations; |
93
| | | ``"return"`` key is |
94
| | | reserved for return |
96
+-----------+-----------------+---------------------------+
97
| traceback | tb_frame | frame object at this |
99
+-----------+-----------------+---------------------------+
100
| | tb_lasti | index of last attempted |
101
| | | instruction in bytecode |
102
+-----------+-----------------+---------------------------+
103
| | tb_lineno | current line number in |
104
| | | Python source code |
105
+-----------+-----------------+---------------------------+
106
| | tb_next | next inner traceback |
107
| | | object (called by this |
109
+-----------+-----------------+---------------------------+
110
| frame | f_back | next outer frame object |
111
| | | (this frame's caller) |
112
+-----------+-----------------+---------------------------+
113
| | f_builtins | builtins namespace seen |
114
| | | by this frame |
115
+-----------+-----------------+---------------------------+
116
| | f_code | code object being |
117
| | | executed in this frame |
118
+-----------+-----------------+---------------------------+
119
| | f_globals | global namespace seen by |
121
+-----------+-----------------+---------------------------+
122
| | f_lasti | index of last attempted |
123
| | | instruction in bytecode |
124
+-----------+-----------------+---------------------------+
125
| | f_lineno | current line number in |
126
| | | Python source code |
127
+-----------+-----------------+---------------------------+
128
| | f_locals | local namespace seen by |
130
+-----------+-----------------+---------------------------+
131
| | f_restricted | 0 or 1 if frame is in |
132
| | | restricted execution mode |
133
+-----------+-----------------+---------------------------+
134
| | f_trace | tracing function for this |
135
| | | frame, or ``None`` |
136
+-----------+-----------------+---------------------------+
137
| code | co_argcount | number of arguments (not |
138
| | | including \* or \*\* |
140
+-----------+-----------------+---------------------------+
141
| | co_code | string of raw compiled |
143
+-----------+-----------------+---------------------------+
144
| | co_consts | tuple of constants used |
145
| | | in the bytecode |
146
+-----------+-----------------+---------------------------+
147
| | co_filename | name of file in which |
148
| | | this code object was |
150
+-----------+-----------------+---------------------------+
151
| | co_firstlineno | number of first line in |
152
| | | Python source code |
153
+-----------+-----------------+---------------------------+
154
| | co_flags | bitmap: 1=optimized ``|`` |
155
| | | 2=newlocals ``|`` 4=\*arg |
156
| | | ``|`` 8=\*\*arg |
157
+-----------+-----------------+---------------------------+
158
| | co_lnotab | encoded mapping of line |
159
| | | numbers to bytecode |
161
+-----------+-----------------+---------------------------+
162
| | co_name | name with which this code |
163
| | | object was defined |
164
+-----------+-----------------+---------------------------+
165
| | co_names | tuple of names of local |
167
+-----------+-----------------+---------------------------+
168
| | co_nlocals | number of local variables |
169
+-----------+-----------------+---------------------------+
170
| | co_stacksize | virtual machine stack |
171
| | | space required |
172
+-----------+-----------------+---------------------------+
173
| | co_varnames | tuple of names of |
174
| | | arguments and local |
176
+-----------+-----------------+---------------------------+
177
| generator | __name__ | name |
178
+-----------+-----------------+---------------------------+
179
| | __qualname__ | qualified name |
180
+-----------+-----------------+---------------------------+
181
| | gi_frame | frame |
182
+-----------+-----------------+---------------------------+
183
| | gi_running | is the generator running? |
184
+-----------+-----------------+---------------------------+
186
+-----------+-----------------+---------------------------+
187
| | gi_yieldfrom | object being iterated by |
188
| | | ``yield from``, or |
190
+-----------+-----------------+---------------------------+
191
| coroutine | __name__ | name |
192
+-----------+-----------------+---------------------------+
193
| | __qualname__ | qualified name |
194
+-----------+-----------------+---------------------------+
195
| | cr_await | object being awaited on, |
197
+-----------+-----------------+---------------------------+
198
| | cr_frame | frame |
199
+-----------+-----------------+---------------------------+
200
| | cr_running | is the coroutine running? |
201
+-----------+-----------------+---------------------------+
203
+-----------+-----------------+---------------------------+
204
| builtin | __doc__ | documentation string |
205
+-----------+-----------------+---------------------------+
206
| | __name__ | original name of this |
207
| | | function or method |
208
+-----------+-----------------+---------------------------+
209
| | __qualname__ | qualified name |
210
+-----------+-----------------+---------------------------+
211
| | __self__ | instance to which a |
212
| | | method is bound, or |
214
+-----------+-----------------+---------------------------+
216
.. versionchanged:: 3.5
218
Add ``__qualname__`` and ``gi_yieldfrom`` attributes to generators.
220
The ``__name__`` attribute of generators is now set from the function
221
name, instead of the code name, and it can now be modified.
224
.. function:: getmembers(object[, predicate])
226
Return all the members of an object in a list of (name, value) pairs sorted by
227
name. If the optional *predicate* argument is supplied, only members for which
228
the predicate returns a true value are included.
232
:func:`getmembers` will only return class attributes defined in the
233
metaclass when the argument is a class and those attributes have been
234
listed in the metaclass' custom :meth:`__dir__`.
237
.. function:: getmoduleinfo(path)
239
Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode, module_type)``
240
of values that describe how Python will interpret the file identified by
241
*path* if it is a module, or ``None`` if it would not be identified as a
242
module. In that tuple, *name* is the name of the module without the name of
243
any enclosing package, *suffix* is the trailing part of the file name (which
244
may not be a dot-delimited extension), *mode* is the :func:`open` mode that
245
would be used (``'r'`` or ``'rb'``), and *module_type* is an integer giving
246
the type of the module. *module_type* will have a value which can be
247
compared to the constants defined in the :mod:`imp` module; see the
248
documentation for that module for more information on module types.
251
You may check the file path's suffix against the supported suffixes
252
listed in :mod:`importlib.machinery` to infer the same information.
255
.. function:: getmodulename(path)
257
Return the name of the module named by the file *path*, without including the
258
names of enclosing packages. The file extension is checked against all of
259
the entries in :func:`importlib.machinery.all_suffixes`. If it matches,
260
the final path component is returned with the extension removed.
261
Otherwise, ``None`` is returned.
263
Note that this function *only* returns a meaningful name for actual
264
Python modules - paths that potentially refer to Python packages will
265
still return ``None``.
267
.. versionchanged:: 3.3
268
This function is now based directly on :mod:`importlib` rather than the
269
deprecated :func:`getmoduleinfo`.
272
.. function:: ismodule(object)
274
Return true if the object is a module.
277
.. function:: isclass(object)
279
Return true if the object is a class, whether built-in or created in Python
283
.. function:: ismethod(object)
285
Return true if the object is a bound method written in Python.
288
.. function:: isfunction(object)
290
Return true if the object is a Python function, which includes functions
291
created by a :term:`lambda` expression.
294
.. function:: isgeneratorfunction(object)
296
Return true if the object is a Python generator function.
299
.. function:: isgenerator(object)
301
Return true if the object is a generator.
304
.. function:: iscoroutinefunction(object)
306
Return true if the object is a :term:`coroutine function`
307
(a function defined with an :keyword:`async def` syntax).
309
.. versionadded:: 3.5
312
.. function:: iscoroutine(object)
314
Return true if the object is a :term:`coroutine` created by an
315
:keyword:`async def` function.
317
.. versionadded:: 3.5
320
.. function:: isawaitable(object)
322
Return true if the object can be used in :keyword:`await` expression.
324
Can also be used to distinguish generator-based coroutines from regular
333
assert not isawaitable(gen())
334
assert isawaitable(gen_coro())
336
.. versionadded:: 3.5
339
.. function:: istraceback(object)
341
Return true if the object is a traceback.
344
.. function:: isframe(object)
346
Return true if the object is a frame.
349
.. function:: iscode(object)
351
Return true if the object is a code.
354
.. function:: isbuiltin(object)
356
Return true if the object is a built-in function or a bound built-in method.
359
.. function:: isroutine(object)
361
Return true if the object is a user-defined or built-in function or method.
364
.. function:: isabstract(object)
366
Return true if the object is an abstract base class.
369
.. function:: ismethoddescriptor(object)
371
Return true if the object is a method descriptor, but not if
372
:func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
375
This, for example, is true of ``int.__add__``. An object passing this test
376
has a :attr:`__get__` attribute but not a :attr:`__set__` attribute, but
377
beyond that the set of attributes varies. :attr:`__name__` is usually
378
sensible, and :attr:`__doc__` often is.
380
Methods implemented via descriptors that also pass one of the other tests
381
return false from the :func:`ismethoddescriptor` test, simply because the
382
other tests promise more -- you can, e.g., count on having the
383
:attr:`__func__` attribute (etc) when an object passes :func:`ismethod`.
386
.. function:: isdatadescriptor(object)
388
Return true if the object is a data descriptor.
390
Data descriptors have both a :attr:`__get__` and a :attr:`__set__` attribute.
391
Examples are properties (defined in Python), getsets, and members. The
392
latter two are defined in C and there are more specific tests available for
393
those types, which is robust across Python implementations. Typically, data
394
descriptors will also have :attr:`__name__` and :attr:`__doc__` attributes
395
(properties, getsets, and members have both of these attributes), but this is
399
.. function:: isgetsetdescriptor(object)
401
Return true if the object is a getset descriptor.
405
getsets are attributes defined in extension modules via
406
:c:type:`PyGetSetDef` structures. For Python implementations without such
407
types, this method will always return ``False``.
410
.. function:: ismemberdescriptor(object)
412
Return true if the object is a member descriptor.
416
Member descriptors are attributes defined in extension modules via
417
:c:type:`PyMemberDef` structures. For Python implementations without such
418
types, this method will always return ``False``.
423
Retrieving source code
424
----------------------
426
.. function:: getdoc(object)
428
Get the documentation string for an object, cleaned up with :func:`cleandoc`.
429
If the documentation string for an object is not provided and the object is
430
a class, a method, a property or a descriptor, retrieve the documentation
431
string from the inheritance hierarchy.
433
.. versionchanged:: 3.5
434
Documentation strings are now inherited if not overridden.
437
.. function:: getcomments(object)
439
Return in a single string any lines of comments immediately preceding the
440
object's source code (for a class, function, or method), or at the top of the
441
Python source file (if the object is a module).
444
.. function:: getfile(object)
446
Return the name of the (text or binary) file in which an object was defined.
447
This will fail with a :exc:`TypeError` if the object is a built-in module,
451
.. function:: getmodule(object)
453
Try to guess which module an object was defined in.
456
.. function:: getsourcefile(object)
458
Return the name of the Python source file in which an object was defined. This
459
will fail with a :exc:`TypeError` if the object is a built-in module, class, or
463
.. function:: getsourcelines(object)
465
Return a list of source lines and starting line number for an object. The
466
argument may be a module, class, method, function, traceback, frame, or code
467
object. The source code is returned as a list of the lines corresponding to the
468
object and the line number indicates where in the original source file the first
469
line of code was found. An :exc:`OSError` is raised if the source code cannot
472
.. versionchanged:: 3.3
473
:exc:`OSError` is raised instead of :exc:`IOError`, now an alias of the
477
.. function:: getsource(object)
479
Return the text of the source code for an object. The argument may be a module,
480
class, method, function, traceback, frame, or code object. The source code is
481
returned as a single string. An :exc:`OSError` is raised if the source code
484
.. versionchanged:: 3.3
485
:exc:`OSError` is raised instead of :exc:`IOError`, now an alias of the
489
.. function:: cleandoc(doc)
491
Clean up indentation from docstrings that are indented to line up with blocks
492
of code. Any whitespace that can be uniformly removed from the second line
493
onwards is removed. Also, all tabs are expanded to spaces.
496
.. _inspect-signature-object:
498
Introspecting callables with the Signature object
499
-------------------------------------------------
501
.. versionadded:: 3.3
503
The Signature object represents the call signature of a callable object and its
504
return annotation. To retrieve a Signature object, use the :func:`signature`
507
.. function:: signature(callable, \*, follow_wrapped=True)
509
Return a :class:`Signature` object for the given ``callable``::
511
>>> from inspect import signature
512
>>> def foo(a, *, b:int, **kwargs):
515
>>> sig = signature(foo)
518
'(a, *, b:int, **kwargs)'
520
>>> str(sig.parameters['b'])
523
>>> sig.parameters['b'].annotation
526
Accepts a wide range of python callables, from plain functions and classes to
527
:func:`functools.partial` objects.
529
Raises :exc:`ValueError` if no signature can be provided, and
530
:exc:`TypeError` if that type of object is not supported.
532
.. versionadded:: 3.5
533
``follow_wrapped`` parameter. Pass ``False`` to get a signature of
534
``callable`` specifically (``callable.__wrapped__`` will not be used to
535
unwrap decorated callables.)
539
Some callables may not be introspectable in certain implementations of
540
Python. For example, in CPython, some built-in functions defined in
541
C provide no metadata about their arguments.
544
.. class:: Signature(parameters=None, \*, return_annotation=Signature.empty)
546
A Signature object represents the call signature of a function and its return
547
annotation. For each parameter accepted by the function it stores a
548
:class:`Parameter` object in its :attr:`parameters` collection.
550
The optional *parameters* argument is a sequence of :class:`Parameter`
551
objects, which is validated to check that there are no parameters with
552
duplicate names, and that the parameters are in the right order, i.e.
553
positional-only first, then positional-or-keyword, and that parameters with
554
defaults follow parameters without defaults.
556
The optional *return_annotation* argument, can be an arbitrary Python object,
557
is the "return" annotation of the callable.
559
Signature objects are *immutable*. Use :meth:`Signature.replace` to make a
562
.. versionchanged:: 3.5
563
Signature objects are picklable and hashable.
565
.. attribute:: Signature.empty
567
A special class-level marker to specify absence of a return annotation.
569
.. attribute:: Signature.parameters
571
An ordered mapping of parameters' names to the corresponding
572
:class:`Parameter` objects.
574
.. attribute:: Signature.return_annotation
576
The "return" annotation for the callable. If the callable has no "return"
577
annotation, this attribute is set to :attr:`Signature.empty`.
579
.. method:: Signature.bind(*args, **kwargs)
581
Create a mapping from positional and keyword arguments to parameters.
582
Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the
583
signature, or raises a :exc:`TypeError`.
585
.. method:: Signature.bind_partial(*args, **kwargs)
587
Works the same way as :meth:`Signature.bind`, but allows the omission of
588
some required arguments (mimics :func:`functools.partial` behavior.)
589
Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the
590
passed arguments do not match the signature.
592
.. method:: Signature.replace(*[, parameters][, return_annotation])
594
Create a new Signature instance based on the instance replace was invoked
595
on. It is possible to pass different ``parameters`` and/or
596
``return_annotation`` to override the corresponding properties of the base
597
signature. To remove return_annotation from the copied Signature, pass in
598
:attr:`Signature.empty`.
604
>>> sig = signature(test)
605
>>> new_sig = sig.replace(return_annotation="new return anno")
607
"(a, b) -> 'new return anno'"
609
.. classmethod:: Signature.from_callable(obj, \*, follow_wrapped=True)
611
Return a :class:`Signature` (or its subclass) object for a given callable
612
``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj``
613
without unwrapping its ``__wrapped__`` chain.
615
This method simplifies subclassing of :class:`Signature`::
617
class MySignature(Signature):
619
sig = MySignature.from_callable(min)
620
assert isinstance(sig, MySignature)
622
.. versionadded:: 3.5
625
.. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Parameter.empty)
627
Parameter objects are *immutable*. Instead of modifying a Parameter object,
628
you can use :meth:`Parameter.replace` to create a modified copy.
630
.. versionchanged:: 3.5
631
Parameter objects are picklable and hashable.
633
.. attribute:: Parameter.empty
635
A special class-level marker to specify absence of default values and
638
.. attribute:: Parameter.name
640
The name of the parameter as a string. The name must be a valid
643
.. attribute:: Parameter.default
645
The default value for the parameter. If the parameter has no default
646
value, this attribute is set to :attr:`Parameter.empty`.
648
.. attribute:: Parameter.annotation
650
The annotation for the parameter. If the parameter has no annotation,
651
this attribute is set to :attr:`Parameter.empty`.
653
.. attribute:: Parameter.kind
655
Describes how argument values are bound to the parameter. Possible values
656
(accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
658
.. tabularcolumns:: |l|L|
660
+------------------------+----------------------------------------------+
662
+========================+==============================================+
663
| *POSITIONAL_ONLY* | Value must be supplied as a positional |
666
| | Python has no explicit syntax for defining |
667
| | positional-only parameters, but many built-in|
668
| | and extension module functions (especially |
669
| | those that accept only one or two parameters)|
671
+------------------------+----------------------------------------------+
672
| *POSITIONAL_OR_KEYWORD*| Value may be supplied as either a keyword or |
673
| | positional argument (this is the standard |
674
| | binding behaviour for functions implemented |
676
+------------------------+----------------------------------------------+
677
| *VAR_POSITIONAL* | A tuple of positional arguments that aren't |
678
| | bound to any other parameter. This |
679
| | corresponds to a ``*args`` parameter in a |
680
| | Python function definition. |
681
+------------------------+----------------------------------------------+
682
| *KEYWORD_ONLY* | Value must be supplied as a keyword argument.|
683
| | Keyword only parameters are those which |
684
| | appear after a ``*`` or ``*args`` entry in a |
685
| | Python function definition. |
686
+------------------------+----------------------------------------------+
687
| *VAR_KEYWORD* | A dict of keyword arguments that aren't bound|
688
| | to any other parameter. This corresponds to a|
689
| | ``**kwargs`` parameter in a Python function |
691
+------------------------+----------------------------------------------+
693
Example: print all keyword-only arguments without default values::
695
>>> def foo(a, b, *, c, d=10):
698
>>> sig = signature(foo)
699
>>> for param in sig.parameters.values():
700
... if (param.kind == param.KEYWORD_ONLY and
701
... param.default is param.empty):
702
... print('Parameter:', param)
705
.. method:: Parameter.replace(*[, name][, kind][, default][, annotation])
707
Create a new Parameter instance based on the instance replaced was invoked
708
on. To override a :class:`Parameter` attribute, pass the corresponding
709
argument. To remove a default value or/and an annotation from a
710
Parameter, pass :attr:`Parameter.empty`.
714
>>> from inspect import Parameter
715
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
719
>>> str(param.replace()) # Will create a shallow copy of 'param'
722
>>> str(param.replace(default=Parameter.empty, annotation='spam'))
725
.. versionchanged:: 3.4
726
In Python 3.3 Parameter objects were allowed to have ``name`` set
727
to ``None`` if their ``kind`` was set to ``POSITIONAL_ONLY``.
728
This is no longer permitted.
730
.. class:: BoundArguments
732
Result of a :meth:`Signature.bind` or :meth:`Signature.bind_partial` call.
733
Holds the mapping of arguments to the function's parameters.
735
.. attribute:: BoundArguments.arguments
737
An ordered, mutable mapping (:class:`collections.OrderedDict`) of
738
parameters' names to arguments' values. Contains only explicitly bound
739
arguments. Changes in :attr:`arguments` will reflect in :attr:`args` and
742
Should be used in conjunction with :attr:`Signature.parameters` for any
743
argument processing purposes.
747
Arguments for which :meth:`Signature.bind` or
748
:meth:`Signature.bind_partial` relied on a default value are skipped.
749
However, if needed, use :meth:`BoundArguments.apply_defaults` to add
752
.. attribute:: BoundArguments.args
754
A tuple of positional arguments values. Dynamically computed from the
755
:attr:`arguments` attribute.
757
.. attribute:: BoundArguments.kwargs
759
A dict of keyword arguments values. Dynamically computed from the
760
:attr:`arguments` attribute.
762
.. attribute:: BoundArguments.signature
764
A reference to the parent :class:`Signature` object.
766
.. method:: BoundArguments.apply_defaults()
768
Set default values for missing arguments.
770
For variable-positional arguments (``*args``) the default is an
773
For variable-keyword arguments (``**kwargs``) the default is an
778
>>> def foo(a, b='ham', *args): pass
779
>>> ba = inspect.signature(foo).bind('spam')
780
>>> ba.apply_defaults()
782
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])
784
.. versionadded:: 3.5
786
The :attr:`args` and :attr:`kwargs` properties can be used to invoke
792
sig = signature(test)
793
ba = sig.bind(10, b=20)
794
test(*ba.args, **ba.kwargs)
799
:pep:`362` - Function Signature Object.
800
The detailed specification, implementation details and examples.
803
.. _inspect-classes-functions:
805
Classes and functions
806
---------------------
808
.. function:: getclasstree(classes, unique=False)
810
Arrange the given list of classes into a hierarchy of nested lists. Where a
811
nested list appears, it contains classes derived from the class whose entry
812
immediately precedes the list. Each entry is a 2-tuple containing a class and a
813
tuple of its base classes. If the *unique* argument is true, exactly one entry
814
appears in the returned structure for each class in the given list. Otherwise,
815
classes using multiple inheritance and their descendants will appear multiple
819
.. function:: getargspec(func)
821
Get the names and default values of a Python function's arguments. A
822
:term:`named tuple` ``ArgSpec(args, varargs, keywords, defaults)`` is
823
returned. *args* is a list of the argument names. *varargs* and *keywords*
824
are the names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a
825
tuple of default argument values or ``None`` if there are no default
826
arguments; if this tuple has *n* elements, they correspond to the last
827
*n* elements listed in *args*.
830
Use :func:`signature` and
831
:ref:`Signature Object <inspect-signature-object>`, which provide a
832
better introspecting API for callables.
835
.. function:: getfullargspec(func)
837
Get the names and default values of a Python function's arguments. A
838
:term:`named tuple` is returned:
840
``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults,
843
*args* is a list of the argument names. *varargs* and *varkw* are the names
844
of the ``*`` and ``**`` arguments or ``None``. *defaults* is an *n*-tuple
845
of the default values of the last *n* arguments, or ``None`` if there are no
846
default arguments. *kwonlyargs* is a list of
847
keyword-only argument names. *kwonlydefaults* is a dictionary mapping names
848
from kwonlyargs to defaults. *annotations* is a dictionary mapping argument
849
names to annotations.
851
The first four items in the tuple correspond to :func:`getargspec`.
853
.. versionchanged:: 3.4
854
This function is now based on :func:`signature`, but still ignores
855
``__wrapped__`` attributes and includes the already bound first
856
parameter in the signature output for bound methods.
859
Use :func:`signature` and
860
:ref:`Signature Object <inspect-signature-object>`, which provide a
861
better introspecting API for callables.
864
.. function:: getargvalues(frame)
866
Get information about arguments passed into a particular frame. A
867
:term:`named tuple` ``ArgInfo(args, varargs, keywords, locals)`` is
868
returned. *args* is a list of the argument names. *varargs* and *keywords*
869
are the names of the ``*`` and ``**`` arguments or ``None``. *locals* is the
870
locals dictionary of the given frame.
873
Use :func:`signature` and
874
:ref:`Signature Object <inspect-signature-object>`, which provide a
875
better introspecting API for callables.
878
.. function:: formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])
880
Format a pretty argument spec from the values returned by
881
:func:`getargspec` or :func:`getfullargspec`.
883
The first seven arguments are (``args``, ``varargs``, ``varkw``,
884
``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``).
886
The other six arguments are functions that are called to turn argument names,
887
``*`` argument name, ``**`` argument name, default values, return annotation
888
and individual annotations into strings, respectively.
892
>>> from inspect import formatargspec, getfullargspec
893
>>> def f(a: int, b: float):
896
>>> formatargspec(*getfullargspec(f))
900
Use :func:`signature` and
901
:ref:`Signature Object <inspect-signature-object>`, which provide a
902
better introspecting API for callables.
905
.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
907
Format a pretty argument spec from the four values returned by
908
:func:`getargvalues`. The format\* arguments are the corresponding optional
909
formatting functions that are called to turn names and values into strings.
912
Use :func:`signature` and
913
:ref:`Signature Object <inspect-signature-object>`, which provide a
914
better introspecting API for callables.
917
.. function:: getmro(cls)
919
Return a tuple of class cls's base classes, including cls, in method resolution
920
order. No class appears more than once in this tuple. Note that the method
921
resolution order depends on cls's type. Unless a very peculiar user-defined
922
metatype is in use, cls will be the first element of the tuple.
925
.. function:: getcallargs(func, *args, **kwds)
927
Bind the *args* and *kwds* to the argument names of the Python function or
928
method *func*, as if it was called with them. For bound methods, bind also the
929
first argument (typically named ``self``) to the associated instance. A dict
930
is returned, mapping the argument names (including the names of the ``*`` and
931
``**`` arguments, if any) to their values from *args* and *kwds*. In case of
932
invoking *func* incorrectly, i.e. whenever ``func(*args, **kwds)`` would raise
933
an exception because of incompatible signature, an exception of the same type
934
and the same or similar message is raised. For example::
936
>>> from inspect import getcallargs
937
>>> def f(a, b=1, *pos, **named):
939
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
941
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
944
Traceback (most recent call last):
946
TypeError: f() missing 1 required positional argument: 'a'
948
.. versionadded:: 3.2
951
Use :meth:`Signature.bind` and :meth:`Signature.bind_partial` instead.
954
.. function:: getclosurevars(func)
956
Get the mapping of external name references in a Python function or
957
method *func* to their current values. A
958
:term:`named tuple` ``ClosureVars(nonlocals, globals, builtins, unbound)``
959
is returned. *nonlocals* maps referenced names to lexical closure
960
variables, *globals* to the function's module globals and *builtins* to
961
the builtins visible from the function body. *unbound* is the set of names
962
referenced in the function that could not be resolved at all given the
963
current module globals and builtins.
965
:exc:`TypeError` is raised if *func* is not a Python function or method.
967
.. versionadded:: 3.3
970
.. function:: unwrap(func, *, stop=None)
972
Get the object wrapped by *func*. It follows the chain of :attr:`__wrapped__`
973
attributes returning the last object in the chain.
975
*stop* is an optional callback accepting an object in the wrapper chain
976
as its sole argument that allows the unwrapping to be terminated early if
977
the callback returns a true value. If the callback never returns a true
978
value, the last object in the chain is returned as usual. For example,
979
:func:`signature` uses this to stop unwrapping if any object in the
980
chain has a ``__signature__`` attribute defined.
982
:exc:`ValueError` is raised if a cycle is encountered.
984
.. versionadded:: 3.4
989
The interpreter stack
990
---------------------
992
When the following functions return "frame records," each record is a
994
``FrameInfo(frame, filename, lineno, function, code_context, index)``.
995
The tuple contains the frame object, the filename, the line number of the
997
the function name, a list of lines of context from the source code, and the
998
index of the current line within that list.
1000
.. versionchanged:: 3.5
1001
Return a named tuple instead of a tuple.
1005
Keeping references to frame objects, as found in the first element of the frame
1006
records these functions return, can cause your program to create reference
1007
cycles. Once a reference cycle has been created, the lifespan of all objects
1008
which can be accessed from the objects which form the cycle can become much
1009
longer even if Python's optional cycle detector is enabled. If such cycles must
1010
be created, it is important to ensure they are explicitly broken to avoid the
1011
delayed destruction of objects and increased memory consumption which occurs.
1013
Though the cycle detector will catch these, destruction of the frames (and local
1014
variables) can be made deterministic by removing the cycle in a
1015
:keyword:`finally` clause. This is also important if the cycle detector was
1016
disabled when Python was compiled or using :func:`gc.disable`. For example::
1018
def handle_stackframe_without_leak():
1019
frame = inspect.currentframe()
1021
# do something with the frame
1025
If you want to keep the frame around (for example to print a traceback
1026
later), you can also break reference cycles by using the
1027
:meth:`frame.clear` method.
1029
The optional *context* argument supported by most of these functions specifies
1030
the number of lines of context to return, which are centered around the current
1034
.. function:: getframeinfo(frame, context=1)
1036
Get information about a frame or traceback object. A :term:`named tuple`
1037
``Traceback(filename, lineno, function, code_context, index)`` is returned.
1040
.. function:: getouterframes(frame, context=1)
1042
Get a list of frame records for a frame and all outer frames. These frames
1043
represent the calls that lead to the creation of *frame*. The first entry in the
1044
returned list represents *frame*; the last entry represents the outermost call
1047
.. versionchanged:: 3.5
1048
A list of :term:`named tuples <named tuple>`
1049
``FrameInfo(frame, filename, lineno, function, code_context, index)``
1053
.. function:: getinnerframes(traceback, context=1)
1055
Get a list of frame records for a traceback's frame and all inner frames. These
1056
frames represent calls made as a consequence of *frame*. The first entry in the
1057
list represents *traceback*; the last entry represents where the exception was
1060
.. versionchanged:: 3.5
1061
A list of :term:`named tuples <named tuple>`
1062
``FrameInfo(frame, filename, lineno, function, code_context, index)``
1066
.. function:: currentframe()
1068
Return the frame object for the caller's stack frame.
1072
This function relies on Python stack frame support in the interpreter,
1073
which isn't guaranteed to exist in all implementations of Python. If
1074
running in an implementation without Python stack frame support this
1075
function returns ``None``.
1078
.. function:: stack(context=1)
1080
Return a list of frame records for the caller's stack. The first entry in the
1081
returned list represents the caller; the last entry represents the outermost
1084
.. versionchanged:: 3.5
1085
A list of :term:`named tuples <named tuple>`
1086
``FrameInfo(frame, filename, lineno, function, code_context, index)``
1090
.. function:: trace(context=1)
1092
Return a list of frame records for the stack between the current frame and the
1093
frame in which an exception currently being handled was raised in. The first
1094
entry in the list represents the caller; the last entry represents where the
1095
exception was raised.
1097
.. versionchanged:: 3.5
1098
A list of :term:`named tuples <named tuple>`
1099
``FrameInfo(frame, filename, lineno, function, code_context, index)``
1103
Fetching attributes statically
1104
------------------------------
1106
Both :func:`getattr` and :func:`hasattr` can trigger code execution when
1107
fetching or checking for the existence of attributes. Descriptors, like
1108
properties, will be invoked and :meth:`__getattr__` and :meth:`__getattribute__`
1111
For cases where you want passive introspection, like documentation tools, this
1112
can be inconvenient. :func:`getattr_static` has the same signature as :func:`getattr`
1113
but avoids executing code when it fetches attributes.
1115
.. function:: getattr_static(obj, attr, default=None)
1117
Retrieve attributes without triggering dynamic lookup via the
1118
descriptor protocol, :meth:`__getattr__` or :meth:`__getattribute__`.
1120
Note: this function may not be able to retrieve all attributes
1121
that getattr can fetch (like dynamically created attributes)
1122
and may find attributes that getattr can't (like descriptors
1123
that raise AttributeError). It can also return descriptors objects
1124
instead of instance members.
1126
If the instance :attr:`~object.__dict__` is shadowed by another member (for
1127
example a property) then this function will be unable to find instance
1130
.. versionadded:: 3.2
1132
:func:`getattr_static` does not resolve descriptors, for example slot descriptors or
1133
getset descriptors on objects implemented in C. The descriptor object
1134
is returned instead of the underlying attribute.
1136
You can handle these with code like the following. Note that
1137
for arbitrary getset descriptors invoking these may trigger
1140
# example code for resolving the builtin descriptor types
1144
slot_descriptor = type(_foo.foo)
1145
getset_descriptor = type(type(open(__file__)).name)
1146
wrapper_descriptor = type(str.__dict__['__add__'])
1147
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)
1149
result = getattr_static(some_object, 'foo')
1150
if type(result) in descriptor_types:
1152
result = result.__get__()
1153
except AttributeError:
1154
# descriptors can raise AttributeError to
1155
# indicate there is no underlying value
1156
# in which case the descriptor itself will
1161
Current State of Generators and Coroutines
1162
------------------------------------------
1164
When implementing coroutine schedulers and for other advanced uses of
1165
generators, it is useful to determine whether a generator is currently
1166
executing, is waiting to start or resume or execution, or has already
1167
terminated. :func:`getgeneratorstate` allows the current state of a
1168
generator to be determined easily.
1170
.. function:: getgeneratorstate(generator)
1172
Get current state of a generator-iterator.
1174
Possible states are:
1175
* GEN_CREATED: Waiting to start execution.
1176
* GEN_RUNNING: Currently being executed by the interpreter.
1177
* GEN_SUSPENDED: Currently suspended at a yield expression.
1178
* GEN_CLOSED: Execution has completed.
1180
.. versionadded:: 3.2
1182
.. function:: getcoroutinestate(coroutine)
1184
Get current state of a coroutine object. The function is intended to be
1185
used with coroutine objects created by :keyword:`async def` functions, but
1186
will accept any coroutine-like object that has ``cr_running`` and
1187
``cr_frame`` attributes.
1189
Possible states are:
1190
* CORO_CREATED: Waiting to start execution.
1191
* CORO_RUNNING: Currently being executed by the interpreter.
1192
* CORO_SUSPENDED: Currently suspended at an await expression.
1193
* CORO_CLOSED: Execution has completed.
1195
.. versionadded:: 3.5
1197
The current internal state of the generator can also be queried. This is
1198
mostly useful for testing purposes, to ensure that internal state is being
1199
updated as expected:
1201
.. function:: getgeneratorlocals(generator)
1203
Get the mapping of live local variables in *generator* to their current
1204
values. A dictionary is returned that maps from variable names to values.
1205
This is the equivalent of calling :func:`locals` in the body of the
1206
generator, and all the same caveats apply.
1208
If *generator* is a :term:`generator` with no currently associated frame,
1209
then an empty dictionary is returned. :exc:`TypeError` is raised if
1210
*generator* is not a Python generator object.
1214
This function relies on the generator exposing a Python stack frame
1215
for introspection, which isn't guaranteed to be the case in all
1216
implementations of Python. In such cases, this function will always
1217
return an empty dictionary.
1219
.. versionadded:: 3.3
1221
.. function:: getcoroutinelocals(coroutine)
1223
This function is analogous to :func:`~inspect.getgeneratorlocals`, but
1224
works for coroutine objects created by :keyword:`async def` functions.
1226
.. versionadded:: 3.5
1229
.. _inspect-module-cli:
1231
Command Line Interface
1232
----------------------
1234
The :mod:`inspect` module also provides a basic introspection capability
1235
from the command line.
1237
.. program:: inspect
1239
By default, accepts the name of a module and prints the source of that
1240
module. A class or function within the module can be printed instead by
1241
appended a colon and the qualified name of the target object.
1243
.. cmdoption:: --details
1245
Print information about the specified object rather than the source code
added
removed
python-3.5.1-docs-html/_sources/library/inspect.txt
