2 # Author: David Goodger <goodger@python.org>
3 # Copyright: This module has been placed in the public domain.
6 This is the Docutils (Python Documentation Utilities) package.
13 - __init__.py: Contains component base classes, exception classes, and
14 Docutils version information.
16 - core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience
19 - frontend.py: Runtime settings (command-line interface, configuration files)
20 processing, for Docutils front-ends.
22 - io.py: Provides a uniform API for low-level input and output.
24 - nodes.py: Docutils document tree (doctree) node class library.
26 - statemachine.py: A finite state machine specialized for
27 regular-expression-based text filters.
31 - languages: Language-specific mappings of terms.
33 - parsers: Syntax-specific input parser modules or packages.
35 - readers: Context-specific input handlers which understand the data
36 source and manage a parser.
38 - transforms: Modules used by readers and writers to modify DPS
41 - utils: Contains the ``Reporter`` system warning class and miscellaneous
42 utilities used by readers, writers, and transforms.
44 utils/urischemes.py: Contains a complete mapping of known URI addressing
45 scheme names to descriptions.
47 - utils/math: Contains functions for conversion of mathematical notation
48 between different formats (LaTeX, MathML, text, ...).
50 - writers: Format-specific output translators.
54 from collections
import namedtuple
57 __docformat__
= 'reStructuredText'
59 __version__
= '0.18.1'
60 """Docutils version identifier (complies with PEP 440)::
62 major.minor[.micro][releaselevel[serial]][.dev]
64 For version comparison operations, use `__version_info__` (see, below)
65 rather than parsing the text of `__version__`.
67 See 'Version Numbering' in docs/dev/policies.txt.
70 # from functools import total_ordering
72 class VersionInfo(namedtuple('VersionInfo',
73 'major minor micro releaselevel serial release')):
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.'
81 if releaselevel
== 'final':
83 raise ValueError('releaselevel "final" must not be used '
84 'with development versions (leads to wrong '
85 'version ordering of the related __version__')
87 raise ValueError('"serial" must be 0 for final releases')
89 return super(VersionInfo
, cls
).__new
__(cls
, major
, minor
, micro
,
90 releaselevel
, serial
, release
)
92 def __lt__(self
, other
):
93 if isinstance(other
, tuple):
94 other
= VersionInfo(*other
)
95 return tuple.__lt
__(self
, other
)
97 def __gt__(self
, other
):
98 if isinstance(other
, tuple):
99 other
= VersionInfo(*other
)
100 return tuple.__gt
__(self
, other
)
102 def __le__(self
, other
):
103 if isinstance(other
, tuple):
104 other
= VersionInfo(*other
)
105 return tuple.__le
__(self
, other
)
107 def __ge__(self
, other
):
108 if isinstance(other
, tuple):
109 other
= VersionInfo(*other
)
110 return tuple.__ge
__(self
, other
)
112 __version_info__
= VersionInfo(
116 releaselevel
='final', # one of 'alpha', 'beta', 'candidate', 'final'
117 # pre-release serial number (0 for final releases and active development):
119 release
=True # True for official releases and pre-releases
121 """Comprehensive version information tuple. See 'Version Numbering' in
122 docs/dev/policies.txt."""
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__`.)
130 class ApplicationError(Exception): pass
132 class DataError(ApplicationError
): pass
135 class SettingsSpec(object):
138 Runtime setting specification base class.
140 SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
144 """Runtime settings specification. Override in subclasses.
146 Defines runtime settings and associated command-line options, as used by
147 `docutils.frontend.OptionParser`. This is a tuple of:
149 - Option group title (string or `None` which implies no group, just a list
152 - Description (string or `None`).
154 - A sequence of option tuples. Each consists of:
158 - List of option strings (e.g. ``['-Q', '--quux']``).
160 - Dictionary of keyword arguments sent to the OptionParser/OptionGroup
161 ``add_option`` method.
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.
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.
176 See the optparse docs for more details.
178 - More triples of group title, description, options, as many times as
179 needed. Thus, `settings_spec` tuples can be simply concatenated.
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."""
187 settings_default_overrides
= None
188 """A dictionary of auxiliary defaults, to override defaults for settings
189 defined in other components. Override in subclasses."""
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
196 config_section
= None
197 """The name of the config file section specific to this component
198 (lowercase, no brackets). Override in subclasses."""
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."""
211 Runtime transform specification base class.
213 TransformSpec subclass objects used by `docutils.transforms.Transformer`.
216 def get_transforms(self
):
217 """Transforms required by this class. Override in subclasses."""
218 if self
.default_transforms
!= ():
220 warnings
.warn('TransformSpec: the "default_transforms" attribute '
221 'will be removed in Docutils 1.1.\n'
222 'Use get_transforms() method instead.',
224 return list(self
.default_transforms
)
227 # Deprecated; for compatibility.
228 default_transforms
= ()
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::
238 def reference_resolver(node):
239 '''Returns boolean: true if resolved, false if not.'''
241 If the function is able to resolve the reference, it should also remove
242 the 'refname' attribute and mark the node as resolved::
247 Each function must have a "priority" attribute which will affect the order
248 the unknown_reference_resolvers are run::
250 reference_resolver.priority = 100
252 Override in subclasses."""
255 class Component(SettingsSpec
, TransformSpec
):
257 """Base class for Docutils components."""
259 component_type
= None
260 """Name of the component type ('reader', 'parser', 'writer'). Override in
264 """Names for this component. Override in subclasses."""
266 def supports(self
, format
):
268 Is `format` supported by this component?
270 To be used by transforms to ask the dependent component if it supports
271 a certain input context or output format.
273 return format
in self
.supported