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 import sys
  54
  55
  56 __docformat__ = 'reStructuredText'
  57
  58 __version__ = '0.14rc2'
  59 """Docutils version identifier (complies with PEP 440)::
  60
  61     major.minor[.micro][releaselevel[serial]][.dev]
  62
  63 * The major number will be bumped when the project is feature-complete, and
  64   later if there is a major change in the design or API.
  65 * The minor number is bumped whenever there are new features.
  66 * The micro number is bumped for bug-fix releases. Omitted if micro=0.
  67 * The releaselevel identifier is used for pre-releases, one of 'a' (alpha),
  68   'b' (beta), or 'rc' (release candidate). Omitted for final releases.
  69 * The serial release number identifies prereleases; omitted if 0.
  70 * The '.dev' suffix indicates active development, not a release, before the
  71   version indicated.
  72
  73 For version comparison operations, use `__version_info__`
  74 rather than parsing the text of `__version__`.
  75 """
  76
  77 # workaround for Python < 2.6:
  78 __version_info__ = (0, 14, 0, 'candidate', 2, True)
  79 # To add in Docutils 0.15, replacing the line above:
  80 """
  81 from collections import namedtuple
  82 VersionInfo = namedtuple(
  83     'VersionInfo', 'major minor micro releaselevel serial release')
  84 __version_info__ = VersionInfo(
  85     major=0,
  86     minor=15,
  87     micro=0,
  88     releaselevel='alpha', # development status:
  89                           # one of 'alpha', 'beta', 'candidate', 'final'
  90     serial=0,             # pre-release number (0 for final releases)
  91     release=False         # True for official releases and pre-releases
  92     )
  93
  94 Comprehensive version information tuple. Can be used to test for a
  95 minimally required version, e.g. ::
  96
  97   if __version_info__ >= (0, 13, 0, 'candidate', 2, True)
  98
  99 or in a self-documenting way like ::
 100
 101   if __version_info__ >= docutils.VersionInfo(
 102       major=0, minor=13, micro=0,
 103       releaselevel='candidate', serial=2, release=True)
 104 """
 105
 106 __version_details__ = ''
 107 """Optional extra version details (e.g. 'snapshot 2005-05-29, r3410').
 108 (For development and release status see `__version_info__`.)
 109 """
 110
 111
 112 class ApplicationError(StandardError):
 113     # Workaround:
 114     # In Python < 2.6, unicode(<exception instance>) calls `str` on the
 115     # arg and therefore, e.g., unicode(StandardError(u'\u234')) fails
 116     # with UnicodeDecodeError.
 117     if sys.version_info < (2,6):
 118         def __unicode__(self):
 119             return u', '.join(self.args)
 120
 121
 122 class DataError(ApplicationError): pass
 123
 124
 125 class SettingsSpec:
 126
 127     """
 128     Runtime setting specification base class.
 129
 130     SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
 131     """
 132
 133     settings_spec = ()
 134     """Runtime settings specification.  Override in subclasses.
 135
 136     Defines runtime settings and associated command-line options, as used by
 137     `docutils.frontend.OptionParser`.  This is a tuple of:
 138
 139     - Option group title (string or `None` which implies no group, just a list
 140       of single options).
 141
 142     - Description (string or `None`).
 143
 144     - A sequence of option tuples.  Each consists of:
 145
 146       - Help text (string)
 147
 148       - List of option strings (e.g. ``['-Q', '--quux']``).
 149
 150       - Dictionary of keyword arguments sent to the OptionParser/OptionGroup
 151         ``add_option`` method.
 152
 153         Runtime setting names are derived implicitly from long option names
 154         ('--a-setting' becomes ``settings.a_setting``) or explicitly from the
 155         'dest' keyword argument.
 156
 157         Most settings will also have a 'validator' keyword & function.  The
 158         validator function validates setting values (from configuration files
 159         and command-line option arguments) and converts them to appropriate
 160         types.  For example, the ``docutils.frontend.validate_boolean``
 161         function, **required by all boolean settings**, converts true values
 162         ('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off',
 163         'no', 'false', and '') to 0.  Validators need only be set once per
 164         setting.  See the `docutils.frontend.validate_*` functions.
 165
 166         See the optparse docs for more details.
 167
 168     - More triples of group title, description, options, as many times as
 169       needed.  Thus, `settings_spec` tuples can be simply concatenated.
 170     """
 171
 172     settings_defaults = None
 173     """A dictionary of defaults for settings not in `settings_spec` (internal
 174     settings, intended to be inaccessible by command-line and config file).
 175     Override in subclasses."""
 176
 177     settings_default_overrides = None
 178     """A dictionary of auxiliary defaults, to override defaults for settings
 179     defined in other components.  Override in subclasses."""
 180
 181     relative_path_settings = ()
 182     """Settings containing filesystem paths.  Override in subclasses.
 183     Settings listed here are to be interpreted relative to the current working
 184     directory."""
 185
 186     config_section = None
 187     """The name of the config file section specific to this component
 188     (lowercase, no brackets).  Override in subclasses."""
 189
 190     config_section_dependencies = None
 191     """A list of names of config file sections that are to be applied before
 192     `config_section`, in order (from general to specific).  In other words,
 193     the settings in `config_section` are to be overlaid on top of the settings
 194     from these sections.  The "general" section is assumed implicitly.
 195     Override in subclasses."""
 196
 197
 198 class TransformSpec:
 199
 200     """
 201     Runtime transform specification base class.
 202
 203     TransformSpec subclass objects used by `docutils.transforms.Transformer`.
 204     """
 205
 206     def get_transforms(self):
 207         """Transforms required by this class.  Override in subclasses."""
 208         if self.default_transforms != ():
 209             import warnings
 210             warnings.warn('default_transforms attribute deprecated.\n'
 211                           'Use get_transforms() method instead.',
 212                           DeprecationWarning)
 213             return list(self.default_transforms)
 214         return []
 215
 216     # Deprecated; for compatibility.
 217     default_transforms = ()
 218
 219     unknown_reference_resolvers = ()
 220     """List of functions to try to resolve unknown references.  Unknown
 221     references have a 'refname' attribute which doesn't correspond to any
 222     target in the document.  Called when the transforms in
 223     `docutils.tranforms.references` are unable to find a correct target.  The
 224     list should contain functions which will try to resolve unknown
 225     references, with the following signature::
 226
 227         def reference_resolver(node):
 228             '''Returns boolean: true if resolved, false if not.'''
 229
 230     If the function is able to resolve the reference, it should also remove
 231     the 'refname' attribute and mark the node as resolved::
 232
 233         del node['refname']
 234         node.resolved = 1
 235
 236     Each function must have a "priority" attribute which will affect the order
 237     the unknown_reference_resolvers are run::
 238
 239         reference_resolver.priority = 100
 240
 241     Override in subclasses."""
 242
 243
 244 class Component(SettingsSpec, TransformSpec):
 245
 246     """Base class for Docutils components."""
 247
 248     component_type = None
 249     """Name of the component type ('reader', 'parser', 'writer').  Override in
 250     subclasses."""
 251
 252     supported = ()
 253     """Names for this component.  Override in subclasses."""
 254
 255     def supports(self, format):
 256         """
 257         Is `format` supported by this component?
 258
 259         To be used by transforms to ask the dependent component if it supports
 260         a certain input context or output format.
 261         """
 262         return format in self.supported