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

Author: csabella

Doc/library/pyclbr.rst

@@ -39,78 +39,77 @@ modules.
    path.
 
 
-.. _pyclbr-class-objects:
+.. _pyclbr-object-objects:
 
-Class Objects
--------------
-
-The :class:`Class` objects used as values in the dictionary returned by
-:func:`readmodule` and :func:`readmodule_ex` provide the following data
-attributes:
-
-
-.. attribute:: Class.module
+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 name of the module defining the class described by the class descriptor.
 
+.. attribute:: Object.module
 
-.. attribute:: Class.name
+   The name of the module defining the object described.
 
-   The name of the class.
 
+.. attribute:: Object.name
 
-.. attribute:: Class.super
+   The name of the object.
 
-   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.file
 
-.. attribute:: Class.methods
+   Name of the file in which the object was defined.
 
-   A dictionary mapping method names to line numbers.
 
+.. attribute:: Object.lineno
 
-.. attribute:: Class.file
+   The line number in the file named by :attr:`~Object.file` where
+   the definition of the object started.
 
-   Name of the file containing the ``class`` statement defining the class.
 
+.. attribute:: Object.parent
 
-.. attribute:: Class.lineno
+   The parent of this object, if any.
 
-   The line number of the ``class`` statement within the file named by
-   :attr:`~Class.file`.
 
+.. attribute:: Object.objects
 
-.. _pyclbr-function-objects:
+   A dictionary mapping object names to the objects that are defined inside the
+   namespace created by the current object.
 
-Function Objects
-----------------
 
-The :class:`Function` objects used as values in the dictionary returned by
-:func:`readmodule_ex` provide the following attributes:
+.. _pyclbr-class-objects:
 
+Class Objects
+-------------
 
-.. attribute:: Function.module
+The :class:`Class` objects used as values in the dictionary returned by
+:func:`readmodule` and :func:`readmodule_ex` provide the following extra
+data members:
 
-   The name of the module defining the function described by the function
-   descriptor.
 
+.. attribute:: Class.super
 
-.. attribute:: Function.name
+   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.
 
-   The name of the function.
 
+.. attribute:: Class.methods
 
-.. attribute:: Function.file
+   A dictionary mapping method names to line numbers.
 
