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