docutils/docutils/parsers/commonmark_wrapper.py

   1 #! /usr/bin/env python3
   2 # :Copyright: © 2022 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 An interface for parsing CommonMark input.
  16
  17 Select a locally installed parser from the following 3rd-party
  18 parser packages:
  19
  20 :pycmark:       https://pypi.org/project/pycmark/
  21 :myst:          https://pypi.org/project/myst-docutils/
  22 :recommonmark:  https://pypi.org/project/recommonmark/ (deprecated)
  23
  24 The first parser class that can be successfully imported is mapped to
  25 `commonmark_wrapper.Parser`.
  26
  27 This module is provisional:
  28 the API is not settled and may change with any minor Docutils version.
  29 """
  30
  31 import docutils.parsers
  32
  33
  34 commonmark_parser_names = ('pycmark', 'myst', 'recommonmark')
  35 """Names of compatible drop-in CommonMark parsers"""
  36
  37 Parser = None
  38 parser_name = ''
  39
  40 for name in commonmark_parser_names:
  41     try:
  42         Parser = docutils.parsers.get_parser_class(name)
  43     except ImportError:
  44         continue
  45     parser_name = name
  46     break
  47
  48 if Parser is None:
  49     raise ImportError(
  50               'Parsing "CommonMark" requires one of the packages\n'
  51               f'{commonmark_parser_names} available at https://pypi.org')
  52
  53 if parser_name == 'myst':
  54     if not Parser.settings_defaults:
  55         Parser.settings_defaults = {}
  56     Parser.settings_defaults['myst_commonmark_only'] = True