-   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`.
+The :class:`Function` objects used as values in the dictionary returned by
+:func:`readmodule_ex` provide only the members already defined by
+:class:`Class` objects.
 

Lib/pyclbr.py

@@ -15,14 +15,23 @@
 is present for packages: the key '__path__' has a list as its value
 which contains the package search path.
 
-A class is described by the class Class in this module.  Instances
-of this class have the following instance variables:
-        module -- the module name
-        name -- the name of the class
-        super -- a list of super classes (Class instances)
+Classes and functions have a common superclass in this module, the Object
+class. Every instance of this class have the following instance variables:
+        module  -- the module name
+        name    -- the name of the object
+        file    -- the file in which the object was defined
+        lineno  -- the line in the file on which the definition of the object
+                   started
+        parent  -- the parent of this object, if any
+        objects -- the other classes and function this object may contain
+The 'objects' attribute is a dictionary where each key/value pair corresponds
+to the name of the object and the object itself.
+
+A class is described by the class Class in this module. Instances
+of this class have the following instance variables (plus the ones from
+Object):
+        super   -- a list of super classes (Class instances)
         methods -- a dictionary of methods
-        file -- the file in which the class was defined
-        lineno -- the line in the file on which the class statement occurred
 The dictionary of methods uses the method names as keys and the line
 numbers on which the method was defined as values.
 If the name of a super class is not recognized, the corresponding
@@ -32,11 +41,6 @@
 shouldn't happen often.
 
 A function is described by the class Function in this module.
-Instances of this class have the following instance variables:
-        module -- the module name
-        name -- the name of the class
-        file -- the file in which the class was defined
-        lineno -- the line in the file on which the class statement occurred
 """
 
 import io
@@ -45,33 +49,54 @@
 import tokenize
 from token import NAME, DEDENT, OP
 
-__all__ = ["readmodule", "readmodule_ex", "Class", "Function"]
+__all__ = ["readmodule", "readmodule_ex", "Object", "Class", "Function"]
 
 _modules = {}                           # cache of modules we've seen
 
-# each Python class is represented by an instance of this class
-class Class:
-    '''Class to represent a Python class.'''
-    def __init__(self, module, name, super, file, lineno):
+
+class Object:
+    """Class to represent a Python object."""
+    def __init__(self, module, name, file, lineno, parent):
         self.module = module
         self.name = name
+        self.file = file
+        self.lineno = lineno
+        self.parent = parent
+        self.objects = {}
+
+    def _addobject(self, name, obj):
+        self.objects[name] = obj
+
+
+# each Python class is represented by an instance of this class
+class Class(Object):
+    '''Class to represent a Python class.'''
+    def __init__(self, module, name, super, file, lineno, parent=None):
+        Object.__init__(self, module, name, file, lineno, parent)
         if super is None:
             super = []
         self.super = super
         self.methods = {}
-        self.file = file
-        self.lineno = lineno
 
     def _addmethod(self, name, lineno):
         self.methods[name] = lineno
 
-class Function:
+
+class Function(Object):
     '''Class to represent a top-level Python function'''
-    def __init__(self, module, name, file, lineno):
-        self.module = module
-        self.name = name
-        self.file = file
-        self.lineno = lineno
+    def __init__(self, module, name, file, lineno, parent=None):
+        Object.__init__(self, module, name, file, lineno, parent)
+
+
+def _newfunction(ob, name, lineno):
+    '''Helper function for creating a nested function or a method.'''
+    return Function(ob.module, name, ob.file, lineno, ob)
+
+
+def _newclass(ob, name, super, lineno):
+    '''Helper function for creating a nested class.'''
+    return Class(ob.module, name, super, ob.file, lineno, ob)
+
 
 def readmodule(module, path=None):
     '''Backwards compatible interface.
@@ -138,7 +163,6 @@ def _readmodule(module, path, inpackage=None):
         search_path = path
     else:
         search_path = path + sys.path
-    # XXX This will change once issue19944 lands.
     spec = importlib.util._find_spec_from_path(fullmodule, search_path)
     _modules[fullmodule] = dict
     # is module a package?
@@ -174,17 +198,22 @@ def _readmodule(module, path, inpackage=None):
                 tokentype, meth_name, start = next(g)[0:3]
                 if tokentype != NAME:
                     continue # Syntax error
+                cur_func = None
                 if stack:
-                    cur_class = stack[-1][0]
-                    if isinstance(cur_class, Class):
-                        # it's a method
-                        cur_class._addmethod(meth_name, lineno)
-                    # else it's a nested def
+                    cur_obj = stack[-1][0]
+                    if isinstance(cur_obj, Object):
+                        # It's a nested function or a method.
+                        cur_func = _newfunction(cur_obj, meth_name, lineno)
+                        cur_obj._addobject(meth_name, cur_func)
+
+                        if isinstance(cur_obj, Class):
+                            # it's a method
+                            cur_obj._addmethod(meth_name, lineno)
                 else:
                     # it's a function
-                    dict[meth_name] = Function(fullmodule, meth_name,
-                                               fname, lineno)
-                stack.append((None, thisindent)) # Marker for nested fns
+                    cur_func = Function(fullmodule, meth_name, fname, lineno)
+                    dict[meth_name] = cur_func
+                stack.append((cur_func, thisindent))  # Marker for nested fns.
             elif token == 'class':
                 lineno, thisindent = start
                 # close previous nested classes and defs
@@ -235,9 +264,16 @@ def _readmodule(module, path, inpackage=None):
                             super.append(token)
                         # expressions in the base list are not supported
                     inherit = names
-                cur_class = Class(fullmodule, class_name, inherit,
-                                  fname, lineno)
-                if not stack:
+                if stack:
+                    cur_obj = stack[-1][0]
+                    if isinstance(cur_obj, Object):
+                        # Either a nested class or a class inside a function.
+                        cur_class = _newclass(cur_obj, class_name, inherit,
+                                              lineno)
+                        cur_obj._addobject(class_name, cur_class)
+                else:
+                    cur_class = Class(fullmodule, class_name, inherit,
+                                      fname, lineno)
                     dict[class_name] = cur_class
                 stack.append((cur_class, thisindent))
             elif token == 'import' and start[1] == 0:
@@ -284,6 +320,7 @@ def _readmodule(module, path, inpackage=None):
     f.close()
     return dict
 
+
 def _getnamelist(g):
     # Helper to get a comma-separated list of dotted names plus 'as'
     # clauses.  Return a list of pairs (name, name2) where name2 is
@@ -304,6 +341,7 @@ def _getnamelist(g):
             break
     return names
 
+
 def _getname(g):
     # Helper to get a dotted name, return a pair (name, token) where
     # name is the dotted name, or None if there was no dotted name,
@@ -323,10 +361,10 @@ def _getname(g):
         parts.append(token)
     return (".".join(parts), token)
 
+
 def _main():
     # Main program for testing.
     import os
-    from operator import itemgetter
     mod = sys.argv[1]
     if os.path.exists(mod):
         path = [os.path.dirname(mod)]
@@ -336,17 +374,28 @@ def _main():
     else:
         path = []
     dict = readmodule_ex(mod, path)
-    objs = list(dict.values())
-    objs.sort(key=lambda a: getattr(a, 'lineno', 0))
-    for obj in objs:
+    lineno_key = lambda a: getattr(a, 'lineno', 0)
+    objs = sorted(dict.values(), key=lineno_key, reverse=True)
+    indent_level = 2
+    while objs:
+        obj = objs.pop()
+        if isinstance(obj, list):
+            # Value of a __path__ key
+            continue
+        if not hasattr(obj, 'indent'):
+            obj.indent = 0
+
+        if isinstance(obj, Object):
+            new_objs = sorted(obj.objects.values(),
+                              key=lineno_key, reverse=True)
+            for ob in new_objs:
+                ob.indent = obj.indent + indent_level
+            objs.extend(new_objs)
         if isinstance(obj, Class):
-            print("class", obj.name, obj.super, obj.lineno)
-            methods = sorted(obj.methods.items(), key=itemgetter(1))
-            for name, lineno in methods:
-                if name != "__path__":
-                    print("  def", name, lineno)
+            print("{}class {} {} {}"
+                  .format(' ' * obj.indent, obj.name, obj.super, obj.lineno))
         elif isinstance(obj, Function):
-            print("def", obj.name, obj.lineno)
+            print("{}def {} {}".format(' ' * obj.indent, obj.name, obj.lineno))
 
 if __name__ == "__main__":
     _main()