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.
29 - urischemes.py: Contains a complete mapping of known URI addressing
30 scheme names to descriptions.
34 - languages: Language-specific mappings of terms.
36 - parsers: Syntax-specific input parser modules or packages.
38 - readers: Context-specific input handlers which understand the data
39 source and manage a parser.
41 - transforms: Modules used by readers and writers to modify DPS
44 - utils: Contains the ``Reporter`` system warning class and miscellaneous
45 utilities used by readers, writers, and transforms.
47 - writers: Format-specific output translators.
50 __docformat__
= 'reStructuredText'
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."""
59 __version_details__
= 'repository'
60 """Extra version details (e.g. 'snapshot 2005-05-29, r3410', 'repository',
61 'release'), modified automatically & manually."""
65 class ApplicationError(StandardError):
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
)
74 class DataError(ApplicationError
): pass
80 Runtime setting specification base class.
82 SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
86 """Runtime settings specification. Override in subclasses.
88 Defines runtime settings and associated command-line options, as used by
89 `docutils.frontend.OptionParser`. This is a tuple of:
91 - Option group title (string or `None` which implies no group, just a list
94 - Description (string or `None`).
96 - A sequence of option tuples. Each consists of:
100 - List of option strings (e.g. ``['-Q', '--quux']``).
102 - Dictionary of keyword arguments sent to the OptionParser/OptionGroup
103 ``add_option`` method.
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.
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.
118 See the optparse docs for more details.
120 - More triples of group title, description, options, as many times as
121 needed. Thus, `settings_spec` tuples can be simply concatenated.
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."""
129 settings_default_overrides
= None
130 """A dictionary of auxiliary defaults, to override defaults for settings
131 defined in other components. Override in subclasses."""
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
138 config_section
= None
139 """The name of the config file section specific to this component
140 (lowercase, no brackets). Override in subclasses."""
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."""
153 Runtime transform specification base class.
155 TransformSpec subclass objects used by `docutils.transforms.Transformer`.
158 def get_transforms(self
):
159 """Transforms required by this class. Override in subclasses."""
160 if self
.default_transforms
!= ():
162 warnings
.warn('default_transforms attribute deprecated.\n'
163 'Use get_transforms() method instead.',
165 return list(self
.default_transforms
)
168 # Deprecated; for compatibility.
169 default_transforms
= ()
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::
179 def reference_resolver(node):
180 '''Returns boolean: true if resolved, false if not.'''
182 If the function is able to resolve the reference, it should also remove
183 the 'refname' attribute and mark the node as resolved::
188 Each function must have a "priority" attribute which will affect the order
189 the unknown_reference_resolvers are run::
191 reference_resolver.priority = 100
193 Override in subclasses."""
196 class Component(SettingsSpec
, TransformSpec
):
198 """Base class for Docutils components."""
200 component_type
= None
201 """Name of the component type ('reader', 'parser', 'writer'). Override in
205 """Names for this component. Override in subclasses."""
207 def supports(self
, format
):
209 Is `format` supported by this component?
211 To be used by transforms to ask the dependent component if it supports
212 a certain input context or output format.
214 return format
in self
.supported