blob: 13eaabf594700236b215eab3c44b9607185e0a45 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`pyclbr` --- Python class browser support
2==============================================
3
4.. module:: pyclbr
5 :synopsis: Supports information extraction for a Python class browser.
6.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
7
Raymond Hettingera1993682011-01-27 01:20:32 +00008**Source code:** :source:`Lib/pyclbr.py`
9
10--------------
Georg Brandl116aa622007-08-15 14:28:22 +000011
Christian Heimes81ee3ef2008-05-04 22:42:01 +000012The :mod:`pyclbr` module can be used to determine some limited information
13about the classes, methods and top-level functions defined in a module. The
14information provided is sufficient to implement a traditional three-pane
15class browser. The information is extracted from the source code rather
16than by importing the module, so this module is safe to use with untrusted
17code. This restriction makes it impossible to use this module with modules
18not implemented in Python, including all standard and optional extension
19modules.
Georg Brandl116aa622007-08-15 14:28:22 +000020
21
Georg Brandl18244152009-09-02 20:34:52 +000022.. function:: readmodule(module, path=None)
Georg Brandl116aa622007-08-15 14:28:22 +000023
Christian Heimes81ee3ef2008-05-04 22:42:01 +000024 Read a module and return a dictionary mapping class names to class
25 descriptor objects. The parameter *module* should be the name of a
26 module as a string; it may be the name of a module within a package. The
27 *path* parameter should be a sequence, and is used to augment the value
28 of ``sys.path``, which is used to locate module source code.
Georg Brandl116aa622007-08-15 14:28:22 +000029
30
Georg Brandl18244152009-09-02 20:34:52 +000031.. function:: readmodule_ex(module, path=None)
Georg Brandl116aa622007-08-15 14:28:22 +000032
Christian Heimes81ee3ef2008-05-04 22:42:01 +000033 Like :func:`readmodule`, but the returned dictionary, in addition to
34 mapping class names to class descriptor objects, also maps top-level
35 function names to function descriptor objects. Moreover, if the module
36 being read is a package, the key ``'__path__'`` in the returned
37 dictionary has as its value a list which contains the package search
38 path.
Georg Brandl116aa622007-08-15 14:28:22 +000039
40
41.. _pyclbr-class-objects:
42
Christian Heimes81ee3ef2008-05-04 22:42:01 +000043Class Objects
44-------------
Georg Brandl116aa622007-08-15 14:28:22 +000045
Christian Heimes81ee3ef2008-05-04 22:42:01 +000046The :class:`Class` objects used as values in the dictionary returned by
47:func:`readmodule` and :func:`readmodule_ex` provide the following data
Senthil Kumarana6bac952011-07-04 11:28:30 -070048attributes:
Georg Brandl116aa622007-08-15 14:28:22 +000049
50
Christian Heimes81ee3ef2008-05-04 22:42:01 +000051.. attribute:: Class.module
Georg Brandl116aa622007-08-15 14:28:22 +000052
53 The name of the module defining the class described by the class descriptor.
54
55
Christian Heimes81ee3ef2008-05-04 22:42:01 +000056.. attribute:: Class.name
Georg Brandl116aa622007-08-15 14:28:22 +000057
58 The name of the class.
59
60
Christian Heimes81ee3ef2008-05-04 22:42:01 +000061.. attribute:: Class.super
Georg Brandl116aa622007-08-15 14:28:22 +000062
Christian Heimes81ee3ef2008-05-04 22:42:01 +000063 A list of :class:`Class` objects which describe the immediate base
64 classes of the class being described. Classes which are named as
65 superclasses but which are not discoverable by :func:`readmodule` are
66 listed as a string with the class name instead of as :class:`Class`
67 objects.
Georg Brandl116aa622007-08-15 14:28:22 +000068
69
Christian Heimes81ee3ef2008-05-04 22:42:01 +000070.. attribute:: Class.methods
Georg Brandl116aa622007-08-15 14:28:22 +000071
72 A dictionary mapping method names to line numbers.
73
74
Christian Heimes81ee3ef2008-05-04 22:42:01 +000075.. attribute:: Class.file
Georg Brandl116aa622007-08-15 14:28:22 +000076
77 Name of the file containing the ``class`` statement defining the class.
78
79
Christian Heimes81ee3ef2008-05-04 22:42:01 +000080.. attribute:: Class.lineno
Georg Brandl116aa622007-08-15 14:28:22 +000081
82 The line number of the ``class`` statement within the file named by
Georg Brandl502d9a52009-07-26 15:02:41 +000083 :attr:`~Class.file`.
Georg Brandl116aa622007-08-15 14:28:22 +000084
85
86.. _pyclbr-function-objects:
87
Christian Heimes81ee3ef2008-05-04 22:42:01 +000088Function Objects
89----------------
Georg Brandl116aa622007-08-15 14:28:22 +000090
Christian Heimes81ee3ef2008-05-04 22:42:01 +000091The :class:`Function` objects used as values in the dictionary returned by
Senthil Kumarana6bac952011-07-04 11:28:30 -070092:func:`readmodule_ex` provide the following attributes:
Georg Brandl116aa622007-08-15 14:28:22 +000093
94
Christian Heimes81ee3ef2008-05-04 22:42:01 +000095.. attribute:: Function.module
Georg Brandl116aa622007-08-15 14:28:22 +000096
97 The name of the module defining the function described by the function
98 descriptor.
99
100
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000101.. attribute:: Function.name
Georg Brandl116aa622007-08-15 14:28:22 +0000102
103 The name of the function.
104
105
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000106.. attribute:: Function.file
Georg Brandl116aa622007-08-15 14:28:22 +0000107
108 Name of the file containing the ``def`` statement defining the function.
109
110
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000111.. attribute:: Function.lineno
Georg Brandl116aa622007-08-15 14:28:22 +0000112
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000113 The line number of the ``def`` statement within the file named by
Georg Brandl502d9a52009-07-26 15:02:41 +0000114 :attr:`~Function.file`.
Georg Brandl116aa622007-08-15 14:28:22 +0000115