Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`pyclbr` --- Python class browser support |
| 2 | ============================================== |
| 3 | |
| 4 | .. module:: pyclbr |
| 5 | :synopsis: Supports information extraction for a Python class browser. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 8 | |
Raymond Hettinger | a199368 | 2011-01-27 01:20:32 +0000 | [diff] [blame] | 9 | **Source code:** :source:`Lib/pyclbr.py` |
| 10 | |
| 11 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 13 | The :mod:`pyclbr` module can be used to determine some limited information |
| 14 | about the classes, methods and top-level functions defined in a module. The |
| 15 | information provided is sufficient to implement a traditional three-pane |
| 16 | class browser. The information is extracted from the source code rather |
| 17 | than by importing the module, so this module is safe to use with untrusted |
| 18 | code. This restriction makes it impossible to use this module with modules |
| 19 | not implemented in Python, including all standard and optional extension |
| 20 | modules. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
| 22 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 23 | .. function:: readmodule(module, path=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 25 | Read a module and return a dictionary mapping class names to class |
| 26 | descriptor objects. The parameter *module* should be the name of a |
| 27 | module as a string; it may be the name of a module within a package. The |
| 28 | *path* parameter should be a sequence, and is used to augment the value |
| 29 | of ``sys.path``, which is used to locate module source code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 32 | .. function:: readmodule_ex(module, path=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 34 | Like :func:`readmodule`, but the returned dictionary, in addition to |
| 35 | mapping class names to class descriptor objects, also maps top-level |
| 36 | function names to function descriptor objects. Moreover, if the module |
| 37 | being read is a package, the key ``'__path__'`` in the returned |
| 38 | dictionary has as its value a list which contains the package search |
| 39 | path. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | |
| 42 | .. _pyclbr-class-objects: |
| 43 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 44 | Class Objects |
| 45 | ------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 47 | The :class:`Class` objects used as values in the dictionary returned by |
| 48 | :func:`readmodule` and :func:`readmodule_ex` provide the following data |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 49 | attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
| 51 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 52 | .. attribute:: Class.module |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
| 54 | The name of the module defining the class described by the class descriptor. |
| 55 | |
| 56 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 57 | .. attribute:: Class.name |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
| 59 | The name of the class. |
| 60 | |
| 61 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 62 | .. attribute:: Class.super |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 64 | A list of :class:`Class` objects which describe the immediate base |
| 65 | classes of the class being described. Classes which are named as |
| 66 | superclasses but which are not discoverable by :func:`readmodule` are |
| 67 | listed as a string with the class name instead of as :class:`Class` |
| 68 | objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 71 | .. attribute:: Class.methods |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | A dictionary mapping method names to line numbers. |
| 74 | |
| 75 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 76 | .. attribute:: Class.file |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
| 78 | Name of the file containing the ``class`` statement defining the class. |
| 79 | |
| 80 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 81 | .. attribute:: Class.lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | |
| 83 | The line number of the ``class`` statement within the file named by |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 84 | :attr:`~Class.file`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | |
| 87 | .. _pyclbr-function-objects: |
| 88 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 89 | Function Objects |
| 90 | ---------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 92 | The :class:`Function` objects used as values in the dictionary returned by |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 93 | :func:`readmodule_ex` provide the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
| 95 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 96 | .. attribute:: Function.module |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | |
| 98 | The name of the module defining the function described by the function |
| 99 | descriptor. |
| 100 | |
| 101 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 102 | .. attribute:: Function.name |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
| 104 | The name of the function. |
| 105 | |
| 106 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 107 | .. attribute:: Function.file |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
| 109 | Name of the file containing the ``def`` statement defining the function. |
| 110 | |
| 111 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 112 | .. attribute:: Function.lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 114 | The line number of the ``def`` statement within the file named by |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 115 | :attr:`~Function.file`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |