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