bpo-6691: Support for nested classes and functions in pyclbr

Doc/library/pyclbr.rst

@@ -11,13 +11,12 @@
 --------------
 
 The :mod:`pyclbr` module can be used to determine some limited information
-about the classes, methods and top-level functions defined in a module.  The
-information provided is sufficient to implement a traditional three-pane
-class browser.  The information is extracted from the source code rather
-than by importing the module, so this module is safe to use with untrusted
-code.  This restriction makes it impossible to use this module with modules
-not implemented in Python, including all standard and optional extension
-modules.
+about the classes, methods, and functions defined in a module.  The
+information provided is sufficient to implement a module browser.  The
+information is extracted from the source code rather than by importing the
+module, so this module is safe to use with untrusted code.  This restriction
+makes it impossible to use this module with modules not implemented in Python,
+including all standard and optional extension modules.
 
 
 .. function:: readmodule(module, path=None)
@@ -32,85 +31,102 @@ modules.
 .. function:: readmodule_ex(module, path=None)
 
    Like :func:`readmodule`, but the returned dictionary, in addition to
-   mapping class names to class descriptor objects, also maps top-level
-   function names to function descriptor objects.  Moreover, if the module
+   mapping class names to class descriptor objects, also maps function
+   names to function descriptor objects.  Moreover, if the module
    being read is a package, the key ``'__path__'`` in the returned
    dictionary has as its value a list which contains the package search
    path.
 
 
-.. _pyclbr-class-objects:
+.. _pyclbr-object-objects:
 
-Class Objects
--------------
+Object Objects
+--------------
+The class :class:`Object` is the base class for the classes
+:class:`Class` and :class:`Function`. It provides the following
+data members:
 
-The :class:`Class` objects used as values in the dictionary returned by
-:func:`readmodule` and :func:`readmodule_ex` provide the following data
-attributes:
 
+.. attribute:: Object.module
 
-.. attribute:: Class.module
+   The name of the module defining the object described.
 
-   The name of the module defining the class described by the class descriptor.
 
+.. attribute:: Object.name
 
-.. attribute:: Class.name
+   The name of the object.
 
-   The name of the class.
 
+.. attribute:: Object.file
 
-.. attribute:: Class.super
+   Name of the file in which the object was defined.
 
-   A list of :class:`Class` objects which describe the immediate base
-   classes of the class being described.  Classes which are named as
-   superclasses but which are not discoverable by :func:`readmodule` are
-   listed as a string with the class name instead of as :class:`Class`
-   objects.
 
+.. attribute:: Object.lineno
 
-.. attribute:: Class.methods
+   The line number in the file named by :attr:`~Object.file` where
+   the definition of the object started.
 
-   A dictionary mapping method names to line numbers.
 
+.. attribute:: Object.parent
 
-.. attribute:: Class.file
+   The parent of this object, if any.
 
-   Name of the file containing the ``class`` statement defining the class.
+   .. versionadded:: 3.7
 
 
-.. attribute:: Class.lineno
+.. attribute:: Object.children
 
-   The line number of the ``class`` statement within the file named by
-   :attr:`~Class.file`.
+   A dictionary mapping object names to the objects that are defined inside the
+   namespace created by the current object.
 
+   .. versionadded:: 3.7
 
-.. _pyclbr-function-objects:
 
-Function Objects
-----------------
+.. versionchanged:: 3.7
+   :class:`Object` was added as a base class for :class:`Class` and
+   :class:`Function` and, except as otherwise noted, the attributes
+   were previously common to those two classes.
 
-The :class:`Function` objects used as values in the dictionary returned by
-:func:`readmodule_ex` provide the following attributes:
 
 
-.. attribute:: Function.module
+.. _pyclbr-class-objects:
 
-   The name of the module defining the function described by the function
-   descriptor.
+Class Objects
+-------------
+
+:class:`Class` is a subclass of :class:`Object` whose objects are used as values
+in the dictionary returned by :func:`readmodule` and :func:`readmodule_ex`.
+In addition to the attributes from :class:`Object`, :class:`Class` objects
+also provide the following attributes:
+
+
+.. attribute:: Class.super
+
+   A list of :class:`Class` objects which describe the immediate base
+   classes of the class being described.  Classes which are named as
+   superclasses but which are not discoverable by :func:`readmodule` are
+   listed as a string with the class name instead of as :class:`Class`
+   objects.
 
 
-.. attribute:: Function.name
+.. attribute:: Class.methods
 
-   The name of the function.
+   A dictionary mapping method names to line numbers.
 
 
-.. attribute:: Function.file
+.. versionchanged:: 3.7
+   :class:`Class` became a subclass of :class:`Object`.
 
-   Name of the file containing the ``def`` statement defining the function.
 
+.. _pyclbr-function-objects:
 
-.. attribute:: Function.lineno
+Function Objects
+----------------
 
-   The line number of the ``def`` statement within the file named by
-   :attr:`~Function.file`.
+:class:`Function` is a subclass of :class:`Object` whose objects are used as
+values in the dictionary returned by :func:`readmodule_ex`.  The only instance
+attributes are those from :class:`Object`.
 
+.. versionchanged:: 3.7
+   :class:`Function` became a subclass of :class:`Object`.