--- rest25/library/inspect.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/inspect.rst	2009-04-05 05:02:09.000000000 +0900
@@ -19,25 +19,25 @@
 
 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
+class or module. The sixteen 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)         |       |
 +-----------+-----------------+---------------------------+-------+
@@ -45,51 +45,80 @@
 +-----------+-----------------+---------------------------+-------+
 |           | __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 |       |
+|           | im_func or      | function object           |       |
+|           | __func__        | containing implementation |       |
 |           |                 | of method                 |       |
 +-----------+-----------------+---------------------------+-------+
-|           | im_self         | instance to which this    |       |
-|           |                 | method is bound, or       |       |
+|           | im_self or      | instance to which this    |       |
+|           | __self__        | method is bound, or       |       |
 |           |                 | ``None``                  |       |
 +-----------+-----------------+---------------------------+-------+
 | function  | __doc__         | documentation string      |       |
 +-----------+-----------------+---------------------------+-------+
 |           | __name__        | name with which this      |       |
 |           |                 | function was defined      |       |
 +-----------+-----------------+---------------------------+-------+
 |           | func_code       | code object containing    |       |
 |           |                 | compiled function         |       |
-|           |                 | bytecode                  |       |
+|           |                 | :term:`bytecode`          |       |
 +-----------+-----------------+---------------------------+-------+
 |           | func_defaults   | tuple of any default      |       |
 |           |                 | values for arguments      |       |
 +-----------+-----------------+---------------------------+-------+
 |           | func_doc        | (same as __doc__)         |       |
 +-----------+-----------------+---------------------------+-------+
 |           | func_globals    | global namespace in which |       |
 |           |                 | this function was defined |       |
 +-----------+-----------------+---------------------------+-------+
 |           | func_name       | (same as __name__)        |       |
 +-----------+-----------------+---------------------------+-------+
+| generator | __iter__        | defined to support        |       |
+|           |                 | iteration over container  |       |
++-----------+-----------------+---------------------------+-------+
+|           | close           | raises new GeneratorExit  |       |
+|           |                 | exception inside the      |       |
+|           |                 | generator to terminate    |       |
+|           |                 | the iteration             |       |
++-----------+-----------------+---------------------------+-------+
+|           | gi_code         | code object               |       |
++-----------+-----------------+---------------------------+-------+
+|           | gi_frame        | frame object or possibly  |       |
+|           |                 | None once the generator   |       |
+|           |                 | has been exhausted        |       |
++-----------+-----------------+---------------------------+-------+
+|           | gi_running      | set to 1 when generator   |       |
+|           |                 | is executing, 0 otherwise |       |
++-----------+-----------------+---------------------------+-------+
+|           | next            | return the next item from |       |
+|           |                 | the container             |       |
++-----------+-----------------+---------------------------+-------+
+|           | send            | resumes the generator and |       |
+|           |                 | "sends" a value that      |       |
+|           |                 | becomes the result of the |       |
+|           |                 | current yield-expression  |       |
++-----------+-----------------+---------------------------+-------+
+|           | throw           | used to raise an          |       |
+|           |                 | exception inside the      |       |
+|           |                 | generator                 |       |
++-----------+-----------------+---------------------------+-------+
 | 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)                    |       |
@@ -186,37 +215,46 @@
 
 (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.
 
+   .. note::
+
+      :func:`getmembers` does not return metaclass attributes when the argument
+      is a class (this behavior is inherited from the :func:`dir` function).
+
 
 .. 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.
+   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.
+
+   .. versionchanged:: 2.6
+      Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode,
+      module_type)``.
 
 
 .. 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)
 
@@ -226,26 +264,37 @@
 .. 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.
+   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
+
+.. function:: isgeneratorfunction(object)
+
+   Return true if the object is a Python generator function.
+
+   .. versionadded:: 2.6
+
+.. function:: isgenerator(object)
+
+   Return true if the object is a generator.
 
+   .. versionadded:: 2.6
 
 .. 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)
@@ -253,89 +302,92 @@
    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:: isabstract(object)
+
+   Return true if the object is an abstract base class.
+
+   .. versionadded:: 2.6
+
 
 .. function:: ismethoddescriptor(object)
 
-   Return true if the object is a method descriptor, but not if ismethod() or
-   isclass() or isfunction() are true.
+   Return true if the object is a method descriptor, but not if :func:`ismethod`
+   or :func:`isclass` or :func:`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.
+   This is new as of Python 2.2, and, for example, is true of
+   ``int.__add__``. An object passing this test has a :attr:`__get__` attribute
+   but not a :attr:`__set__` attribute, but beyond that the set of attributes
+   varies.  :attr:`__name__` is usually sensible, and :attr:`__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().
+   Methods implemented via descriptors that also pass one of the other tests
+   return false from the :func:`ismethoddescriptor` test, simply because the
+   other tests promise more -- you can, e.g., count on having the
+   :attr:`im_func` attribute (etc) when an object passes :func:`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.
+   Data descriptors have both a :attr:`__get__` and a :attr:`__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 :attr:`__name__` and :attr:`__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``.
+   ``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.
+   Get the documentation string for an object, cleaned up with :func:`cleandoc`.
 
 
 .. 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.
@@ -364,24 +416,33 @@
    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.
 
 
+.. function:: cleandoc(doc)
+
+   Clean up indentation from docstrings that are indented to line up with blocks
+   of code.  Any whitespace that can be uniformly removed from the second line
+   onwards is removed.  Also, all tabs are expanded to spaces.
+
+   .. versionadded:: 2.6
+
+
 .. _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
@@ -390,33 +451,41 @@
    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*.
 
+   .. versionchanged:: 2.6
+      Returns a :term:`named tuple` ``ArgSpec(args, varargs, keywords,
+      defaults)``.
+
 
 .. 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.
 
+   .. versionchanged:: 2.6
+      Returns a :term:`named tuple` ``ArgInfo(args, varargs, keywords,
+      locals)``.
+
 
 .. 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
@@ -464,24 +533,28 @@
               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.
 
+   .. versionchanged:: 2.6
+      Returns a :term:`named tuple` ``Traceback(filename, lineno, function,
+      code_context, index)``.
+
 
 .. 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
