Move the 3k reST doc tree in place.

1 files changed, 507 insertions, 0 deletions

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
new file mode 100644
index 0000000..edec9d5
--- /dev/null
+++ b/Doc/library/inspect.rst
@@ -0,0 +1,507 @@
+
+:mod:`inspect` --- Inspect live objects
+=======================================
+
+.. module:: inspect
+   :synopsis: Extract information and source code from live objects.
+.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
+.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
+
+
+.. versionadded:: 2.1
+
+The :mod:`inspect` module provides several useful functions to help get
+information about live objects such as modules, classes, methods, functions,
+tracebacks, frame objects, and code objects.  For example, it can help you
+examine the contents of a class, retrieve the source code of a method, extract
+and format the argument list for a function, or get all the information you need
+to display a detailed traceback.
+
+There are four main kinds of services provided by this module: type checking,
+getting source code, inspecting classes and functions, and examining the
+interpreter stack.
+
+
+.. _inspect-types:
+
+Types and members
+-----------------
+
+The :func:`getmembers` function retrieves the members of an object such as a
+class or module. The eleven functions whose names begin with "is" are mainly
+provided as convenient choices for the second argument to :func:`getmembers`.
+They also help you determine when you can expect to find the following special
+attributes:
+
++-----------+-----------------+---------------------------+-------+
+| Type      | Attribute       | Description               | Notes |
++===========+=================+===========================+=======+
+| module    | __doc__         | documentation string      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __file__        | filename (missing for     |       |
+|           |                 | built-in modules)         |       |
++-----------+-----------------+---------------------------+-------+
+| class     | __doc__         | documentation string      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __module__      | name of module in which   |       |
+|           |                 | this class was defined    |       |
++-----------+-----------------+---------------------------+-------+
+| method    | __doc__         | documentation string      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __name__        | name with which this      |       |
+|           |                 | method was defined        |       |
++-----------+-----------------+---------------------------+-------+
+|           | im_class        | class object that asked   | \(1)  |
+|           |                 | for this method           |       |
++-----------+-----------------+---------------------------+-------+
+|           | im_func         | function object           |       |
+|           |                 | containing implementation |       |
+|           |                 | of method                 |       |
++-----------+-----------------+---------------------------+-------+
+|           | im_self         | instance to which this    |       |
+|           |                 | method is bound, or       |       |
+|           |                 | ``None``                  |       |
++-----------+-----------------+---------------------------+-------+
+| function  | __doc__         | documentation string      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __name__        | name with which this      |       |
+|           |                 | function was defined      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __code__        | code object containing    |       |
+|           |                 | compiled function         |       |
+|           |                 | bytecode                  |       |
++-----------+-----------------+---------------------------+-------+
+|           | __defaults__    | tuple of any default      |       |
+|           |                 | values for arguments      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __globals__     | global namespace in which |       |
+|           |                 | this function was defined |       |
++-----------+-----------------+---------------------------+-------+
+| traceback | tb_frame        | frame object at this      |       |
+|           |                 | level                     |       |
++-----------+-----------------+---------------------------+-------+
+|           | tb_lasti        | index of last attempted   |       |
+|           |                 | instruction in bytecode   |       |
++-----------+-----------------+---------------------------+-------+
+|           | tb_lineno       | current line number in    |       |
+|           |                 | Python source code        |       |
++-----------+-----------------+---------------------------+-------+
+|           | tb_next         | next inner traceback      |       |
+|           |                 | object (called by this    |       |
+|           |                 | level)                    |       |
++-----------+-----------------+---------------------------+-------+
+| frame     | f_back          | next outer frame object   |       |
+|           |                 | (this frame's caller)     |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_builtins      | built-in namespace seen   |       |
+|           |                 | by this frame             |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_code          | code object being         |       |
+|           |                 | executed in this frame    |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_exc_traceback | traceback if raised in    |       |
+|           |                 | this frame, or ``None``   |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_exc_type      | exception type if raised  |       |
+|           |                 | in this frame, or         |       |
+|           |                 | ``None``                  |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_exc_value     | exception value if raised |       |
+|           |                 | in this frame, or         |       |
+|           |                 | ``None``                  |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_globals       | global namespace seen by  |       |
+|           |                 | this frame                |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_lasti         | index of last attempted   |       |
+|           |                 | instruction in bytecode   |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_lineno        | current line number in    |       |
+|           |                 | Python source code        |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_locals        | local namespace seen by   |       |
+|           |                 | this frame                |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_restricted    | 0 or 1 if frame is in     |       |
+|           |                 | restricted execution mode |       |
++-----------+-----------------+---------------------------+-------+
+|           | f_trace         | tracing function for this |       |
+|           |                 | frame, or ``None``        |       |
++-----------+-----------------+---------------------------+-------+
+| code      | co_argcount     | number of arguments (not  |       |
+|           |                 | including \* or \*\*      |       |
+|           |                 | args)                     |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_code         | string of raw compiled    |       |
+|           |                 | bytecode                  |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_consts       | tuple of constants used   |       |
+|           |                 | in the bytecode           |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_filename     | name of file in which     |       |
+|           |                 | this code object was      |       |
+|           |                 | created                   |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_firstlineno  | number of first line in   |       |
+|           |                 | Python source code        |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_flags        | bitmap: 1=optimized ``|`` |       |
+|           |                 | 2=newlocals ``|`` 4=\*arg |       |
+|           |                 | ``|`` 8=\*\*arg           |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_lnotab       | encoded mapping of line   |       |
+|           |                 | numbers to bytecode       |       |
+|           |                 | indices                   |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_name         | name with which this code |       |
+|           |                 | object was defined        |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_names        | tuple of names of local   |       |
+|           |                 | variables                 |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_nlocals      | number of local variables |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_stacksize    | virtual machine stack     |       |
+|           |                 | space required            |       |
++-----------+-----------------+---------------------------+-------+
+|           | co_varnames     | tuple of names of         |       |
+|           |                 | arguments and local       |       |
+|           |                 | variables                 |       |
++-----------+-----------------+---------------------------+-------+
+| builtin   | __doc__         | documentation string      |       |
++-----------+-----------------+---------------------------+-------+
+|           | __name__        | original name of this     |       |
+|           |                 | function or method        |       |
++-----------+-----------------+---------------------------+-------+
+|           | __self__        | instance to which a       |       |
+|           |                 | method is bound, or       |       |
+|           |                 | ``None``                  |       |
++-----------+-----------------+---------------------------+-------+
+
+Note:
+
+(1)
+   .. versionchanged:: 2.2
+      :attr:`im_class` used to refer to the class that defined the method.
+
+
+.. function:: getmembers(object[, predicate])
+
+   Return all the members of an object in a list of (name, value) pairs sorted by
+   name.  If the optional *predicate* argument is supplied, only members for which
+   the predicate returns a true value are included.
+
+
+.. function:: getmoduleinfo(path)
+
+   Return a tuple of values that describe how Python will interpret the file
+   identified by *path* if it is a module, or ``None`` if it would not be
+   identified as a module.  The return tuple is ``(name, suffix, mode, mtype)``,
+   where *name* is the name of the module without the name of any enclosing
+   package, *suffix* is the trailing part of the file name (which may not be a
+   dot-delimited extension), *mode* is the :func:`open` mode that would be used
+   (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the
+   module.  *mtype* will have a value which can be compared to the constants
+   defined in the :mod:`imp` module; see the documentation for that module for
+   more information on module types.
+
+
+.. function:: getmodulename(path)
+
+   Return the name of the module named by the file *path*, without including the
+   names of enclosing packages.  This uses the same algorithm as the interpreter
+   uses when searching for modules.  If the name cannot be matched according to the
+   interpreter's rules, ``None`` is returned.
+
+
+.. function:: ismodule(object)
+
+   Return true if the object is a module.
+
+
+.. function:: isclass(object)
+
+   Return true if the object is a class.
+
+
+.. function:: ismethod(object)
+
+   Return true if the object is a method.
+
+
+.. function:: isfunction(object)
+
+   Return true if the object is a Python function or unnamed (lambda) function.
+
+
+.. function:: istraceback(object)
+
+   Return true if the object is a traceback.
+
+
+.. function:: isframe(object)
+
+   Return true if the object is a frame.
+
+
+.. function:: iscode(object)
+
+   Return true if the object is a code.
+
+
+.. function:: isbuiltin(object)
+
+   Return true if the object is a built-in function.
+
+
+.. function:: isroutine(object)
+
+   Return true if the object is a user-defined or built-in function or method.
+
+
+.. function:: ismethoddescriptor(object)
+
+   Return true if the object is a method descriptor, but not if ismethod() or
+   isclass() or isfunction() are true.
+
+   This is new as of Python 2.2, and, for example, is true of int.__add__. An
+   object passing this test has a __get__ attribute but not a __set__ attribute,
+   but beyond that the set of attributes varies.  __name__ is usually sensible, and
+   __doc__ often is.
+
+   Methods implemented via descriptors that also pass one of the other tests return
+   false from the ismethoddescriptor() test, simply because the other tests promise
+   more -- you can, e.g., count on having the im_func attribute (etc) when an
+   object passes ismethod().
+
+
+.. function:: isdatadescriptor(object)
+
+   Return true if the object is a data descriptor.
+
+   Data descriptors have both a __get__ and a __set__ attribute.  Examples are
+   properties (defined in Python), getsets, and members.  The latter two are
+   defined in C and there are more specific tests available for those types, which
+   is robust across Python implementations.  Typically, data descriptors will also
+   have __name__ and __doc__ attributes (properties, getsets, and members have both
+   of these attributes), but this is not guaranteed.
+
+   .. versionadded:: 2.3
+
+
+.. function:: isgetsetdescriptor(object)
+
+   Return true if the object is a getset descriptor.
+
+   getsets are attributes defined in extension modules via ``PyGetSetDef``
+   structures.  For Python implementations without such types, this method will
+   always return ``False``.
+
+   .. versionadded:: 2.5
+
+
+.. function:: ismemberdescriptor(object)
+
+   Return true if the object is a member descriptor.
+
+   Member descriptors are attributes defined in extension modules via
+   ``PyMemberDef`` structures.  For Python implementations without such types, this
+   method will always return ``False``.
+
+   .. versionadded:: 2.5
+
+
+.. _inspect-source:
+
+Retrieving source code
+----------------------
+
+
+.. function:: getdoc(object)
+
+   Get the documentation string for an object. All tabs are expanded to spaces.  To
+   clean up docstrings that are indented to line up with blocks of code, any
+   whitespace than can be uniformly removed from the second line onwards is
+   removed.
+
+
+.. function:: getcomments(object)
+
+   Return in a single string any lines of comments immediately preceding the
+   object's source code (for a class, function, or method), or at the top of the
+   Python source file (if the object is a module).
+
+
+.. function:: getfile(object)
+
+   Return the name of the (text or binary) file in which an object was defined.
+   This will fail with a :exc:`TypeError` if the object is a built-in module,
+   class, or function.
+
+
+.. function:: getmodule(object)
+
+   Try to guess which module an object was defined in.
+
+
+.. function:: getsourcefile(object)
+
+   Return the name of the Python source file in which an object was defined.  This
+   will fail with a :exc:`TypeError` if the object is a built-in module, class, or
+   function.
+
+
+.. function:: getsourcelines(object)
+
+   Return a list of source lines and starting line number for an object. The
+   argument may be a module, class, method, function, traceback, frame, or code
+   object.  The source code is returned as a list of the lines corresponding to the
+   object and the line number indicates where in the original source file the first
+   line of code was found.  An :exc:`IOError` is raised if the source code cannot
+   be retrieved.
+
+
+.. function:: 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 is
+   returned as a single string.  An :exc:`IOError` is raised if the source code
+   cannot be retrieved.
+
+
+.. _inspect-classes-functions:
+
+Classes and functions
+---------------------
+
+
+.. function:: getclasstree(classes[, unique])
+
+   Arrange the given list of classes into a hierarchy of nested lists. Where a
+   nested list appears, it contains classes derived from the class whose entry
+   immediately precedes the list.  Each entry is a 2-tuple containing a class and a
+   tuple of its base classes.  If the *unique* argument is true, exactly one entry
+   appears in the returned structure for each class in the given list.  Otherwise,
+   classes using multiple inheritance and their descendants will appear multiple
+   times.
+
+
+.. function:: getargspec(func)
+
+   Get the names and default values of a function's arguments. A tuple of four
+   things is returned: ``(args, varargs, varkw, defaults)``. *args* is a list of
+   the argument names (it may contain nested lists). *varargs* and *varkw* are the
+   names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a tuple of
+   default argument values or None if there are no default arguments; if this tuple
+   has *n* elements, they correspond to the last *n* elements listed in *args*.
+
+
+.. function:: getargvalues(frame)
+
+   Get information about arguments passed into a particular frame. A tuple of four
+   things is returned: ``(args, varargs, varkw, locals)``. *args* is a list of the
+   argument names (it may contain nested lists). *varargs* and *varkw* are the
+   names of the ``*`` and ``**`` arguments or ``None``. *locals* is the locals
+   dictionary of the given frame.
+
+
+.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+
+   Format a pretty argument spec from the four values returned by
+   :func:`getargspec`.  The format\* arguments are the corresponding optional
+   formatting functions that are called to turn names and values into strings.
+
+
+.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+
+   Format a pretty argument spec from the four values returned by
+   :func:`getargvalues`.  The format\* arguments are the corresponding optional
+   formatting functions that are called to turn names and values into strings.
+
+
+.. function:: getmro(cls)
+
+   Return a tuple of class cls's base classes, including cls, in method resolution
+   order.  No class appears more than once in this tuple. Note that the method
+   resolution order depends on cls's type.  Unless a very peculiar user-defined
+   metatype is in use, cls will be the first element of the tuple.
+
+
+.. _inspect-stack:
+
+The interpreter stack
+---------------------
+
+When the following functions return "frame records," each record is a tuple of
+six items: the frame object, the filename, the line number of the current line,
+the function name, a list of lines of context from the source code, and the
+index of the current line within that list.
+
+.. warning::
+
+   Keeping references to frame objects, as found in the first element of the frame
+   records these functions return, can cause your program to create reference
+   cycles.  Once a reference cycle has been created, the lifespan of all objects
+   which can be accessed from the objects which form the cycle can become much
+   longer even if Python's optional cycle detector is enabled.  If such cycles must
+   be created, it is important to ensure they are explicitly broken to avoid the
+   delayed destruction of objects and increased memory consumption which occurs.
+
+   Though the cycle detector will catch these, destruction of the frames (and local
+   variables) can be made deterministic by removing the cycle in a
+   :keyword:`finally` clause.  This is also important if the cycle detector was
+   disabled when Python was compiled or using :func:`gc.disable`.  For example::
+
+      def handle_stackframe_without_leak():
+          frame = inspect.currentframe()
+          try:
+              # do something with the frame
+          finally:
+              del frame
+
+The optional *context* argument supported by most of these functions specifies
+the number of lines of context to return, which are centered around the current
+line.
+
+
+.. function:: getframeinfo(frame[, context])
+
+   Get information about a frame or traceback object.  A 5-tuple is returned, the
+   last five elements of the frame's frame record.
+
+
+.. function:: getouterframes(frame[, context])
+
+   Get a list of frame records for a frame and all outer frames.  These frames
+   represent the calls that lead to the creation of *frame*. The first entry in the
+   returned list represents *frame*; the last entry represents the outermost call
+   on *frame*'s stack.
+
+
+.. function:: getinnerframes(traceback[, context])
+
+   Get a list of frame records for a traceback's frame and all inner frames.  These
+   frames represent calls made as a consequence of *frame*.  The first entry in the
+   list represents *traceback*; the last entry represents where the exception was
+   raised.
+
+
+.. function:: currentframe()
+
+   Return the frame object for the caller's stack frame.
+
+
+.. function:: stack([context])
+
+   Return a list of frame records for the caller's stack.  The first entry in the
+   returned list represents the caller; the last entry represents the outermost
+   call on the stack.
+
+
+.. function:: trace([context])
+
+   Return a list of frame records for the stack between the current frame and the
+   frame in which an exception currently being handled was raised in.  The first
+   entry in the list represents the caller; the last entry represents where the
+   exception was raised.
+