1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
# $Id$
# Author: David Goodger <goodger@python.org>
# Copyright: This module has been placed in the public domain.
"""
This package contains Docutils Writer modules.
"""
__docformat__ = 'reStructuredText'
from importlib import import_module
import docutils
from docutils import languages, Component
from docutils.transforms import universal
class Writer(Component):
"""
Abstract base class for docutils Writers.
Each writer module or package must export a subclass also called 'Writer'.
Each writer must support all standard node types listed in
`docutils.nodes.node_class_names`.
The `write()` method is the main entry point.
"""
component_type = 'writer'
config_section = 'writers'
def get_transforms(self):
return super().get_transforms() + [universal.Messages,
universal.FilterMessages,
universal.StripClassesAndElements]
document = None
"""The document to write (Docutils doctree); set by `write()`."""
output = None
"""Final translated form of `document`
(`str` for text, `bytes` for binary formats); set by `translate()`.
"""
language = None
"""Language module for the document; set by `write()`."""
destination = None
"""`docutils.io` Output object; where to write the document.
Set by `write()`.
"""
def __init__(self):
# Used by HTML and LaTeX writer for output fragments:
self.parts = {}
"""Mapping of document part names to fragments of `self.output`.
Values are Unicode strings; encoding is up to the client. The 'whole'
key should contain the entire document output.
"""
def write(self, document, destination):
"""
Process a document into its final form.
Translate `document` (a Docutils document tree) into the Writer's
native format, and write it out to its `destination` (a
`docutils.io.Output` subclass object).
Normally not overridden or extended in subclasses.
"""
self.document = document
self.language = languages.get_language(
document.settings.language_code,
document.reporter)
self.destination = destination
self.translate()
return self.destination.write(self.output)
def translate(self):
"""
Do final translation of `self.document` into `self.output`. Called
from `write`. Override in subclasses.
Usually done with a `docutils.nodes.NodeVisitor` subclass, in
combination with a call to `docutils.nodes.Node.walk()` or
`docutils.nodes.Node.walkabout()`. The ``NodeVisitor`` subclass must
support all standard elements (listed in
`docutils.nodes.node_class_names`) and possibly non-standard elements
used by the current Reader as well.
"""
raise NotImplementedError('subclass must override this method')
def assemble_parts(self):
"""Assemble the `self.parts` dictionary. Extend in subclasses."""
self.parts['whole'] = self.output
self.parts['encoding'] = self.document.settings.output_encoding
self.parts['version'] = docutils.__version__
class UnfilteredWriter(Writer):
"""
A writer that passes the document tree on unchanged (e.g. a
serializer.)
Documents written by UnfilteredWriters are typically reused at a
later date using a subclass of `readers.ReReader`.
"""
def get_transforms(self):
# Do not add any transforms. When the document is reused
# later, the then-used writer will add the appropriate
# transforms.
return Component.get_transforms(self)
_writer_aliases = {
'html': 'html4css1', # may change to html5 some day
'html4': 'html4css1',
'xhtml10': 'html4css1',
'html5': 'html5_polyglot',
'xhtml': 'html5_polyglot',
's5': 's5_html',
'latex': 'latex2e',
'xelatex': 'xetex',
'luatex': 'xetex',
'lualatex': 'xetex',
'odf': 'odf_odt',
'odt': 'odf_odt',
'ooffice': 'odf_odt',
'openoffice': 'odf_odt',
'libreoffice': 'odf_odt',
'pprint': 'pseudoxml',
'pformat': 'pseudoxml',
'pdf': 'rlpdf',
'xml': 'docutils_xml'}
def get_writer_class(writer_name):
"""Return the Writer class from the `writer_name` module."""
name = writer_name.lower()
name = _writer_aliases.get(name, name)
try:
module = import_module('docutils.writers.'+name)
except ImportError:
try:
module = import_module(name)
except ImportError as err:
raise ImportError(f'Writer "{writer_name}" not found. {err}')
return module.Writer
|
