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