135 lines
4.4 KiB
Python
135 lines
4.4 KiB
Python
# $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
|