docutils/writers/__init__.py

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