Home | History | Annotate | Download | only in library 
      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 (a] acm.org>
      8 
      9 **Source code:** :source:`Lib/pyclbr.py`
     10 
     11 --------------
     12 
     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
     20 modules.
     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 
     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.
     52 
     53 
     54 .. _pyclbr-function-objects:
     55 
     56 Function Objects
     57 ----------------
     58 Class :class:`Function` instances describe functions defined by def
     59 statements.  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 
     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.
    154