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