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