docutils/readers/__init__.py

   1 # $Id$
   2 # Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 This package contains Docutils Reader modules.
   7 """
   8
   9 __docformat__ = 'reStructuredText'
  10
  11 import sys
  12
  13 from docutils import utils, parsers, Component
  14 from docutils.transforms import universal
  15 if sys.version_info < (2,5):
  16     from docutils._compat import __import__
  17
  18
  19 class Reader(Component):
  20
  21     """
  22     Abstract base class for docutils Readers.
  23
  24     Each reader module or package must export a subclass also called 'Reader'.
  25
  26     The two steps of a Reader's responsibility are `scan()` and
  27     `parse()`.  Call `read()` to process a document.
  28     """
  29
  30     component_type = 'reader'
  31     config_section = 'readers'
  32
  33     def get_transforms(self):
  34         return Component.get_transforms(self) + [
  35             universal.Decorations,
  36             universal.ExposeInternals,
  37             universal.StripComments,]
  38
  39     def __init__(self, parser=None, parser_name=None):
  40         """
  41         Initialize the Reader instance.
  42
  43         Several instance attributes are defined with dummy initial values.
  44         Subclasses may use these attributes as they wish.
  45         """
  46
  47         self.parser = parser
  48         """A `parsers.Parser` instance shared by all doctrees.  May be left
  49         unspecified if the document source determines the parser."""
  50
  51         if parser is None and parser_name:
  52             self.set_parser(parser_name)
  53
  54         self.source = None
  55         """`docutils.io` IO object, source of input data."""
  56
  57         self.input = None
  58         """Raw text input; either a single string or, for more complex cases,
  59         a collection of strings."""
  60
  61     def set_parser(self, parser_name):
  62         """Set `self.parser` by name."""
  63         parser_class = parsers.get_parser_class(parser_name)
  64         self.parser = parser_class()
  65
  66     def read(self, source, parser, settings):
  67         self.source = source
  68         if not self.parser:
  69             self.parser = parser
  70         self.settings = settings
  71         self.input = self.source.read()
  72         self.parse()
  73         return self.document
  74
  75     def parse(self):
  76         """Parse `self.input` into a document tree."""
  77         self.document = document = self.new_document()
  78         self.parser.parse(self.input, document)
  79         document.current_source = document.current_line = None
  80
  81     def new_document(self):
  82         """Create and return a new empty document tree (root node)."""
  83         document = utils.new_document(self.source.source_path, self.settings)
  84         return document
  85
  86
  87 class ReReader(Reader):
  88
  89     """
  90     A reader which rereads an existing document tree (e.g. a
  91     deserializer).
  92
  93     Often used in conjunction with `writers.UnfilteredWriter`.
  94     """
  95
  96     def get_transforms(self):
  97         # Do not add any transforms.  They have already been applied
  98         # by the reader which originally created the document.
  99         return Component.get_transforms(self)
 100
 101
 102 _reader_aliases = {}
 103
 104 def get_reader_class(reader_name):
 105     """Return the Reader class from the `reader_name` module."""
 106     reader_name = reader_name.lower()
 107     if reader_name in _reader_aliases:
 108         reader_name = _reader_aliases[reader_name]
 109     try:
 110         module = __import__(reader_name, globals(), locals(), level=0)
 111     except ImportError:
 112         module = __import__(reader_name, globals(), locals(), level=1)
 113     return module.Reader