docutils/docutils/parsers/__init__.py

   1 # $Id$
   2 # Author: David Goodger <goodger@python.org>
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 This package contains Docutils parser modules.
   7 """
   8
   9 from __future__ import annotations
  10
  11 __docformat__ = 'reStructuredText'
  12
  13 import importlib
  14 from typing import TYPE_CHECKING, overload
  15
  16 from docutils import Component, frontend, transforms
  17
  18 if TYPE_CHECKING:
  19     from typing import Final, Literal
  20
  21     from docutils import nodes
  22     from docutils.parsers import (
  23         commonmark_wrapper,
  24         docutils_xml,
  25         null,
  26         rst,
  27         recommonmark_wrapper,
  28     )
  29     from docutils.transforms import Transform
  30
  31     from myst_parser import docutils_ as myst_wrapper
  32
  33
  34 class Parser(Component):
  35     settings_spec = (
  36         'Generic Parser Options',
  37         None,
  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.',
  50           ['--no-raw'],
  51           {'action': 'store_false', 'default': True, 'dest': 'raw_enabled',
  52            'validator': frontend.validate_boolean}),
  53          ('Enable the "raw" directive. (default)',
  54           ['--raw-enabled'],
  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.',
  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
  95 @overload
  96 def get_parser_class(parser_name: Literal['null']) -> type[null.Parser]:
  97     ...
  98
  99
 100 @overload
 101 def get_parser_class(
 102     parser_name: Literal['rst', 'restructuredtext']
 103 ) -> type[rst.Parser]:
 104     ...
 105
 106
 107 @overload
 108 def get_parser_class(
 109     parser_name: Literal['xml', 'docutils_xml']
 110 ) -> type[docutils_xml.Parser]:
 111     ...
 112
 113
 114 @overload
 115 def get_parser_class(
 116     parser_name: Literal['recommonmark']
 117 ) -> type[recommonmark_wrapper.Parser]:
 118     ...
 119
 120
 121 @overload
 122 def get_parser_class(
 123     parser_name: Literal['myst']
 124 ) -> type[myst_wrapper.Parser]:
 125     ...
 126
 127
 128 @overload
 129 def get_parser_class(
 130     parser_name: Literal['commonmark', 'markdown']
 131 ) -> type[commonmark_wrapper.Parser]:
 132     ...
 133
 134
 135 @overload
 136 def get_parser_class(parser_name: str) -> type[Parser]:
 137     ...
 138
 139
 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()
 143
 144     # short names for known parsers
 145     if name == 'null':
 146         from docutils.parsers import null
 147         return null.Parser
 148     if name in {'rst', 'restructuredtext', 'rest', 'restx', 'rtxt'}:
 149         from docutils.parsers import rst
 150         return rst.Parser
 151     if name in {'docutils_xml', 'xml'}:
 152         from docutils.parsers import docutils_xml
 153         return docutils_xml.Parser
 154
 155     try:
 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
 161         if name == 'myst':
 162             from myst_parser import docutils_ as myst_wrapper
 163             return myst_wrapper.Parser
 164
 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
 169
 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}')
 174     else:
 175         return module.Parser