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,
10 path is prepended to the system search path sys.path.  The return value
11 is a dictionary.  The keys of the dictionary are the names of the
12 classes and functions defined in the module (including classes that are
14 instances of classes Class and Function.  One special key/value pair is
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.
27 The 'children' attribute is a dictionary mapping names to objects.
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.
37 If the name of a super class is not recognized, the corresponding
38 entry in the list of super classes is not a class instance but a
55     def __init__(self, module, name, file, lineno, end_lineno, parent):  argument
56         self.module = module
63         if parent is not None:
67 # Odd Function and Class signatures are for back-compatibility.
70     def __init__(self, module, name, file, lineno,  argument
72         super().__init__(module, name, file, lineno, end_lineno, parent)
80     def __init__(self, module, name, super_, file, lineno,  argument
82         super().__init__(module, name, file, lineno, end_lineno, parent)
91     return Function(ob.module, func_name, ob.file, lineno,
96     return Class(ob.module, class_name, super, ob.file, lineno,
100 def readmodule(module, path=None):  argument
101     """Return Class objects for the top-level classes in module.
103     This is the original interface, before Functions were added.
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
125     If inpackage is given, it must be the dotted name of the package in
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).
131     if inpackage is not None:
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:]
154         if inpackage is not None:
160     # Search the path for the module.
162     if inpackage is not None:
167     if spec is None:
168         raise ModuleNotFoundError(f"no module named {fullmodule!r}", name=fullmodule)
170     # Is module a package?
171     if spec.submodule_search_locations is not None:
176         # If module is not Python source, we cannot do anything.
179         if source is None:
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,
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,
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]
296             # Value is a __path__ key.