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 __docformat__ = 'reStructuredText'
  10
  11 from importlib import import_module
  12
  13 from docutils import Component, frontend, transforms
  14
  15
  16 class 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 get_transforms(self):
  55         return super().get_transforms() + [transforms.universal.Validate]
  56
  57     def parse(self, inputstring, document):
  58         """Override to parse `inputstring` into document tree `document`."""
  59         raise NotImplementedError('subclass must override this method')
  60
  61     def setup_parse(self, inputstring, document):
  62         """Initial parse setup.  Call at start of `self.parse()`."""
  63         self.inputstring = inputstring
  64         # provide fallbacks in case the document has only generic settings
  65         document.settings.setdefault('file_insertion_enabled', False)
  66         document.settings.setdefault('raw_enabled', False)
  67         document.settings.setdefault('line_length_limit', 10000)
  68         self.document = document
  69         document.reporter.attach_observer(document.note_parse_message)
  70
  71     def finish_parse(self):
  72         """Finalize parse details.  Call at end of `self.parse()`."""
  73         self.document.reporter.detach_observer(
  74             self.document.note_parse_message)
  75
  76
  77 _parser_aliases = {  # short names for known parsers
  78                    'null': 'docutils.parsers.null',
  79                    # reStructuredText
  80                    'rst': 'docutils.parsers.rst',
  81                    'restructuredtext': 'docutils.parsers.rst',
  82                    'rest': 'docutils.parsers.rst',
  83                    'restx': 'docutils.parsers.rst',
  84                    'rtxt': 'docutils.parsers.rst',
  85                    # Docutils XML
  86                    'docutils_xml': 'docutils.parsers.docutils_xml',
  87                    'xml': 'docutils.parsers.docutils_xml',
  88                    # 3rd-party Markdown parsers
  89                    'recommonmark': 'docutils.parsers.recommonmark_wrapper',
  90                    'myst': 'myst_parser.docutils_',
  91                    # 'pycmark': works out of the box
  92                    # dispatcher for 3rd-party Markdown parsers
  93                    'commonmark': 'docutils.parsers.commonmark_wrapper',
  94                    'markdown': 'docutils.parsers.commonmark_wrapper',
  95                   }
  96
  97
  98 def get_parser_class(parser_name):
  99     """Return the Parser class from the `parser_name` module."""
 100     name = parser_name.lower()
 101     try:
 102         module = import_module(_parser_aliases.get(name, name))
 103     except ImportError as err:
 104         raise ImportError(f'Parser "{parser_name}" not found. {err}')
 105     return module.Parser