/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
 10The :mod:`pyclbr` module can be used to determine some limited information
 11about the classes, methods and top-level functions defined in a module.  The
 12information provided is sufficient to implement a traditional three-pane
 13class browser.  The information is extracted from the source code rather
 14than by importing the module, so this module is safe to use with untrusted
 15code.  This restriction makes it impossible to use this module with modules
 16not implemented in Python, including all standard and optional extension
 17modules.
 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
 41Class Objects
 42-------------
 43
 44The :class:`Class` objects used as values in the dictionary returned by
 45:func:`readmodule` and :func:`readmodule_ex` provide the following data
 46members:
 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
 86Function Objects
 87----------------
 88
 89The :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