2 # Author: David Goodger <goodger@python.org>
3 # Copyright: This module has been placed in the public domain.
6 This package contains Docutils parser modules.
9 from __future__
import annotations
11 __docformat__
= 'reStructuredText'
14 from typing
import TYPE_CHECKING
, overload
16 from docutils
import Component
, frontend
, transforms
19 from typing
import Final
, Literal
21 from docutils
import nodes
22 from docutils
.parsers
import (
29 from docutils
.transforms
import Transform
31 from myst_parser
import docutils_
as myst_wrapper
34 class Parser(Component
):
36 'Generic Parser Options',
38 (('Disable directives that insert the contents of an external file; '
39 'replaced with a "warning" system message.',
40 ['--no-file-insertion'],
41 {'action': 'store_false', 'default': True,
42 'dest': 'file_insertion_enabled',
43 'validator': frontend
.validate_boolean
}),
44 ('Enable directives that insert the contents '
45 'of an external file. (default)',
46 ['--file-insertion-enabled'],
47 {'action': 'store_true'}),
48 ('Disable the "raw" directive; '
49 'replaced with a "warning" system message.',
51 {'action': 'store_false', 'default': True, 'dest': 'raw_enabled',
52 'validator': frontend
.validate_boolean
}),
53 ('Enable the "raw" directive. (default)',
55 {'action': 'store_true'}),
56 ('Maximal number of characters in an input line. Default 10 000.',
57 ['--line-length-limit'],
58 {'metavar': '<length>', 'type': 'int', 'default': 10_000,
59 'validator': frontend
.validate_nonnegative_int
}),
60 ('Validate the document tree after parsing.',
62 {'action': 'store_true',
63 'validator': frontend
.validate_boolean
}),
64 ('Do not validate the document tree. (default)',
66 {'action': 'store_false', 'dest': 'validate'}),
69 component_type
: Final
= 'parser'
70 config_section
: Final
= 'parsers'
72 def get_transforms(self
) -> list[type[Transform
]]:
73 return super().get_transforms() + [transforms
.universal
.Validate
]
75 def parse(self
, inputstring
: str, document
: nodes
.document
) -> None:
76 """Override to parse `inputstring` into document tree `document`."""
77 raise NotImplementedError('subclass must override this method')
79 def setup_parse(self
, inputstring
: str, document
: nodes
.document
) -> None:
80 """Initial parse setup. Call at start of `self.parse()`."""
81 self
.inputstring
= inputstring
82 # provide fallbacks in case the document has only generic settings
83 document
.settings
.setdefault('file_insertion_enabled', False)
84 document
.settings
.setdefault('raw_enabled', False)
85 document
.settings
.setdefault('line_length_limit', 10_000)
86 self
.document
= document
87 document
.reporter
.attach_observer(document
.note_parse_message
)
89 def finish_parse(self
) -> None:
90 """Finalize parse details. Call at end of `self.parse()`."""
91 self
.document
.reporter
.detach_observer(
92 self
.document
.note_parse_message
)
96 def get_parser_class(parser_name
: Literal
['null']) -> type[null
.Parser
]:
101 def get_parser_class(
102 parser_name
: Literal
['rst', 'restructuredtext']
103 ) -> type[rst
.Parser
]:
108 def get_parser_class(
109 parser_name
: Literal
['xml', 'docutils_xml']
110 ) -> type[docutils_xml
.Parser
]:
115 def get_parser_class(
116 parser_name
: Literal
['recommonmark']
117 ) -> type[recommonmark_wrapper
.Parser
]:
122 def get_parser_class(
123 parser_name
: Literal
['myst']
124 ) -> type[myst_wrapper
.Parser
]:
129 def get_parser_class(
130 parser_name
: Literal
['commonmark', 'markdown']
131 ) -> type[commonmark_wrapper
.Parser
]:
136 def get_parser_class(parser_name
: str) -> type[Parser
]:
140 def get_parser_class(parser_name
: str) -> type[Parser
]:
141 """Return the Parser class from the `parser_name` module."""
142 name
= parser_name
.lower()
144 # short names for known parsers
146 from docutils
.parsers
import null
148 if name
in {'rst', 'restructuredtext', 'rest', 'restx', 'rtxt'}:
149 from docutils
.parsers
import rst
151 if name
in {'docutils_xml', 'xml'}:
152 from docutils
.parsers
import docutils_xml
153 return docutils_xml
.Parser
156 # 3rd-party Markdown parsers
157 # (pycmark works out of the box)
158 if name
== 'recommonmark':
159 from docutils
.parsers
import recommonmark_wrapper
160 return recommonmark_wrapper
.Parser
162 from myst_parser
import docutils_
as myst_wrapper
163 return myst_wrapper
.Parser
165 # dispatcher for 3rd-party Markdown parsers
166 if name
in {'commonmark', 'markdown'}:
167 from docutils
.parsers
import commonmark_wrapper
168 return commonmark_wrapper
.Parser
170 # fallback to importing a fully-qualified name
171 module
= importlib
.import_module(name
)
172 except ImportError as err
:
173 raise ImportError(f
'Parser "{parser_name}" not found. {err}')