1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
# $Id: __init__.py 10045 2025-03-09 01:02:23Z aa-turner $
# Author: David Goodger <goodger@python.org>
# Copyright: This module has been placed in the public domain.
"""
This package contains Docutils parser modules.
"""
from __future__ import annotations
__docformat__ = 'reStructuredText'
import importlib
from docutils import Component, frontend, transforms
TYPE_CHECKING = False
if TYPE_CHECKING:
from typing import Final
from docutils import nodes
from docutils.transforms import Transform
class Parser(Component):
settings_spec = (
'Generic Parser Options',
None,
(('Disable directives that insert the contents of an external file; '
'replaced with a "warning" system message.',
['--no-file-insertion'],
{'action': 'store_false', 'default': True,
'dest': 'file_insertion_enabled',
'validator': frontend.validate_boolean}),
('Enable directives that insert the contents '
'of an external file. (default)',
['--file-insertion-enabled'],
{'action': 'store_true'}),
('Disable the "raw" directive; '
'replaced with a "warning" system message.',
['--no-raw'],
{'action': 'store_false', 'default': True, 'dest': 'raw_enabled',
'validator': frontend.validate_boolean}),
('Enable the "raw" directive. (default)',
['--raw-enabled'],
{'action': 'store_true'}),
('Maximal number of characters in an input line. Default 10 000.',
['--line-length-limit'],
{'metavar': '<length>', 'type': 'int', 'default': 10_000,
'validator': frontend.validate_nonnegative_int}),
('Validate the document tree after parsing.',
['--validate'],
{'action': 'store_true',
'validator': frontend.validate_boolean}),
('Do not validate the document tree. (default)',
['--no-validation'],
{'action': 'store_false', 'dest': 'validate'}),
)
)
component_type: Final = 'parser'
config_section: Final = 'parsers'
def get_transforms(self) -> list[type[Transform]]:
return super().get_transforms() + [transforms.universal.Validate]
def parse(self, inputstring: str, document: nodes.document) -> None:
"""Override to parse `inputstring` into document tree `document`."""
raise NotImplementedError('subclass must override this method')
def setup_parse(self, inputstring: str, document: nodes.document) -> None:
"""Initial parse setup. Call at start of `self.parse()`."""
self.inputstring = inputstring
# provide fallbacks in case the document has only generic settings
document.settings.setdefault('file_insertion_enabled', False)
document.settings.setdefault('raw_enabled', False)
document.settings.setdefault('line_length_limit', 10_000)
self.document = document
document.reporter.attach_observer(document.note_parse_message)
def finish_parse(self) -> None:
"""Finalize parse details. Call at end of `self.parse()`."""
self.document.reporter.detach_observer(
self.document.note_parse_message)
PARSER_ALIASES = { # short names for known parsers
'null': 'docutils.parsers.null',
# reStructuredText
'rst': 'docutils.parsers.rst',
'restructuredtext': 'docutils.parsers.rst',
'rest': 'docutils.parsers.rst',
'restx': 'docutils.parsers.rst',
'rtxt': 'docutils.parsers.rst',
# Docutils XML
'docutils_xml': 'docutils.parsers.docutils_xml',
'xml': 'docutils.parsers.docutils_xml',
# 3rd-party Markdown parsers
'recommonmark': 'docutils.parsers.recommonmark_wrapper',
'myst': 'myst_parser.docutils_',
# 'pycmark': works out of the box
# dispatcher for 3rd-party Markdown parsers
'commonmark': 'docutils.parsers.commonmark_wrapper',
'markdown': 'docutils.parsers.commonmark_wrapper',
}
def get_parser_class(parser_name: str) -> type[Parser]:
"""Return the Parser class from the `parser_name` module."""
name = parser_name.lower()
try:
module = importlib.import_module(PARSER_ALIASES.get(name, name))
except ImportError as err:
raise ImportError(f'Parser "{parser_name}" not found. {err}') from err
return module.Parser
|
