Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/docutils/parsers/__init__.py: 78%

1# $Id: __init__.py 10306 2026-03-28 18:54:04Z milde $ 

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 

9from __future__ import annotations 

10 

11__docformat__ = 'reStructuredText' 

12 

13import importlib 

14 

15from docutils import Component, frontend, transforms 

16 

17TYPE_CHECKING = False 

18if TYPE_CHECKING: 

19 from typing import Final 

20 

21 from docutils import nodes 

22 from docutils.transforms import Transform 

23 

24 

25class Parser(Component): 

26 settings_spec = ( 

27 'Generic Parser Options', 

28 None, 

29 (('Disable directives that insert the contents of an external file; ' 

30 'replaced with a "warning" system message.', 

31 ['--no-file-insertion'], 

32 {'action': 'store_false', 'default': True, 

33 'dest': 'file_insertion_enabled', 

34 'validator': frontend.validate_boolean}), 

35 ('Enable directives that insert the contents ' 

36 'of an external file. (default)', 

37 ['--file-insertion-enabled'], 

38 {'action': 'store_true'}), 

39 ('Disable the "raw" directive; ' 

40 'replaced with a "warning" system message.', 

41 ['--no-raw'], 

42 {'action': 'store_false', 'default': True, 'dest': 'raw_enabled', 

43 'validator': frontend.validate_boolean}), 

44 ('Enable the "raw" directive. (default)', 

45 ['--raw-enabled'], 

46 {'action': 'store_true'}), 

47 ('Maximal number of characters in an input line. Default 10 000.', 

48 ['--line-length-limit'], 

49 {'metavar': '<length>', 'type': 'int', 'default': 10_000, 

50 'validator': frontend.validate_nonnegative_int}), 

51 ('Keep identifiers backwards compatible. Default.', 

52 ['--legacy-ids'], 

53 {'action': 'store_true', 

54 'validator': frontend.validate_boolean, 

55 'default': True}), 

56 ('Explicit targets use identifiers matching the reference name.', 

57 ['--matching-ids'], 

58 {'action': 'store_false', 

59 'dest': 'legacy_ids'}), 

60 ('Validate the document tree after parsing.', 

61 ['--validate'], 

62 {'action': 'store_true', 

63 'validator': frontend.validate_boolean}), 

64 ('Do not validate the document tree. (default)', 

65 ['--no-validation'], 

66 {'action': 'store_false', 'dest': 'validate'}), 

67 ) 

68 ) 

69 component_type: Final = 'parser' 

70 config_section: Final = 'parsers' 

71 

72 def get_transforms(self) -> list[type[Transform]]: 

73 return super().get_transforms() + [transforms.universal.Validate] 

74 

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') 

78 

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) 

88 

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) 

93 

94 

95PARSER_ALIASES = { # short names for known parsers 

96 'null': 'docutils.parsers.null', 

97 # reStructuredText 

98 'rst': 'docutils.parsers.rst', 

99 'restructuredtext': 'docutils.parsers.rst', 

100 'rest': 'docutils.parsers.rst', 

101 'restx': 'docutils.parsers.rst', 

102 'rtxt': 'docutils.parsers.rst', 

103 # Docutils XML 

104 'docutils_xml': 'docutils.parsers.docutils_xml', 

105 'xml': 'docutils.parsers.docutils_xml', 

106 # 3rd-party Markdown parsers 

107 'recommonmark': 'docutils.parsers.recommonmark_wrapper', 

108 'myst': 'myst_parser.docutils_', 

109 # 'pycmark': works out of the box 

110 # dispatcher for 3rd-party Markdown parsers 

111 'commonmark': 'docutils.parsers.commonmark_wrapper', 

112 'markdown': 'docutils.parsers.commonmark_wrapper', 

113 } 

114 

115 

116def get_parser_class(parser_name: str) -> type[Parser]: 

117 """Return the Parser class from the `parser_name` module.""" 

118 name = parser_name.lower() 

119 

120 try: 

121 module = importlib.import_module(PARSER_ALIASES.get(name, name)) 

122 except ImportError as err: 

123 raise ImportError(f'Parser "{parser_name}" not found. {err}') from err 

124 return module.Parser