504 lines
21 KiB
Python
504 lines
21 KiB
Python
# Python Markdown
|
|
|
|
# A Python implementation of John Gruber's Markdown.
|
|
|
|
# Documentation: https://python-markdown.github.io/
|
|
# GitHub: https://github.com/Python-Markdown/markdown/
|
|
# PyPI: https://pypi.org/project/Markdown/
|
|
|
|
# Started by Manfred Stienstra (http://www.dwerg.net/).
|
|
# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
|
|
# Currently maintained by Waylan Limberg (https://github.com/waylan),
|
|
# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
|
|
|
|
# Copyright 2007-2023 The Python Markdown Project (v. 1.7 and later)
|
|
# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
|
|
# Copyright 2004 Manfred Stienstra (the original version)
|
|
|
|
# License: BSD (see LICENSE.md for details).
|
|
|
|
from __future__ import annotations
|
|
|
|
import codecs
|
|
import sys
|
|
import logging
|
|
import importlib
|
|
from typing import TYPE_CHECKING, Any, BinaryIO, Callable, ClassVar, Mapping, Sequence
|
|
from . import util
|
|
from .preprocessors import build_preprocessors
|
|
from .blockprocessors import build_block_parser
|
|
from .treeprocessors import build_treeprocessors
|
|
from .inlinepatterns import build_inlinepatterns
|
|
from .postprocessors import build_postprocessors
|
|
from .extensions import Extension
|
|
from .serializers import to_html_string, to_xhtml_string
|
|
from .util import BLOCK_LEVEL_ELEMENTS
|
|
|
|
if TYPE_CHECKING: # pragma: no cover
|
|
from xml.etree.ElementTree import Element
|
|
|
|
__all__ = ['Markdown', 'markdown', 'markdownFromFile']
|
|
|
|
|
|
logger = logging.getLogger('MARKDOWN')
|
|
|
|
|
|
class Markdown:
|
|
"""
|
|
A parser which converts Markdown to HTML.
|
|
|
|
Attributes:
|
|
Markdown.tab_length (int): The number of spaces which correspond to a single tab. Default: `4`.
|
|
Markdown.ESCAPED_CHARS (list[str]): List of characters which get the backslash escape treatment.
|
|
Markdown.block_level_elements (list[str]): List of HTML tags which get treated as block-level elements.
|
|
See [`markdown.util.BLOCK_LEVEL_ELEMENTS`][] for the full list of elements.
|
|
Markdown.registeredExtensions (list[Extension]): List of extensions which have called
|
|
[`registerExtension`][markdown.Markdown.registerExtension] during setup.
|
|
Markdown.doc_tag (str): Element used to wrap document. Default: `div`.
|
|
Markdown.stripTopLevelTags (bool): Indicates whether the `doc_tag` should be removed. Default: 'True'.
|
|
Markdown.references (dict[str, tuple[str, str]]): A mapping of link references found in a parsed document
|
|
where the key is the reference name and the value is a tuple of the URL and title.
|
|
Markdown.htmlStash (util.HtmlStash): The instance of the `HtmlStash` used by an instance of this class.
|
|
Markdown.output_formats (dict[str, Callable[xml.etree.ElementTree.Element]]): A mapping of known output
|
|
formats by name and their respective serializers. Each serializer must be a callable which accepts an
|
|
[`Element`][xml.etree.ElementTree.Element] and returns a `str`.
|
|
Markdown.output_format (str): The output format set by
|
|
[`set_output_format`][markdown.Markdown.set_output_format].
|
|
Markdown.serializer (Callable[xml.etree.ElementTree.Element]): The serializer set by
|
|
[`set_output_format`][markdown.Markdown.set_output_format].
|
|
Markdown.preprocessors (util.Registry): A collection of [`preprocessors`][markdown.preprocessors].
|
|
Markdown.parser (blockparser.BlockParser): A collection of [`blockprocessors`][markdown.blockprocessors].
|
|
Markdown.inlinePatterns (util.Registry): A collection of [`inlinepatterns`][markdown.inlinepatterns].
|
|
Markdown.treeprocessors (util.Registry): A collection of [`treeprocessors`][markdown.treeprocessors].
|
|
Markdown.postprocessors (util.Registry): A collection of [`postprocessors`][markdown.postprocessors].
|
|
|
|
"""
|
|
|
|
doc_tag = "div" # Element used to wrap document - later removed
|
|
|
|
output_formats: ClassVar[dict[str, Callable[[Element], str]]] = {
|
|
'html': to_html_string,
|
|
'xhtml': to_xhtml_string,
|
|
}
|
|
"""
|
|
A mapping of known output formats by name and their respective serializers. Each serializer must be a
|
|
callable which accepts an [`Element`][xml.etree.ElementTree.Element] and returns a `str`.
|
|
"""
|
|
|
|
def __init__(self, **kwargs):
|
|
"""
|
|
Creates a new Markdown instance.
|
|
|
|
Keyword Arguments:
|
|
extensions (list[Extension | str]): A list of extensions.
|
|
|
|
If an item is an instance of a subclass of [`markdown.extensions.Extension`][],
|
|
the instance will be used as-is. If an item is of type `str`, it is passed
|
|
to [`build_extension`][markdown.Markdown.build_extension] with its corresponding
|
|
`extension_configs` and the returned instance of [`markdown.extensions.Extension`][]
|
|
is used.
|
|
extension_configs (dict[str, dict[str, Any]]): Configuration settings for extensions.
|
|
output_format (str): Format of output. Supported formats are:
|
|
|
|
* `xhtml`: Outputs XHTML style tags. Default.
|
|
* `html`: Outputs HTML style tags.
|
|
tab_length (int): Length of tabs in the source. Default: `4`
|
|
|
|
"""
|
|
|
|
self.tab_length: int = kwargs.get('tab_length', 4)
|
|
|
|
self.ESCAPED_CHARS: list[str] = [
|
|
'\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '>', '#', '+', '-', '.', '!'
|
|
]
|
|
""" List of characters which get the backslash escape treatment. """
|
|
|
|
self.block_level_elements: list[str] = BLOCK_LEVEL_ELEMENTS.copy()
|
|
|
|
self.registeredExtensions: list[Extension] = []
|
|
self.docType = "" # TODO: Maybe delete this. It does not appear to be used anymore.
|
|
self.stripTopLevelTags: bool = True
|
|
|
|
self.build_parser()
|
|
|
|
self.references: dict[str, tuple[str, str]] = {}
|
|
self.htmlStash: util.HtmlStash = util.HtmlStash()
|
|
self.registerExtensions(extensions=kwargs.get('extensions', []),
|
|
configs=kwargs.get('extension_configs', {}))
|
|
self.set_output_format(kwargs.get('output_format', 'xhtml'))
|
|
self.reset()
|
|
|
|
def build_parser(self) -> Markdown:
|
|
"""
|
|
Build the parser from the various parts.
|
|
|
|
Assigns a value to each of the following attributes on the class instance:
|
|
|
|
* **`Markdown.preprocessors`** ([`Registry`][markdown.util.Registry]) -- A collection of
|
|
[`preprocessors`][markdown.preprocessors].
|
|
* **`Markdown.parser`** ([`BlockParser`][markdown.blockparser.BlockParser]) -- A collection of
|
|
[`blockprocessors`][markdown.blockprocessors].
|
|
* **`Markdown.inlinePatterns`** ([`Registry`][markdown.util.Registry]) -- A collection of
|
|
[`inlinepatterns`][markdown.inlinepatterns].
|
|
* **`Markdown.treeprocessors`** ([`Registry`][markdown.util.Registry]) -- A collection of
|
|
[`treeprocessors`][markdown.treeprocessors].
|
|
* **`Markdown.postprocessors`** ([`Registry`][markdown.util.Registry]) -- A collection of
|
|
[`postprocessors`][markdown.postprocessors].
|
|
|
|
This method could be redefined in a subclass to build a custom parser which is made up of a different
|
|
combination of processors and patterns.
|
|
|
|
"""
|
|
self.preprocessors = build_preprocessors(self)
|
|
self.parser = build_block_parser(self)
|
|
self.inlinePatterns = build_inlinepatterns(self)
|
|
self.treeprocessors = build_treeprocessors(self)
|
|
self.postprocessors = build_postprocessors(self)
|
|
return self
|
|
|
|
def registerExtensions(
|
|
self,
|
|
extensions: Sequence[Extension | str],
|
|
configs: Mapping[str, dict[str, Any]]
|
|
) -> Markdown:
|
|
"""
|
|
Load a list of extensions into an instance of the `Markdown` class.
|
|
|
|
Arguments:
|
|
extensions (list[Extension | str]): A list of extensions.
|
|
|
|
If an item is an instance of a subclass of [`markdown.extensions.Extension`][],
|
|
the instance will be used as-is. If an item is of type `str`, it is passed
|
|
to [`build_extension`][markdown.Markdown.build_extension] with its corresponding `configs` and the
|
|
returned instance of [`markdown.extensions.Extension`][] is used.
|
|
configs (dict[str, dict[str, Any]]): Configuration settings for extensions.
|
|
|
|
"""
|
|
for ext in extensions:
|
|
if isinstance(ext, str):
|
|
ext = self.build_extension(ext, configs.get(ext, {}))
|
|
if isinstance(ext, Extension):
|
|
ext.extendMarkdown(self)
|
|
logger.debug(
|
|
'Successfully loaded extension "%s.%s".'
|
|
% (ext.__class__.__module__, ext.__class__.__name__)
|
|
)
|
|
elif ext is not None:
|
|
raise TypeError(
|
|
'Extension "{}.{}" must be of type: "{}.{}"'.format(
|
|
ext.__class__.__module__, ext.__class__.__name__,
|
|
Extension.__module__, Extension.__name__
|
|
)
|
|
)
|
|
return self
|
|
|
|
def build_extension(self, ext_name: str, configs: Mapping[str, Any]) -> Extension:
|
|
"""
|
|
Build extension from a string name, then return an instance using the given `configs`.
|
|
|
|
Arguments:
|
|
ext_name: Name of extension as a string.
|
|
configs: Configuration settings for extension.
|
|
|
|
Returns:
|
|
An instance of the extension with the given configuration settings.
|
|
|
|
First attempt to load an entry point. The string name must be registered as an entry point in the
|
|
`markdown.extensions` group which points to a subclass of the [`markdown.extensions.Extension`][] class.
|
|
If multiple distributions have registered the same name, the first one found is returned.
|
|
|
|
If no entry point is found, assume dot notation (`path.to.module:ClassName`). Load the specified class and
|
|
return an instance. If no class is specified, import the module and call a `makeExtension` function and return
|
|
the [`markdown.extensions.Extension`][] instance returned by that function.
|
|
"""
|
|
configs = dict(configs)
|
|
|
|
entry_points = [ep for ep in util.get_installed_extensions() if ep.name == ext_name]
|
|
if entry_points:
|
|
ext = entry_points[0].load()
|
|
return ext(**configs)
|
|
|
|
# Get class name (if provided): `path.to.module:ClassName`
|
|
ext_name, class_name = ext_name.split(':', 1) if ':' in ext_name else (ext_name, '')
|
|
|
|
try:
|
|
module = importlib.import_module(ext_name)
|
|
logger.debug(
|
|
'Successfully imported extension module "%s".' % ext_name
|
|
)
|
|
except ImportError as e:
|
|
message = 'Failed loading extension "%s".' % ext_name
|
|
e.args = (message,) + e.args[1:]
|
|
raise
|
|
|
|
if class_name:
|
|
# Load given class name from module.
|
|
return getattr(module, class_name)(**configs)
|
|
else:
|
|
# Expect `makeExtension()` function to return a class.
|
|
try:
|
|
return module.makeExtension(**configs)
|
|
except AttributeError as e:
|
|
message = e.args[0]
|
|
message = "Failed to initiate extension " \
|
|
"'%s': %s" % (ext_name, message)
|
|
e.args = (message,) + e.args[1:]
|
|
raise
|
|
|
|
def registerExtension(self, extension: Extension) -> Markdown:
|
|
"""
|
|
Register an extension as having a resettable state.
|
|
|
|
Arguments:
|
|
extension: An instance of the extension to register.
|
|
|
|
This should get called once by an extension during setup. A "registered" extension's
|
|
`reset` method is called by [`Markdown.reset()`][markdown.Markdown.reset]. Not all extensions have or need a
|
|
resettable state, and so it should not be assumed that all extensions are "registered."
|
|
|
|
"""
|
|
self.registeredExtensions.append(extension)
|
|
return self
|
|
|
|
def reset(self) -> Markdown:
|
|
"""
|
|
Resets all state variables to prepare the parser instance for new input.
|
|
|
|
Called once upon creation of a class instance. Should be called manually between calls
|
|
to [`Markdown.convert`][markdown.Markdown.convert].
|
|
"""
|
|
self.htmlStash.reset()
|
|
self.references.clear()
|
|
|
|
for extension in self.registeredExtensions:
|
|
if hasattr(extension, 'reset'):
|
|
extension.reset()
|
|
|
|
return self
|
|
|
|
def set_output_format(self, format: str) -> Markdown:
|
|
"""
|
|
Set the output format for the class instance.
|
|
|
|
Arguments:
|
|
format: Must be a known value in `Markdown.output_formats`.
|
|
|
|
"""
|
|
self.output_format = format.lower().rstrip('145') # ignore number
|
|
try:
|
|
self.serializer = self.output_formats[self.output_format]
|
|
except KeyError as e:
|
|
valid_formats = list(self.output_formats.keys())
|
|
valid_formats.sort()
|
|
message = 'Invalid Output Format: "%s". Use one of %s.' \
|
|
% (self.output_format,
|
|
'"' + '", "'.join(valid_formats) + '"')
|
|
e.args = (message,) + e.args[1:]
|
|
raise
|
|
return self
|
|
|
|
# Note: the `tag` argument is type annotated `Any` as ElementTree uses many various objects as tags.
|
|
# As there is no standardization in ElementTree, the type of a given tag is unpredictable.
|
|
def is_block_level(self, tag: Any) -> bool:
|
|
"""
|
|
Check if the given `tag` is a block level HTML tag.
|
|
|
|
Returns `True` for any string listed in `Markdown.block_level_elements`. A `tag` which is
|
|
not a string always returns `False`.
|
|
|
|
"""
|
|
if isinstance(tag, str):
|
|
return tag.lower().rstrip('/') in self.block_level_elements
|
|
# Some ElementTree tags are not strings, so return False.
|
|
return False
|
|
|
|
def convert(self, source: str) -> str:
|
|
"""
|
|
Convert a Markdown string to a string in the specified output format.
|
|
|
|
Arguments:
|
|
source: Markdown formatted text as Unicode or ASCII string.
|
|
|
|
Returns:
|
|
A string in the specified output format.
|
|
|
|
Markdown parsing takes place in five steps:
|
|
|
|
1. A bunch of [`preprocessors`][markdown.preprocessors] munge the input text.
|
|
2. A [`BlockParser`][markdown.blockparser.BlockParser] parses the high-level structural elements of the
|
|
pre-processed text into an [`ElementTree`][xml.etree.ElementTree.ElementTree] object.
|
|
3. A bunch of [`treeprocessors`][markdown.treeprocessors] are run against the
|
|
[`ElementTree`][xml.etree.ElementTree.ElementTree] object. One such `treeprocessor`
|
|
([`markdown.treeprocessors.InlineProcessor`][]) runs [`inlinepatterns`][markdown.inlinepatterns]
|
|
against the [`ElementTree`][xml.etree.ElementTree.ElementTree] object, parsing inline markup.
|
|
4. Some [`postprocessors`][markdown.postprocessors] are run against the text after the
|
|
[`ElementTree`][xml.etree.ElementTree.ElementTree] object has been serialized into text.
|
|
5. The output is returned as a string.
|
|
|
|
"""
|
|
|
|
# Fix up the source text
|
|
if not source.strip():
|
|
return '' # a blank Unicode string
|
|
|
|
try:
|
|
source = str(source)
|
|
except UnicodeDecodeError as e: # pragma: no cover
|
|
# Customize error message while maintaining original traceback
|
|
e.reason += '. -- Note: Markdown only accepts Unicode input!'
|
|
raise
|
|
|
|
# Split into lines and run the line preprocessors.
|
|
self.lines = source.split("\n")
|
|
for prep in self.preprocessors:
|
|
self.lines = prep.run(self.lines)
|
|
|
|
# Parse the high-level elements.
|
|
root = self.parser.parseDocument(self.lines).getroot()
|
|
|
|
# Run the tree-processors
|
|
for treeprocessor in self.treeprocessors:
|
|
newRoot = treeprocessor.run(root)
|
|
if newRoot is not None:
|
|
root = newRoot
|
|
|
|
# Serialize _properly_. Strip top-level tags.
|
|
output = self.serializer(root)
|
|
if self.stripTopLevelTags:
|
|
try:
|
|
start = output.index(
|
|
'<%s>' % self.doc_tag) + len(self.doc_tag) + 2
|
|
end = output.rindex('</%s>' % self.doc_tag)
|
|
output = output[start:end].strip()
|
|
except ValueError as e: # pragma: no cover
|
|
if output.strip().endswith('<%s />' % self.doc_tag):
|
|
# We have an empty document
|
|
output = ''
|
|
else:
|
|
# We have a serious problem
|
|
raise ValueError('Markdown failed to strip top-level '
|
|
'tags. Document=%r' % output.strip()) from e
|
|
|
|
# Run the text post-processors
|
|
for pp in self.postprocessors:
|
|
output = pp.run(output)
|
|
|
|
return output.strip()
|
|
|
|
def convertFile(
|
|
self,
|
|
input: str | BinaryIO | None = None,
|
|
output: str | BinaryIO | None = None,
|
|
encoding: str | None = None,
|
|
) -> Markdown:
|
|
"""
|
|
Converts a Markdown file and returns the HTML as a Unicode string.
|
|
|
|
Decodes the file using the provided encoding (defaults to `utf-8`),
|
|
passes the file content to markdown, and outputs the HTML to either
|
|
the provided stream or the file with provided name, using the same
|
|
encoding as the source file. The
|
|
[`xmlcharrefreplace`](https://docs.python.org/3/library/codecs.html#error-handlers)
|
|
error handler is used when encoding the output.
|
|
|
|
**Note:** This is the only place that decoding and encoding of Unicode
|
|
takes place in Python-Markdown. (All other code is Unicode-in /
|
|
Unicode-out.)
|
|
|
|
Arguments:
|
|
input: File object or path. Reads from `stdin` if `None`.
|
|
output: File object or path. Writes to `stdout` if `None`.
|
|
encoding: Encoding of input and output files. Defaults to `utf-8`.
|
|
|
|
"""
|
|
|
|
encoding = encoding or "utf-8"
|
|
|
|
# Read the source
|
|
if input:
|
|
if isinstance(input, str):
|
|
input_file = codecs.open(input, mode="r", encoding=encoding)
|
|
else:
|
|
input_file = codecs.getreader(encoding)(input)
|
|
text = input_file.read()
|
|
input_file.close()
|
|
else:
|
|
text = sys.stdin.read()
|
|
|
|
text = text.lstrip('\ufeff') # remove the byte-order mark
|
|
|
|
# Convert
|
|
html = self.convert(text)
|
|
|
|
# Write to file or stdout
|
|
if output:
|
|
if isinstance(output, str):
|
|
output_file = codecs.open(output, "w",
|
|
encoding=encoding,
|
|
errors="xmlcharrefreplace")
|
|
output_file.write(html)
|
|
output_file.close()
|
|
else:
|
|
writer = codecs.getwriter(encoding)
|
|
output_file = writer(output, errors="xmlcharrefreplace")
|
|
output_file.write(html)
|
|
# Don't close here. User may want to write more.
|
|
else:
|
|
# Encode manually and write bytes to stdout.
|
|
html = html.encode(encoding, "xmlcharrefreplace")
|
|
sys.stdout.buffer.write(html)
|
|
|
|
return self
|
|
|
|
|
|
"""
|
|
EXPORTED FUNCTIONS
|
|
=============================================================================
|
|
|
|
Those are the two functions we really mean to export: `markdown()` and
|
|
`markdownFromFile()`.
|
|
"""
|
|
|
|
|
|
def markdown(text: str, **kwargs: Any) -> str:
|
|
"""
|
|
Convert a markdown string to HTML and return HTML as a Unicode string.
|
|
|
|
This is a shortcut function for [`Markdown`][markdown.Markdown] class to cover the most
|
|
basic use case. It initializes an instance of [`Markdown`][markdown.Markdown], loads the
|
|
necessary extensions and runs the parser on the given text.
|
|
|
|
Arguments:
|
|
text: Markdown formatted text as Unicode or ASCII string.
|
|
|
|
Keyword arguments:
|
|
**kwargs: Any arguments accepted by the Markdown class.
|
|
|
|
Returns:
|
|
A string in the specified output format.
|
|
|
|
"""
|
|
md = Markdown(**kwargs)
|
|
return md.convert(text)
|
|
|
|
|
|
def markdownFromFile(**kwargs: Any):
|
|
"""
|
|
Read Markdown text from a file and write output to a file or a stream.
|
|
|
|
This is a shortcut function which initializes an instance of [`Markdown`][markdown.Markdown],
|
|
and calls the [`convertFile`][markdown.Markdown.convertFile] method rather than
|
|
[`convert`][markdown.Markdown.convert].
|
|
|
|
Keyword arguments:
|
|
input (str | BinaryIO): A file name or readable object.
|
|
output (str | BinaryIO): A file name or writable object.
|
|
encoding (str): Encoding of input and output.
|
|
**kwargs: Any arguments accepted by the `Markdown` class.
|
|
|
|
"""
|
|
md = Markdown(**kwargs)
|
|
md.convertFile(kwargs.get('input', None),
|
|
kwargs.get('output', None),
|
|
kwargs.get('encoding', None))
|