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 

    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.

    18 

    19 

    20 .. function:: readmodule(module[, path=None])

    21 

    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.

    27 

    28 

    29 .. function:: readmodule_ex(module[, path=None])

    30 

    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.

    37 

    38 

    39 .. _pyclbr-class-objects:

    40 

    41 Class Objects

    42 -------------

    43 

    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:

    47 

    48 

    49 .. attribute:: Class.module

    50 

    51    The name of the module defining the class described by the class descriptor.

    52 

    53 

    54 .. attribute:: Class.name

    55 

    56    The name of the class.

    57 

    58 

    59 .. attribute:: Class.super

    60 

    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.

    66 

    67 

    68 .. attribute:: Class.methods

    69 

    70    A dictionary mapping method names to line numbers.

    71 

    72 

    73 .. attribute:: Class.file

    74 

    75    Name of the file containing the ``class`` statement defining the class.

    76 

    77 

    78 .. attribute:: Class.lineno

    79 

    80    The line number of the ``class`` statement within the file named by

    81    :attr:`file`.

    82 

    83 

    84 .. _pyclbr-function-objects:

    85 

    86 Function Objects

    87 ----------------

    88 

    89 The :class:`Function` objects used as values in the dictionary returned by

    90 :func:`readmodule_ex` provide the following data members:

    91 

    92 

    93 .. attribute:: Function.module

    94 

    95    The name of the module defining the function described by the function

    96    descriptor.

    97 

    98 

    99 .. attribute:: Function.name

   100 

   101    The name of the function.

   102 

   103 

   104 .. attribute:: Function.file

   105 

   106    Name of the file containing the ``def`` statement defining the function.

   107 

   108 

   109 .. attribute:: Function.lineno

   110 

   111    The line number of the ``def`` statement within the file named by

   112    :attr:`file`.

   113