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