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----------------
61Class :class:`Function` instances describe functions defined by def
62statements.  They have the following attributes:
63
64
65.. attribute:: Function.file
66
67   Name of the file in which the function is defined.
68
69
70.. attribute:: Function.module
71
72   The name of the module defining the function described.
73
74
75.. attribute:: Function.name
76
77   The name of the function.
78
79
80.. attribute:: Function.lineno
81
82   The line number in the file where the definition starts.
83
84
85.. attribute:: Function.parent
86
87   For top-level functions, None.  For nested functions, the parent.
88
89   .. versionadded:: 3.7
90
91
92.. attribute:: Function.children
93
94   A dictionary mapping names to descriptors for nested functions and
95   classes.
96
97   .. versionadded:: 3.7
98
99
100.. _pyclbr-class-objects:
101
102Class Objects
103-------------
104Class :class:`Class` instances describe classes defined by class
105statements.  They have the same attributes as Functions and two more.
106
107
108.. attribute:: Class.file
109
110   Name of the file in which the class is defined.
111
112
113.. attribute:: Class.module
114
115   The name of the module defining the class described.
116
117
118.. attribute:: Class.name
119
120   The name of the class.
121
122
123.. attribute:: Class.lineno
124
125   The line number in the file where the definition starts.
126
127
128.. attribute:: Class.parent
129
130   For top-level classes, None.  For nested classes, the parent.
131
132   .. versionadded:: 3.7
133
134
135.. attribute:: Class.children
136
137   A dictionary mapping names to descriptors for nested functions and
138   classes.
139
140   .. versionadded:: 3.7
141
142
143.. attribute:: Class.super
144
145   A list of :class:`Class` objects which describe the immediate base
146   classes of the class being described.  Classes which are named as
147   superclasses but which are not discoverable by :func:`readmodule_ex`
148   are listed as a string with the class name instead of as
149   :class:`Class` objects.
150
151
152.. attribute:: Class.methods
153
154   A dictionary mapping method names to line numbers.  This can be
155   derived from the newer children dictionary, but remains for
156   back-compatibility.
157