docutils/__init__.py

   1 # $Id$
   2 # Author: David Goodger <goodger@python.org>
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 This is the Docutils (Python Documentation Utilities) package.
   7
   8 Package Structure
   9 =================
  10
  11 Modules:
  12
  13 - __init__.py: Contains component base classes, exception classes, and
  14   Docutils version information.
  15
  16 - core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience
  17   functions.
  18
  19 - frontend.py: Runtime settings (command-line interface, configuration files)
  20   processing, for Docutils front-ends.
  21
  22 - io.py: Provides a uniform API for low-level input and output.
  23
  24 - nodes.py: Docutils document tree (doctree) node class library.
  25
  26 - statemachine.py: A finite state machine specialized for
  27   regular-expression-based text filters.
  28
  29 - urischemes.py: Contains a complete mapping of known URI addressing
  30   scheme names to descriptions.
  31
  32 - utils.py: Contains the ``Reporter`` system warning class and miscellaneous
  33   utilities.
  34
  35 Subpackages:
  36
  37 - languages: Language-specific mappings of terms.
  38
  39 - parsers: Syntax-specific input parser modules or packages.
  40
  41 - readers: Context-specific input handlers which understand the data
  42   source and manage a parser.
  43
  44 - transforms: Modules used by readers and writers to modify DPS
  45   doctrees.
  46
  47 - writers: Format-specific output translators.
  48 """
  49
  50 __docformat__ = 'reStructuredText'
  51
  52 __version__ = '0.7'
  53 """``major.minor.micro`` version number.  The micro number is bumped for API
  54 changes, for new functionality, and for interim project releases.  The minor
  55 number is bumped whenever there is a significant project release.  The major
  56 number will be bumped when the project is feature-complete, and perhaps if
  57 there is a major change in the design."""
  58
  59 __version_details__ = 'repository'
  60 """Extra version details (e.g. 'snapshot 2005-05-29, r3410', 'repository',
  61 'release'), modified automatically & manually."""
  62
  63 class ApplicationError(StandardError): pass
  64 class DataError(ApplicationError): pass
  65
  66
  67 class SettingsSpec:
  68
  69     """
  70     Runtime setting specification base class.
  71
  72     SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
  73     """
  74
  75     settings_spec = ()
  76     """Runtime settings specification.  Override in subclasses.
  77
  78     Defines runtime settings and associated command-line options, as used by
  79     `docutils.frontend.OptionParser`.  This is a tuple of:
  80
  81     - Option group title (string or `None` which implies no group, just a list
  82       of single options).
  83
  84     - Description (string or `None`).
  85
  86     - A sequence of option tuples.  Each consists of:
  87
  88       - Help text (string)
  89
  90       - List of option strings (e.g. ``['-Q', '--quux']``).
  91
  92       - Dictionary of keyword arguments sent to the OptionParser/OptionGroup
  93         ``add_option`` method.
  94
  95         Runtime setting names are derived implicitly from long option names
  96         ('--a-setting' becomes ``settings.a_setting``) or explicitly from the
  97         'dest' keyword argument.
  98
  99         Most settings will also have a 'validator' keyword & function.  The
 100         validator function validates setting values (from configuration files
 101         and command-line option arguments) and converts them to appropriate
 102         types.  For example, the ``docutils.frontend.validate_boolean``
 103         function, **required by all boolean settings**, converts true values
 104         ('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off',
 105         'no', 'false', and '') to 0.  Validators need only be set once per
 106         setting.  See the `docutils.frontend.validate_*` functions.
 107
 108         See the optparse docs for more details.
 109
 110     - More triples of group title, description, options, as many times as
 111       needed.  Thus, `settings_spec` tuples can be simply concatenated.
 112     """
 113
 114     settings_defaults = None
 115     """A dictionary of defaults for settings not in `settings_spec` (internal
 116     settings, intended to be inaccessible by command-line and config file).
 117     Override in subclasses."""
 118
 119     settings_default_overrides = None
 120     """A dictionary of auxiliary defaults, to override defaults for settings
 121     defined in other components.  Override in subclasses."""
 122
 123     relative_path_settings = ()
 124     """Settings containing filesystem paths.  Override in subclasses.
 125     Settings listed here are to be interpreted relative to the current working
 126     directory."""
 127
 128     config_section = None
 129     """The name of the config file section specific to this component
 130     (lowercase, no brackets).  Override in subclasses."""
 131
 132     config_section_dependencies = None
 133     """A list of names of config file sections that are to be applied before
 134     `config_section`, in order (from general to specific).  In other words,
 135     the settings in `config_section` are to be overlaid on top of the settings
 136     from these sections.  The "general" section is assumed implicitly.
 137     Override in subclasses."""
 138
 139
 140 class TransformSpec:
 141
 142     """
 143     Runtime transform specification base class.
 144
 145     TransformSpec subclass objects used by `docutils.transforms.Transformer`.
 146     """
 147
 148     def get_transforms(self):
 149         """Transforms required by this class.  Override in subclasses."""
 150         if self.default_transforms != ():
 151             import warnings
 152             warnings.warn('default_transforms attribute deprecated.\n'
 153                           'Use get_transforms() method instead.',
 154                           DeprecationWarning)
 155             return list(self.default_transforms)
 156         return []
 157
 158     # Deprecated; for compatibility.
 159     default_transforms = ()
 160
 161     unknown_reference_resolvers = ()
 162     """List of functions to try to resolve unknown references.  Unknown
 163     references have a 'refname' attribute which doesn't correspond to any
 164     target in the document.  Called when the transforms in
 165     `docutils.tranforms.references` are unable to find a correct target.  The
 166     list should contain functions which will try to resolve unknown
 167     references, with the following signature::
 168
 169         def reference_resolver(node):
 170             '''Returns boolean: true if resolved, false if not.'''
 171
 172     If the function is able to resolve the reference, it should also remove
 173     the 'refname' attribute and mark the node as resolved::
 174
 175         del node['refname']
 176         node.resolved = 1
 177
 178     Each function must have a "priority" attribute which will affect the order
 179     the unknown_reference_resolvers are run::
 180
 181         reference_resolver.priority = 100
 182
 183     Override in subclasses."""
 184
 185
 186 class Component(SettingsSpec, TransformSpec):
 187
 188     """Base class for Docutils components."""
 189
 190     component_type = None
 191     """Name of the component type ('reader', 'parser', 'writer').  Override in
 192     subclasses."""
 193
 194     supported = ()
 195     """Names for this component.  Override in subclasses."""
 196
 197     def supports(self, format):
 198         """
 199         Is `format` supported by this component?
 200
 201         To be used by transforms to ask the dependent component if it supports
 202         a certain input context or output format.
 203         """
 204         return format in self.supported