Doc/library/pyclbr.rst

   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` can be used to determine some limited information about the
  11 classes, methods and top-level functions defined in a module.  The information
  12 provided is sufficient to implement a traditional three-pane class browser.  The
  13 information is extracted from the source code rather than by importing the
  14 module, so this module is safe to use with untrusted source code.  This
  15 restriction makes it impossible to use this module with modules not implemented
  16 in Python, including many standard and optional extension modules.
  17
  18
  19 .. function:: readmodule(module[, path])
  20
  21    Read a module and return a dictionary mapping class names to class descriptor
  22    objects.  The parameter *module* should be the name of a module as a string;
  23    it may be the name of a module within a package.  The *path* parameter should
  24    be a sequence, and is used to augment the value of ``sys.path``, which is
  25    used to locate module source code.
  26
  27    .. The 'inpackage' parameter appears to be for internal use only....
  28
  29
  30 .. function:: readmodule_ex(module[, path])
  31
  32    Like :func:`readmodule`, but the returned dictionary, in addition to mapping
  33    class names to class descriptor objects, also maps top-level function names to
  34    function descriptor objects.  Moreover, if the module being read is a package,
  35    the key ``'__path__'`` in the returned dictionary has as its value a list which
  36    contains the package search path.
  37
  38    .. The 'inpackage' parameter appears to be for internal use only....
  39
  40
  41 .. _pyclbr-class-objects:
  42
  43 Class Descriptor Objects
  44 ------------------------
  45
  46 The class descriptor objects used as values in the dictionary returned by
  47 :func:`readmodule` and :func:`readmodule_ex` provide the following data members:
  48
  49
  50 .. attribute:: class_descriptor.module
  51
  52    The name of the module defining the class described by the class descriptor.
  53
  54
  55 .. attribute:: class_descriptor.name
  56
  57    The name of the class.
  58
  59
  60 .. attribute:: class_descriptor.super
  61
  62    A list of class descriptors which describe the immediate base classes of the
  63    class being described.  Classes which are named as superclasses but which are
  64    not discoverable by :func:`readmodule` are listed as a string with the class
  65    name instead of class descriptors.
  66
  67
  68 .. attribute:: class_descriptor.methods
  69
  70    A dictionary mapping method names to line numbers.
  71
  72
  73 .. attribute:: class_descriptor.file
  74
  75    Name of the file containing the ``class`` statement defining the class.
  76
  77
  78 .. attribute:: class_descriptor.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 Descriptor Objects
  87 ---------------------------
  88
  89 The function descriptor objects used as values in the dictionary returned by
  90 :func:`readmodule_ex` provide the following data members:
  91
  92
  93 .. attribute:: function_descriptor.module
  94
  95    The name of the module defining the function described by the function
  96    descriptor.
  97
  98
  99 .. attribute:: function_descriptor.name
 100
 101    The name of the function.
 102
 103
 104 .. attribute:: function_descriptor.file
 105
 106    Name of the file containing the ``def`` statement defining the function.
 107
 108
 109 .. attribute:: function_descriptor.lineno
 110
 111    The line number of the ``def`` statement within the file named by :attr:`file`.
 112