1 """Parse a Python module and describe its classes and functions.
7     readmodule_ex(module, path=None)
8 where module is the name of a Python module, and path is an optional
9 list of directories where the module is to be searched.  If present,
12 classes and functions defined in the module (including classes that are
20     module  -- name of the module;
21     name    -- name of the object;
22     file    -- file in which the object is defined;
23     lineno  -- line in the file where the object's definition starts;
24     end_lineno -- line in the file where the object's definition ends;
25     parent  -- parent of this object, if any;
26     children -- nested objects contained in this object.
31     is_async -- if a function is defined with an 'async' prefix
35     super   -- list of super classes (Class instances if possible);
36     methods -- mapping of method names to beginning line numbers.
55     def __init__(self, module, name, file, lineno, end_lineno, parent):  argument
56         self.module = module
61         self.parent = parent
63         if parent is not None:
64             parent.children[name] = self
67 # Odd Function and Class signatures are for back-compatibility.
70     def __init__(self, module, name, file, lineno,  argument
71                  parent=None, is_async=False, *, end_lineno=None):  argument
72         super().__init__(module, name, file, lineno, end_lineno, parent)
74         if isinstance(parent, Class):
75             parent.methods[name] = lineno
80     def __init__(self, module, name, super_, file, lineno,  argument
81                  parent=None, *, end_lineno=None):  argument
82         super().__init__(module, name, file, lineno, end_lineno, parent)
91     return Function(ob.module, func_name, ob.file, lineno,
92                     parent=ob, is_async=is_async, end_lineno=end_lineno)
96     return Class(ob.module, class_name, super, ob.file, lineno,
97                  parent=ob, end_lineno=end_lineno)
100 def readmodule(module, path=None):  argument
101     """Return Class objects for the top-level classes in module.
107     for key, value in _readmodule(module, path or []).items():
112 def readmodule_ex(module, path=None):  argument
113     """Return a dictionary with all functions and classes in module.
115     Search for module in PATH + sys.path.
119     return _readmodule(module, path or [])
122 def _readmodule(module, path, inpackage=None):  argument
127     package search path; otherwise, we are searching for a top-level
128     module, and path is combined with sys.path.
130     # Compute the full module name (prepending inpackage if set).
132         fullmodule = "%s.%s" % (inpackage, module)
134         fullmodule = module
140     # Initialize the dict for this module's contents.
143     # Check if it is a built-in module; we don't do much for these.
144     if module in sys.builtin_module_names and inpackage is None:
145         _modules[module] = tree
148     # Check for a dotted module name.
149     i = module.rfind('.')
151         package = module[:i]
152         submodule = module[i+1:]
153         parent = _readmodule(package, path, inpackage)
156         if not '__path__' in parent:
158         return _readmodule(submodule, parent['__path__'], package)
160     # Search the path for the module.
168         raise ModuleNotFoundError(f"no module named {fullmodule!r}", name=fullmodule)
170     # Is module a package?
176         # If module is not Python source, we cannot do anything.
187     def __init__(self, module, path, file, tree, inpackage):  argument
191         self.module = module
203                 # Super class form is module.class:
204                 # look in module for class.
205                 *_, module, class_ = names
206                 if module in _modules:
207                     bases.append(_modules[module].get(class_, name))
211         parent = self.stack[-1] if self.stack else None
212         class_ = Class(self.module, node.name, bases, self.file, node.lineno,
213                        parent=parent, end_lineno=node.end_lineno)
214         if parent is None:
221         parent = self.stack[-1] if self.stack else None
222         function = Function(self.module, node.name, self.file, node.lineno,
223                             parent, is_async, end_lineno=node.end_lineno)
224         if parent is None:
237         for module in node.names:
240                     _readmodule(module.name, self.path, self.inpackage)
242                     _readmodule(module.name, [])
244                 # If we can't find or parse the imported module,
245                 # too bad -- don't die here.
252             module = "." * node.level
253             if node.module:
254                 module += node.module
255             module = _readmodule(module, self.path, self.inpackage)
260             if name.name in module:
261                 self.tree[name.asname or name.name] = module[name.name]
263                 for import_name, import_value in module.items():
276     "Print module output (default this file) for quick visual check."
286             mod = mod[:-3]