1:mod:`pyclbr` --- Python class browser support
2==============================================
3
4.. module:: pyclbr
5   :synopsis: Supports information extraction for a Python class 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
33.. function:: readmodule_ex(module, path=None)
34
35   Return a dictionary-based tree containing a function or class
36   descriptors for each function and class defined in the module with a
37   ``def`` or ``class`` statement.  The returned dictionary maps
38   module-level function and class names to their descriptors.  Nested
39   objects are entered into the children dictionary of their parent.  As
40   with readmodule, *module* names the module to be read and *path* is
41   prepended to sys.path.  If the module being read is a package, the
42   returned dictionary has a key ``'__path__'`` whose value is a list
43   containing the package search path.
44
45.. versionadded:: 3.7
46   Descriptors for nested definitions.  They are accessed through the
47   new children attibute.  Each has a new parent attribute.
48
49The descriptors returned by these functions are instances of
50Function and Class classes.  Users are not expected to create instances
51of these classes.
52
53
54.. _pyclbr-function-objects:
55
56Function Objects
57----------------
58Class :class:`Function` instances describe functions defined by def
59statements.  They have the following attributes:
60
61
62.. attribute:: Function.file
63
64   Name of the file in which the function is defined.
65
66
67.. attribute:: Function.module
68
69   The name of the module defining the function described.
70
71
72.. attribute:: Function.name
73
74   The name of the function.
75
76
77.. attribute:: Function.lineno
78
79   The line number in the file where the definition starts.
80
81
82.. attribute:: Function.parent
83
84   For top-level functions, None.  For nested functions, the parent.
85
86   .. versionadded:: 3.7
87
88
89.. attribute:: Function.children
90
91   A dictionary mapping names to descriptors for nested functions and
92   classes.
93
94   .. versionadded:: 3.7
95
96
97.. _pyclbr-class-objects:
98
99Class Objects
100-------------
101Class :class:`Class` instances describe classes defined by class
102statements.  They have the same attributes as Functions and two more.
103
104
105.. attribute:: Class.file
106
107   Name of the file in which the class is defined.
108
109
110.. attribute:: Class.module
111
112   The name of the module defining the class described.
113
114
115.. attribute:: Class.name
116
117   The name of the class.
118
119
120.. attribute:: Class.lineno
121
122   The line number in the file where the definition starts.
123
124
125.. attribute:: Class.parent
126
127   For top-level classes, None.  For nested classes, the parent.
128
129   .. versionadded:: 3.7
130
131
132.. attribute:: Class.children
133
134   A dictionary mapping names to descriptors for nested functions and
135   classes.
136
137   .. versionadded:: 3.7
138
139
140.. attribute:: Class.super
141
142   A list of :class:`Class` objects which describe the immediate base
143   classes of the class being described.  Classes which are named as
144   superclasses but which are not discoverable by :func:`readmodule_ex`
145   are listed as a string with the class name instead of as
146   :class:`Class` objects.
147
148
149.. attribute:: Class.methods
150
151   A dictionary mapping method names to line numbers.  This can be
152   derived from the newer children dictionary, but remains for
153   back-compatibility.
154