docutils/docutils/parsers/recommonmark_wrapper.py

   1 #!/usr/bin/env python3
   2 # :Copyright: © 2020 Günter Milde.
   3 # :License: Released under the terms of the `2-Clause BSD license`_, in short:
   4 #
   5 #    Copying and distribution of this file, with or without modification,
   6 #    are permitted in any medium without royalty provided the copyright
   7 #    notice and this notice are preserved.
   8 #    This file is offered as-is, without any warranty.
   9 #
  10 # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
  11 #
  12 # Revision: $Revision$
  13 # Date: $Date$
  14 """
  15 A parser for CommonMark Markdown text using `recommonmark`__.
  16
  17 __ https://pypi.org/project/recommonmark/
  18
  19 .. important:: This module is deprecated.
  20
  21    * The "recommonmark" package is unmaintained and deprecated.
  22      This wrapper module will be removed in Docutils 1.0.
  23
  24    * The API is not settled and may change with any minor Docutils version.
  25 """
  26
  27 from docutils import Component
  28 from docutils import nodes
  29
  30 try:
  31     # If possible, import Sphinx's 'addnodes'
  32     from sphinx import addnodes
  33 except ImportError:
  34     # stub to prevent errors if Sphinx isn't installed
  35     import sys
  36     import types
  37
  38     class pending_xref(nodes.Inline, nodes.Element): ... # NoQA
  39
  40     sys.modules['sphinx'] = sphinx = types.ModuleType('sphinx')
  41     sphinx.addnodes = addnodes = types.SimpleNamespace()
  42     addnodes.pending_xref = pending_xref
  43 try:
  44     import recommonmark
  45     from recommonmark.parser import CommonMarkParser
  46 except ImportError as err:
  47     raise ImportError(
  48         'Parsing "recommonmark" Markdown flavour requires the\n'
  49         '  package https://pypi.org/project/recommonmark.'
  50     ) from err
  51 else:
  52     if recommonmark.__version__ < '0.6.0':
  53         raise ImportError('The installed version of "recommonmark" is too old.'
  54                           ' Update with "pip install -U recommonmark".')
  55
  56
  57 # auxiliary function for `document.findall()`
  58 def is_literal(node):
  59     return isinstance(node, (nodes.literal, nodes.literal_block))
  60
  61
  62 class Parser(CommonMarkParser):
  63     """MarkDown parser based on recommonmark.
  64
  65     This parser is provisional:
  66     the API is not settled and may change with any minor Docutils version.
  67     """
  68     supported = ('recommonmark', 'commonmark', 'markdown', 'md')
  69     """Formats this parser supports."""
  70
  71     config_section = 'recommonmark parser'
  72     config_section_dependencies = ('parsers',)
  73
  74     def get_transforms(self):
  75         return Component.get_transforms(self)  # + [AutoStructify]
  76
  77     def parse(self, inputstring, document):
  78         """Wrapper of upstream method.
  79
  80         Ensure "line-length-limt". Report errors with `document.reporter`.
  81         """
  82         # check for exorbitantly long lines
  83         for i, line in enumerate(inputstring.split('\n')):
  84             if len(line) > document.settings.line_length_limit:
  85                 error = document.reporter.error(
  86                     'Line %d exceeds the line-length-limit.'%(i+1))
  87                 document.append(error)
  88                 return
  89
  90         # pass to upstream parser
  91         try:
  92             CommonMarkParser.parse(self, inputstring, document)
  93         except Exception as err:
  94             if document.settings.traceback:
  95                 raise err
  96             error = document.reporter.error('Parsing with "recommonmark" '
  97                                             'returned the error:\n%s'%err)
  98             document.append(error)
  99
 100     # Post-Processing
 101     # ---------------
 102
 103     def finish_parse(self):
 104         """Finalize parse details.  Call at end of `self.parse()`."""
 105
 106         document = self.document
 107
 108         # merge adjoining Text nodes:
 109         for node in document.findall(nodes.TextElement):
 110             children = node.children
 111             i = 0
 112             while i+1 < len(children):
 113                 if (isinstance(children[i], nodes.Text)
 114                     and isinstance(children[i+1], nodes.Text)):
 115                     children[i] = nodes.Text(children[i]+children.pop(i+1))
 116                     children[i].parent = node
 117                 else:
 118                     i += 1
 119
 120         # remove empty Text nodes:
 121         for node in document.findall(nodes.Text):
 122             if not len(node):
 123                 node.parent.remove(node)
 124
 125         # add "code" class argument to literal elements (inline and block)
 126         for node in document.findall(is_literal):
 127             if 'code' not in node['classes']:
 128                 node['classes'].append('code')
 129         # move "language" argument to classes
 130         for node in document.findall(nodes.literal_block):
 131             if 'language' in node.attributes:
 132                 node['classes'].append(node['language'])
 133                 del node['language']
 134
 135         # replace raw nodes if raw is not allowed
 136         if not document.settings.raw_enabled:
 137             for node in document.findall(nodes.raw):
 138                 message = document.reporter.warning('Raw content disabled.')
 139                 if isinstance(node.parent, nodes.TextElement):
 140                     msgid = document.set_id(message)
 141                     problematic = nodes.problematic('', node.astext(),
 142                                                     refid=msgid)
 143                     node.parent.replace(node, problematic)
 144                     prbid = document.set_id(problematic)
 145                     message.add_backref(prbid)
 146                     document.append(message)
 147                 else:
 148                     node.parent.replace(node, message)
 149
 150         # drop pending_xref (Sphinx cross reference extension)
 151         for node in document.findall(addnodes.pending_xref):
 152             reference = node.children[0]
 153             if 'name' not in reference:
 154                 reference['name'] = nodes.fully_normalize_name(
 155                                                     reference.astext())
 156             node.parent.replace(node, reference)
 157         # now we are ready to call the upstream function:
 158         super().finish_parse()
 159
 160     def visit_document(self, node):
 161         """Dummy function to prevent spurious warnings.
 162
 163         cf. https://github.com/readthedocs/recommonmark/issues/177
 164         """
 165         pass
 166
 167     # Overwrite parent method with version that
 168     # doesn't pass deprecated `rawsource` argument to nodes.Text:
 169     def visit_text(self, mdnode):
 170         self.current_node.append(nodes.Text(mdnode.literal))