1:mod:`!pyclbr` --- Python module browser support 2================================================ 3 4.. module:: pyclbr 5 :synopsis: Supports information extraction for a Python module browser. 6 7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 8 9**Source code:** :source:`Lib/pyclbr.py` 10 11-------------- 12 13The :mod:`pyclbr` module provides limited information about the 14functions, classes, and methods defined in a Python-coded module. The 15information is sufficient to implement a module browser. The 16information is extracted from the Python source code rather than by 17importing the module, so this module is safe to use with untrusted code. 18This restriction makes it impossible to use this module with modules not 19implemented in Python, including all standard and optional extension 20modules. 21 22 23.. function:: readmodule(module, path=None) 24 25 Return a dictionary mapping module-level class names to class 26 descriptors. If possible, descriptors for imported base classes are 27 included. Parameter *module* is a string with the name of the module 28 to read; it may be the name of a module within a package. If given, 29 *path* is a sequence of directory paths prepended to ``sys.path``, 30 which is used to locate the module source code. 31 32 This function is the original interface and is only kept for back 33 compatibility. It returns a filtered version of the following. 34 35 36.. function:: readmodule_ex(module, path=None) 37 38 Return a dictionary-based tree containing a function or class 39 descriptors for each function and class defined in the module with a 40 ``def`` or ``class`` statement. The returned dictionary maps 41 module-level function and class names to their descriptors. Nested 42 objects are entered into the children dictionary of their parent. As 43 with readmodule, *module* names the module to be read and *path* is 44 prepended to sys.path. If the module being read is a package, the 45 returned dictionary has a key ``'__path__'`` whose value is a list 46 containing the package search path. 47 48.. versionadded:: 3.7 49 Descriptors for nested definitions. They are accessed through the 50 new children attribute. Each has a new parent attribute. 51 52The descriptors returned by these functions are instances of 53Function and Class classes. Users are not expected to create instances 54of these classes. 55 56 57.. _pyclbr-function-objects: 58 59Function Objects 60---------------- 61 62.. class:: Function 63 64 Class :class:`!Function` instances describe functions defined by def 65 statements. They have the following attributes: 66 67 68 .. attribute:: file 69 70 Name of the file in which the function is defined. 71 72 73 .. attribute:: module 74 75 The name of the module defining the function described. 76 77 78 .. attribute:: name 79 80 The name of the function. 81 82 83 .. attribute:: lineno 84 85 The line number in the file where the definition starts. 86 87 88 .. attribute:: parent 89 90 For top-level functions, ``None``. For nested functions, the parent. 91 92 .. versionadded:: 3.7 93 94 95 .. attribute:: children 96 97 A :class:`dictionary <dict>` mapping names to descriptors for nested functions and 98 classes. 99 100 .. versionadded:: 3.7 101 102 103 .. attribute:: is_async 104 105 ``True`` for functions that are defined with the 106 :keyword:`async <async def>` prefix, ``False`` otherwise. 107 108 .. versionadded:: 3.10 109 110 111.. _pyclbr-class-objects: 112 113Class Objects 114------------- 115 116.. class:: Class 117 118 Class :class:`!Class` instances describe classes defined by class 119 statements. They have the same attributes as :class:`Functions <Function>` 120 and two more. 121 122 123 .. attribute:: file 124 125 Name of the file in which the class is defined. 126 127 128 .. attribute:: module 129 130 The name of the module defining the class described. 131 132 133 .. attribute:: name 134 135 The name of the class. 136 137 138 .. attribute:: lineno 139 140 The line number in the file where the definition starts. 141 142 143 .. attribute:: parent 144 145 For top-level classes, ``None``. For nested classes, the parent. 146 147 .. versionadded:: 3.7 148 149 150 .. attribute:: children 151 152 A dictionary mapping names to descriptors for nested functions and 153 classes. 154 155 .. versionadded:: 3.7 156 157 158 .. attribute:: super 159 160 A list of :class:`!Class` objects which describe the immediate base 161 classes of the class being described. Classes which are named as 162 superclasses but which are not discoverable by :func:`readmodule_ex` 163 are listed as a string with the class name instead of as 164 :class:`!Class` objects. 165 166 167 .. attribute:: methods 168 169 A :class:`dictionary <dict>` mapping method names to line numbers. 170 This can be derived from the newer :attr:`children` dictionary, 171 but remains for 172 back-compatibility. 173