Debian Codegraph @

Doc/library/pyclbr.rst

raw
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. <[email protected]>
8
9 **Source code:** :source:`Lib/pyclbr.py`
10
11 --------------
12
13 The :mod:`!pyclbr` module provides limited information about the
14 functions, classes, and methods defined in a Python-coded module. The
15 information is sufficient to implement a module browser. The
16 information is extracted from the Python source code rather than by
17 importing the module, so this module is safe to use with untrusted code.
18 This restriction makes it impossible to use this module with modules not
19 implemented in Python, including all standard and optional extension
20 modules.
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
52 The descriptors returned by these functions are instances of
53 Function and Class classes. Users are not expected to create instances
54 of these classes.
55
56
57 .. _pyclbr-function-objects:
58
59 Function 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
113 Class 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.