Stav 23.06.2026
This commit is contained in:
@@ -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
|
||||
@@ -0,0 +1,50 @@
|
||||
# $Id: doctree.py 10136 2025-05-20 15:48:27Z milde $
|
||||
# Author: Martin Blais <blais@furius.ca>
|
||||
# Copyright: This module has been placed in the public domain.
|
||||
|
||||
"""Reader for existing document trees."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
__docformat__ = 'reStructuredText'
|
||||
|
||||
from docutils import readers, utils, transforms
|
||||
|
||||
|
||||
class Reader(readers.ReReader):
|
||||
|
||||
"""
|
||||
Adapt the Reader API for an existing document tree.
|
||||
|
||||
The existing document tree must be passed as the ``source`` parameter to
|
||||
the `docutils.core.Publisher` initializer, wrapped in a
|
||||
`docutils.io.DocTreeInput` object::
|
||||
|
||||
pub = docutils.core.Publisher(
|
||||
..., source=docutils.io.DocTreeInput(document), ...)
|
||||
|
||||
The original document settings are overridden; if you want to use the
|
||||
settings of the original document, pass ``settings=document.settings`` to
|
||||
the Publisher call above.
|
||||
"""
|
||||
|
||||
supported = ('doctree',)
|
||||
|
||||
config_section = 'doctree reader'
|
||||
config_section_dependencies = ('readers',)
|
||||
|
||||
def parse(self) -> None:
|
||||
"""
|
||||
No parsing to do; refurbish the document tree instead.
|
||||
Overrides the inherited method.
|
||||
"""
|
||||
self.document = self.input
|
||||
# Create fresh Transformer object, to be populated from Writer
|
||||
# component.
|
||||
self.document.transformer = transforms.Transformer(self.document)
|
||||
# Replace existing settings object with new one.
|
||||
self.document.settings = self.settings
|
||||
# Create fresh Reporter object because it is dependent on
|
||||
# (new) settings.
|
||||
self.document.reporter = utils.new_reporter(
|
||||
self.document.get('source', ''), self.document.settings)
|
||||
@@ -0,0 +1,55 @@
|
||||
# $Id: pep.py 10136 2025-05-20 15:48:27Z milde $
|
||||
# Author: David Goodger <goodger@python.org>
|
||||
# Copyright: This module has been placed in the public domain.
|
||||
|
||||
"""
|
||||
Python Enhancement Proposal (PEP) Reader.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
__docformat__ = 'reStructuredText'
|
||||
|
||||
from docutils.readers import standalone
|
||||
from docutils.transforms import peps, frontmatter
|
||||
from docutils.parsers import rst
|
||||
|
||||
|
||||
class Reader(standalone.Reader):
|
||||
|
||||
supported = ('pep',)
|
||||
"""Contexts this reader supports."""
|
||||
|
||||
settings_spec = (
|
||||
'PEP Reader Option Defaults',
|
||||
'The --pep-references and --rfc-references options (for the '
|
||||
'reStructuredText parser) are on by default.',
|
||||
())
|
||||
|
||||
config_section = 'pep reader'
|
||||
config_section_dependencies = ('readers', 'standalone reader')
|
||||
|
||||
def get_transforms(self):
|
||||
transforms = super().get_transforms()
|
||||
# We have PEP-specific frontmatter handling.
|
||||
transforms.remove(frontmatter.DocTitle)
|
||||
transforms.remove(frontmatter.SectionSubTitle)
|
||||
transforms.remove(frontmatter.DocInfo)
|
||||
transforms.extend([peps.Headers, peps.Contents, peps.TargetNotes])
|
||||
return transforms
|
||||
|
||||
settings_default_overrides = {'pep_references': True,
|
||||
'rfc_references': True}
|
||||
|
||||
inliner_class = rst.states.Inliner
|
||||
|
||||
def __init__(self, parser=None, parser_name=None) -> None:
|
||||
"""`parser` should be ``None``, `parser_name` is ignored.
|
||||
|
||||
The default parser is "rst" with PEP-specific settings
|
||||
(since Docutils 0.3). Since Docutils 0.22, `parser` is ignored,
|
||||
if it is a `str` instance.
|
||||
"""
|
||||
if parser is None or isinstance(parser, str):
|
||||
parser = rst.Parser(rfc2822=True, inliner=self.inliner_class())
|
||||
super().__init__(parser)
|
||||
@@ -0,0 +1,65 @@
|
||||
# $Id: standalone.py 9539 2024-02-17 10:36:51Z milde $
|
||||
# Author: David Goodger <goodger@python.org>
|
||||
# Copyright: This module has been placed in the public domain.
|
||||
|
||||
"""
|
||||
Standalone file Reader for the reStructuredText markup syntax.
|
||||
"""
|
||||
|
||||
__docformat__ = 'reStructuredText'
|
||||
|
||||
|
||||
from docutils import frontend, readers
|
||||
from docutils.transforms import frontmatter, references, misc
|
||||
|
||||
|
||||
class Reader(readers.Reader):
|
||||
|
||||
supported = ('standalone',)
|
||||
"""Contexts this reader supports."""
|
||||
|
||||
document = None
|
||||
"""A single document tree."""
|
||||
|
||||
settings_spec = (
|
||||
'Standalone Reader Options',
|
||||
None,
|
||||
(('Disable the promotion of a lone top-level section title to '
|
||||
'document title (and subsequent section title to document '
|
||||
'subtitle promotion; enabled by default).',
|
||||
['--no-doc-title'],
|
||||
{'dest': 'doctitle_xform', 'action': 'store_false',
|
||||
'default': True, 'validator': frontend.validate_boolean}),
|
||||
('Disable the bibliographic field list transform (enabled by '
|
||||
'default).',
|
||||
['--no-doc-info'],
|
||||
{'dest': 'docinfo_xform', 'action': 'store_false',
|
||||
'default': True, 'validator': frontend.validate_boolean}),
|
||||
('Activate the promotion of lone subsection titles to '
|
||||
'section subtitles (disabled by default).',
|
||||
['--section-subtitles'],
|
||||
{'dest': 'sectsubtitle_xform', 'action': 'store_true',
|
||||
'default': False, 'validator': frontend.validate_boolean}),
|
||||
('Deactivate the promotion of lone subsection titles.',
|
||||
['--no-section-subtitles'],
|
||||
{'dest': 'sectsubtitle_xform', 'action': 'store_false'}),
|
||||
))
|
||||
|
||||
config_section = 'standalone reader'
|
||||
config_section_dependencies = ('readers',)
|
||||
|
||||
def get_transforms(self):
|
||||
return super().get_transforms() + [
|
||||
references.Substitutions,
|
||||
references.PropagateTargets,
|
||||
frontmatter.DocTitle,
|
||||
frontmatter.SectionSubTitle,
|
||||
frontmatter.DocInfo,
|
||||
references.AnonymousHyperlinks,
|
||||
references.IndirectHyperlinks,
|
||||
references.Footnotes,
|
||||
references.ExternalTargets,
|
||||
references.InternalTargets,
|
||||
references.DanglingReferences,
|
||||
misc.Transitions,
|
||||
]
|
||||
Reference in New Issue
Block a user