rest25/library/inspect.rst => rest262/library/inspect.rst
23
24
25.. _inspect-types:
26
27Types and members
28-----------------
29
30The :func:`getmembers` function retrieves the members of an object such as a
n31-class or module. The eleven functions whose names begin with "is" are mainly
n31+class or module. The sixteen functions whose names begin with "is" are mainly
32provided as convenient choices for the second argument to :func:`getmembers`.
33They also help you determine when you can expect to find the following special
34attributes:
35
36+-----------+-----------------+---------------------------+-------+
37| Type      | Attribute       | Description               | Notes |
38+===========+=================+===========================+=======+
39| module    | __doc__         | documentation string      |       |
49| method    | __doc__         | documentation string      |       |
50+-----------+-----------------+---------------------------+-------+
51|           | __name__        | name with which this      |       |
52|           |                 | method was defined        |       |
53+-----------+-----------------+---------------------------+-------+
54|           | im_class        | class object that asked   | \(1)  |
55|           |                 | for this method           |       |
56+-----------+-----------------+---------------------------+-------+
n57-|           | im_func         | function object           |       |
n57+|           | im_func or      | function object           |       |
58-|           |                 | containing implementation |       |
58+|           | __func__        | containing implementation |       |
59|           |                 | of method                 |       |
60+-----------+-----------------+---------------------------+-------+
n61-|           | im_self         | instance to which this    |       |
n61+|           | im_self or      | instance to which this    |       |
62-|           |                 | method is bound, or       |       |
62+|           | __self__        | method is bound, or       |       |
63|           |                 | ``None``                  |       |
64+-----------+-----------------+---------------------------+-------+
65| function  | __doc__         | documentation string      |       |
66+-----------+-----------------+---------------------------+-------+
67|           | __name__        | name with which this      |       |
68|           |                 | function was defined      |       |
69+-----------+-----------------+---------------------------+-------+
70|           | func_code       | code object containing    |       |
71|           |                 | compiled function         |       |
n72-|           |                 | bytecode                  |       |
n72+|           |                 | :term:`bytecode`          |       |
73+-----------+-----------------+---------------------------+-------+
74|           | func_defaults   | tuple of any default      |       |
75|           |                 | values for arguments      |       |
76+-----------+-----------------+---------------------------+-------+
77|           | func_doc        | (same as __doc__)         |       |
78+-----------+-----------------+---------------------------+-------+
79|           | func_globals    | global namespace in which |       |
80|           |                 | this function was defined |       |
81+-----------+-----------------+---------------------------+-------+
82|           | func_name       | (same as __name__)        |       |
n83++-----------+-----------------+---------------------------+-------+
84+| generator | __iter__        | defined to support        |       |
85+|           |                 | iteration over container  |       |
86++-----------+-----------------+---------------------------+-------+
87+|           | close           | raises new GeneratorExit  |       |
88+|           |                 | exception inside the      |       |
89+|           |                 | generator to terminate    |       |
90+|           |                 | the iteration             |       |
91++-----------+-----------------+---------------------------+-------+
92+|           | gi_code         | code object               |       |
93++-----------+-----------------+---------------------------+-------+
94+|           | gi_frame        | frame object or possibly  |       |
95+|           |                 | None once the generator   |       |
96+|           |                 | has been exhausted        |       |
97++-----------+-----------------+---------------------------+-------+
98+|           | gi_running      | set to 1 when generator   |       |
99+|           |                 | is executing, 0 otherwise |       |
100++-----------+-----------------+---------------------------+-------+
101+|           | next            | return the next item from |       |
102+|           |                 | the container             |       |
103++-----------+-----------------+---------------------------+-------+
104+|           | send            | resumes the generator and |       |
105+|           |                 | "sends" a value that      |       |
106+|           |                 | becomes the result of the |       |
107+|           |                 | current yield-expression  |       |
108++-----------+-----------------+---------------------------+-------+
109+|           | throw           | used to raise an          |       |
110+|           |                 | exception inside the      |       |
111+|           |                 | generator                 |       |
83+-----------+-----------------+---------------------------+-------+
84| traceback | tb_frame        | frame object at this      |       |
85|           |                 | level                     |       |
86+-----------+-----------------+---------------------------+-------+
87|           | tb_lasti        | index of last attempted   |       |
88|           |                 | instruction in bytecode   |       |
89+-----------+-----------------+---------------------------+-------+
90|           | tb_lineno       | current line number in    |       |
189      :attr:`im_class` used to refer to the class that defined the method.
190
191
192.. function:: getmembers(object[, predicate])
193
194   Return all the members of an object in a list of (name, value) pairs sorted by
195   name.  If the optional *predicate* argument is supplied, only members for which
196   the predicate returns a true value are included.
n226+ 
227+   .. note::
228+ 
229+      :func:`getmembers` does not return metaclass attributes when the argument
230+      is a class (this behavior is inherited from the :func:`dir` function).
197
198
199.. function:: getmoduleinfo(path)
200
201   Return a tuple of values that describe how Python will interpret the file
202   identified by *path* if it is a module, or ``None`` if it would not be
203   identified as a module.  The return tuple is ``(name, suffix, mode, mtype)``,
204   where *name* is the name of the module without the name of any enclosing
n205-   package, *suffix* is the trailing part of the file name (which may not be a dot-
n239+   package, *suffix* is the trailing part of the file name (which may not be a
206-   delimited extension), *mode* is the :func:`open` mode that would be used
240+   dot-delimited extension), *mode* is the :func:`open` mode that would be used
207-   (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the module.
241+   (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the
208-   *mtype* will have a value which can be compared to the constants defined in the
242+   module.  *mtype* will have a value which can be compared to the constants
209-   :mod:`imp` module; see the documentation for that module for more information on
243+   defined in the :mod:`imp` module; see the documentation for that module for
244+   more information on module types.
245+ 
246+   .. versionchanged:: 2.6
247+      Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode,
210-   module types.
248+      module_type)``.
211
212
213.. function:: getmodulename(path)
214
215   Return the name of the module named by the file *path*, without including the
216   names of enclosing packages.  This uses the same algorithm as the interpreter
217   uses when searching for modules.  If the name cannot be matched according to the
218   interpreter's rules, ``None`` is returned.
230
231.. function:: ismethod(object)
232
233   Return true if the object is a method.
234
235
236.. function:: isfunction(object)
237
n238-   Return true if the object is a Python function or unnamed (lambda) function.
n276+   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
239
n278+.. function:: isgeneratorfunction(object)
279+ 
280+   Return true if the object is a Python generator function.
281+ 
282+   .. versionadded:: 2.6
283+ 
284+.. function:: isgenerator(object)
285+ 
286+   Return true if the object is a generator.
287+ 
288+   .. versionadded:: 2.6
240
241.. function:: istraceback(object)
242
243   Return true if the object is a traceback.
244
245
246.. function:: isframe(object)
247
257
258   Return true if the object is a built-in function.
259
260
261.. function:: isroutine(object)
262
263   Return true if the object is a user-defined or built-in function or method.
264
n314+.. function:: isabstract(object)
315+ 
316+   Return true if the object is an abstract base class.
317+ 
318+   .. versionadded:: 2.6
319+ 
265
266.. function:: ismethoddescriptor(object)
267
n268-   Return true if the object is a method descriptor, but not if ismethod() or
n323+   Return true if the object is a method descriptor, but not if :func:`ismethod`
269-   isclass() or isfunction() are true.
324+   or :func:`isclass` or :func:`isfunction` are true.
270
n271-   This is new as of Python 2.2, and, for example, is true of int.__add__. An
n326+   This is new as of Python 2.2, and, for example, is true of
272-   object passing this test has a __get__ attribute but not a __set__ attribute,
327+   ``int.__add__``. An object passing this test has a :attr:`__get__` attribute
273-   but beyond that the set of attributes varies.  __name__ is usually sensible, and
328+   but not a :attr:`__set__` attribute, but beyond that the set of attributes
274-   __doc__ often is.
329+   varies.  :attr:`__name__` is usually sensible, and :attr:`__doc__` often is.
275
n276-   Methods implemented via descriptors that also pass one of the other tests return
n331+   Methods implemented via descriptors that also pass one of the other tests
277-   false from the ismethoddescriptor() test, simply because the other tests promise
332+   return false from the :func:`ismethoddescriptor` test, simply because the
278-   more -- you can, e.g., count on having the im_func attribute (etc) when an
333+   other tests promise more -- you can, e.g., count on having the
279-   object passes ismethod().
334+   :attr:`im_func` attribute (etc) when an object passes :func:`ismethod`.
280
281
282.. function:: isdatadescriptor(object)
283
284   Return true if the object is a data descriptor.
285
n286-   Data descriptors have both a __get__ and a __set__ attribute.  Examples are
n341+   Data descriptors have both a :attr:`__get__` and a :attr:`__set__` attribute.
287-   properties (defined in Python), getsets, and members.  The latter two are
342+   Examples are properties (defined in Python), getsets, and members.  The
288-   defined in C and there are more specific tests available for those types, which
343+   latter two are defined in C and there are more specific tests available for
289-   is robust across Python implementations.  Typically, data descriptors will also
344+   those types, which is robust across Python implementations.  Typically, data
290-   have __name__ and __doc__ attributes (properties, getsets, and members have both
345+   descriptors will also have :attr:`__name__` and :attr:`__doc__` attributes
291-   of these attributes), but this is not guaranteed.
346+   (properties, getsets, and members have both of these attributes), but this is
347+   not guaranteed.
292
293   .. versionadded:: 2.3
294
295
296.. function:: isgetsetdescriptor(object)
297
298   Return true if the object is a getset descriptor.
299
304   .. versionadded:: 2.5
305
306
307.. function:: ismemberdescriptor(object)
308
309   Return true if the object is a member descriptor.
310
311   Member descriptors are attributes defined in extension modules via
n312-   ``PyMemberDef`` structures.  For Python implementations without such types, this
n368+   ``PyMemberDef`` structures.  For Python implementations without such types,
313-   method will always return ``False``.
369+   this method will always return ``False``.
314
315   .. versionadded:: 2.5
316
317
318.. _inspect-source:
319
320Retrieving source code
321----------------------
322
n323- 
324.. function:: getdoc(object)
325
n326-   Get the documentation string for an object. All tabs are expanded to spaces.  To
n381+   Get the documentation string for an object, cleaned up with :func:`cleandoc`.
327-   clean up docstrings that are indented to line up with blocks of code, any
328-   whitespace than can be uniformly removed from the second line onwards is
329-   removed.
330
331
332.. function:: getcomments(object)
333
334   Return in a single string any lines of comments immediately preceding the
335   object's source code (for a class, function, or method), or at the top of the
336   Python source file (if the object is a module).
337
366
367
368.. function:: getsource(object)
369
370   Return the text of the source code for an object. The argument may be a module,
371   class, method, function, traceback, frame, or code object.  The source code is
372   returned as a single string.  An :exc:`IOError` is raised if the source code
373   cannot be retrieved.
n426+ 
427+ 
428+.. function:: cleandoc(doc)
429+ 
430+   Clean up indentation from docstrings that are indented to line up with blocks
431+   of code.  Any whitespace that can be uniformly removed from the second line
432+   onwards is removed.  Also, all tabs are expanded to spaces.
433+ 
434+   .. versionadded:: 2.6
374
375
376.. _inspect-classes-functions:
377
378Classes and functions
379---------------------
380
381
394
395   Get the names and default values of a function's arguments. A tuple of four
396   things is returned: ``(args, varargs, varkw, defaults)``. *args* is a list of
397   the argument names (it may contain nested lists). *varargs* and *varkw* are the
398   names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a tuple of
399   default argument values or None if there are no default arguments; if this tuple
400   has *n* elements, they correspond to the last *n* elements listed in *args*.
401
n463+   .. versionchanged:: 2.6
464+      Returns a :term:`named tuple` ``ArgSpec(args, varargs, keywords,
465+      defaults)``.
466+ 
402
403.. function:: getargvalues(frame)
404
405   Get information about arguments passed into a particular frame. A tuple of four
406   things is returned: ``(args, varargs, varkw, locals)``. *args* is a list of the
407   argument names (it may contain nested lists). *varargs* and *varkw* are the
408   names of the ``*`` and ``**`` arguments or ``None``. *locals* is the locals
409   dictionary of the given frame.
n475+ 
476+   .. versionchanged:: 2.6
477+      Returns a :term:`named tuple` ``ArgInfo(args, varargs, keywords,
478+      locals)``.
410
411
412.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
413
414   Format a pretty argument spec from the four values returned by
415   :func:`getargspec`.  The format\* arguments are the corresponding optional
416   formatting functions that are called to turn names and values into strings.
417
468line.
469
470
471.. function:: getframeinfo(frame[, context])
472
473   Get information about a frame or traceback object.  A 5-tuple is returned, the
474   last five elements of the frame's frame record.
475
t545+   .. versionchanged:: 2.6
546+      Returns a :term:`named tuple` ``Traceback(filename, lineno, function,
547+      code_context, index)``.
548+ 
476
477.. function:: getouterframes(frame[, context])
478
479   Get a list of frame records for a frame and all outer frames.  These frames
480   represent the calls that lead to the creation of *frame*. The first entry in the
481   returned list represents *frame*; the last entry represents the outermost call
482   on *frame*'s stack.
483
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op