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