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