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 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 13 | The :mod:`pyclbr` module provides limited information about the |
| 14 | functions, classes, and methods defined in a python-coded module. The |
| 15 | information is sufficient to implement a module browser. The |
| 16 | information is extracted from the python source code rather than by |
| 17 | importing the module, so this module is safe to use with untrusted code. |
| 18 | This restriction makes it impossible to use this module with modules not |
| 19 | implemented in Python, including all standard and optional extension |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 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 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
| 32 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 33 | .. function:: readmodule_ex(module, path=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 45 | .. versionadded:: 3.7 |
| 46 | Descriptors for nested definitions. They are accessed through the |
| 47 | new children attibute. Each has a new parent attribute. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 49 | The descriptors returned by these functions are instances of |
| 50 | Function and Class classes. Users are not expected to create instances |
| 51 | of these classes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | |
| 54 | .. _pyclbr-function-objects: |
| 55 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 56 | Function Objects |
| 57 | ---------------- |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 58 | Class :class:`Function` instances describe functions defined by def |
| 59 | statements. They have the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 61 | |
| 62 | .. attribute:: Function.file |
| 63 | |
| 64 | Name of the file in which the function is defined. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
| 66 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 67 | .. attribute:: Function.module |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 69 | The name of the module defining the function described. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
| 71 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 72 | .. attribute:: Function.name |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | The name of the function. |
| 75 | |
| 76 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 77 | .. attribute:: Function.lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 79 | The line number in the file where the definition starts. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
csabella | 246ff3b | 2017-07-03 21:31:25 -0400 | [diff] [blame] | 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 | |
| 99 | Class Objects |
| 100 | ------------- |
| 101 | Class :class:`Class` instances describe classes defined by class |
| 102 | statements. 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. |