Stav 23.06.2026

2026-06-23 15:20:56 +02:00
commit 6d91e83e8c
5670 changed files with 1145969 additions and 0 deletions
@@ -0,0 +1,135 @@
+# $Id: __init__.py 10077 2025-04-09 08:55:54Z milde $
+# Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains Docutils Reader modules.
+"""
+
+from __future__ import annotations
+
+__docformat__ = 'reStructuredText'
+
+import importlib
+import warnings
+
+from docutils import utils, parsers, Component
+from docutils.transforms import universal
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Final
+
+    from docutils import nodes
+    from docutils.io import Input
+    from docutils.parsers import Parser
+    from docutils.transforms import Transform
+
+
+class Reader(Component):
+
+    """
+    Abstract base class for docutils Readers.
+
+    Each reader module or package must export a subclass also called 'Reader'.
+
+    The two steps of a Reader's responsibility are to read data from the
+    source Input object and parse the data with the Parser object.
+    Call `read()` to process a document.
+    """
+
+    component_type: Final = 'reader'
+    config_section: Final = 'readers'
+
+    def get_transforms(self) -> list[type[Transform]]:
+        return super().get_transforms() + [universal.Decorations,
+                                           universal.ExposeInternals,
+                                           universal.StripComments]
+
+    def __init__(self,
+                 parser: Parser | str | None = None,
+                 parser_name: str | None = None
+                 ) -> None:
+        """
+        Initialize the Reader instance.
+
+        :parser: A parser instance or name (an instance will be created).
+        :parser_name: deprecated, use "parser".
+
+        Several instance attributes are defined with dummy initial values.
+        Subclasses may use these attributes as they wish.
+        """
+
+        self.parser: Parser | None = parser
+        """A `parsers.Parser` instance shared by all doctrees.  May be left
+        unspecified if the document source determines the parser."""
+
+        if isinstance(parser, str):
+            self.set_parser(parser)
+        if parser_name is not None:
+            warnings.warn('Argument "parser_name" will be removed '
+                          'in Docutils 2.0.\n'
+                          '  Specify parser name in the "parser" argument.',
+                          PendingDeprecationWarning, stacklevel=2)
+            if self.parser is None:
+                self.set_parser(parser_name)
+
+        self.source: Input | None = None
+        """`docutils.io` IO object, source of input data."""
+
+        self.input: str | None = None
+        """Raw text input; either a single string or, for more complex cases,
+        a collection of strings."""
+
+    def set_parser(self, parser_name: str) -> None:
+        """Set `self.parser` by name."""
+        parser_class = parsers.get_parser_class(parser_name)
+        self.parser = parser_class()
+
+    def read(self, source, parser, settings):
+        self.source = source
+        if not self.parser:
+            self.parser = parser
+        self.settings = settings
+        self.input = self.source.read()
+        self.parse()
+        return self.document
+
+    def parse(self) -> None:
+        """Parse `self.input` into a document tree."""
+        document = self.new_document()
+        self.parser.parse(self.input, document)
+        document.current_source = document.current_line = None
+        self.document: nodes.document = document
+
+    def new_document(self) -> nodes.document:
+        """Create and return a new empty document tree (root node)."""
+        return utils.new_document(self.source.source_path, self.settings)
+
+
+class ReReader(Reader):
+
+    """
+    A reader which rereads an existing document tree (e.g. a
+    deserializer).
+
+    Often used in conjunction with `writers.UnfilteredWriter`.
+    """
+
+    def get_transforms(self) -> list[type[Transform]]:
+        # Do not add any transforms.  They have already been applied
+        # by the reader which originally created the document.
+        return Component.get_transforms(self)
+
+
+def get_reader_class(reader_name: str) -> type[Reader]:
+    """Return the Reader class from the `reader_name` module."""
+    name = reader_name.lower()
+    try:
+        module = importlib.import_module('docutils.readers.'+name)
+    except ImportError:
+        try:
+            module = importlib.import_module(name)
+        except ImportError as err:
+            raise ImportError(f'Reader "{reader_name}" not found.') from err
+    return module.Reader