530 lines
20 KiB
Python
530 lines
20 KiB
Python
"""
|
|
Python Markdown
|
|
===============
|
|
|
|
Python Markdown converts Markdown to HTML and can be used as a library or
|
|
called from the command line.
|
|
|
|
## Basic usage as a module:
|
|
|
|
import markdown
|
|
html = markdown.markdown(your_text_string)
|
|
|
|
See <https://Python-Markdown.github.io/> for more
|
|
information and instructions on how to extend the functionality of
|
|
Python Markdown. Read that before you try modifying this file.
|
|
|
|
## Authors and License
|
|
|
|
Started by [Manfred Stienstra](http://www.dwerg.net/). Continued and
|
|
maintained by [Yuri Takhteyev](http://www.freewisdom.org), [Waylan
|
|
Limberg](http://achinghead.com/) and [Artem Yunusov](http://blog.splyer.com).
|
|
|
|
Contact: markdown@freewisdom.org
|
|
|
|
Copyright 2007-2013 The Python Markdown Project (v. 1.7 and later)
|
|
Copyright 200? Django Software Foundation (OrderedDict implementation)
|
|
Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
|
|
Copyright 2004 Manfred Stienstra (the original version)
|
|
|
|
License: BSD (see LICENSE for details).
|
|
"""
|
|
|
|
from __future__ import absolute_import
|
|
from __future__ import unicode_literals
|
|
from .__version__ import version, version_info # noqa
|
|
import codecs
|
|
import sys
|
|
import logging
|
|
import warnings
|
|
import importlib
|
|
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
|
|
|
|
__all__ = ['Markdown', 'markdown', 'markdownFromFile']
|
|
|
|
|
|
logger = logging.getLogger('MARKDOWN')
|
|
|
|
|
|
class Markdown(object):
|
|
"""Convert Markdown to HTML."""
|
|
|
|
doc_tag = "div" # Element used to wrap document - later removed
|
|
|
|
option_defaults = {
|
|
'html_replacement_text': '[HTML_REMOVED]',
|
|
'tab_length': 4,
|
|
'enable_attributes': True,
|
|
'smart_emphasis': True,
|
|
'lazy_ol': True,
|
|
}
|
|
|
|
output_formats = {
|
|
'html': to_html_string,
|
|
'html4': to_html_string,
|
|
'html5': to_html_string,
|
|
'xhtml': to_xhtml_string,
|
|
'xhtml1': to_xhtml_string,
|
|
'xhtml5': to_xhtml_string,
|
|
}
|
|
|
|
def __init__(self, *args, **kwargs):
|
|
"""
|
|
Creates a new Markdown instance.
|
|
|
|
Keyword arguments:
|
|
|
|
* extensions: A list of extensions.
|
|
If they are of type string, the module mdx_name.py will be loaded.
|
|
If they are a subclass of markdown.Extension, they will be used
|
|
as-is.
|
|
* extension_configs: Configuration settings for extensions.
|
|
* output_format: Format of output. Supported formats are:
|
|
* "xhtml1": Outputs XHTML 1.x. Default.
|
|
* "xhtml5": Outputs XHTML style tags of HTML 5
|
|
* "xhtml": Outputs latest supported version of XHTML
|
|
(currently XHTML 1.1).
|
|
* "html4": Outputs HTML 4
|
|
* "html5": Outputs HTML style tags of HTML 5
|
|
* "html": Outputs latest supported version of HTML
|
|
(currently HTML 4).
|
|
Note that it is suggested that the more specific formats ("xhtml1"
|
|
and "html4") be used as "xhtml" or "html" may change in the future
|
|
if it makes sense at that time.
|
|
* safe_mode: Deprecated! Disallow raw html. One of "remove", "replace"
|
|
or "escape".
|
|
* html_replacement_text: Deprecated! Text used when safe_mode is set
|
|
to "replace".
|
|
* tab_length: Length of tabs in the source. Default: 4
|
|
* enable_attributes: Enable the conversion of attributes. Default: True
|
|
* smart_emphasis: Treat `_connected_words_` intelligently Default: True
|
|
* lazy_ol: Ignore number of first item of ordered lists. Default: True
|
|
|
|
"""
|
|
|
|
# For backward compatibility, loop through old positional args
|
|
pos = ['extensions', 'extension_configs', 'safe_mode', 'output_format']
|
|
for c, arg in enumerate(args):
|
|
if pos[c] not in kwargs:
|
|
kwargs[pos[c]] = arg
|
|
if c+1 == len(pos): # pragma: no cover
|
|
# ignore any additional args
|
|
break
|
|
if len(args):
|
|
warnings.warn('Positional arguments are deprecated in Markdown. '
|
|
'Use keyword arguments only.',
|
|
DeprecationWarning)
|
|
|
|
# Loop through kwargs and assign defaults
|
|
for option, default in self.option_defaults.items():
|
|
setattr(self, option, kwargs.get(option, default))
|
|
|
|
self.safeMode = kwargs.get('safe_mode', False)
|
|
if self.safeMode and 'enable_attributes' not in kwargs:
|
|
# Disable attributes in safeMode when not explicitly set
|
|
self.enable_attributes = False
|
|
|
|
if 'safe_mode' in kwargs:
|
|
warnings.warn('"safe_mode" is deprecated in Python-Markdown. '
|
|
'Use an HTML sanitizer (like '
|
|
'Bleach https://bleach.readthedocs.io/) '
|
|
'if you are parsing untrusted markdown text. '
|
|
'See the 2.6 release notes for more info',
|
|
DeprecationWarning)
|
|
|
|
if 'html_replacement_text' in kwargs:
|
|
warnings.warn('The "html_replacement_text" keyword is '
|
|
'deprecated along with "safe_mode".',
|
|
DeprecationWarning)
|
|
|
|
self.ESCAPED_CHARS = ['\\', '`', '*', '_', '{', '}', '[', ']',
|
|
'(', ')', '>', '#', '+', '-', '.', '!']
|
|
|
|
self.registeredExtensions = []
|
|
self.docType = ""
|
|
self.stripTopLevelTags = True
|
|
|
|
self.build_parser()
|
|
|
|
self.references = {}
|
|
self.htmlStash = util.HtmlStash()
|
|
self.registerExtensions(extensions=kwargs.get('extensions', []),
|
|
configs=kwargs.get('extension_configs', {}))
|
|
self.set_output_format(kwargs.get('output_format', 'xhtml1'))
|
|
self.reset()
|
|
|
|
def build_parser(self):
|
|
""" Build the parser from the various parts. """
|
|
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, configs):
|
|
"""
|
|
Register extensions with this instance of Markdown.
|
|
|
|
Keyword arguments:
|
|
|
|
* extensions: A list of extensions, which can either
|
|
be strings or objects. See the docstring on Markdown.
|
|
* configs: A dictionary mapping module names to config options.
|
|
|
|
"""
|
|
for ext in extensions:
|
|
if isinstance(ext, util.string_type):
|
|
ext = self.build_extension(ext, configs.get(ext, {}))
|
|
if isinstance(ext, Extension):
|
|
ext.extendMarkdown(self, globals())
|
|
logger.debug(
|
|
'Successfully loaded extension "%s.%s".'
|
|
% (ext.__class__.__module__, ext.__class__.__name__)
|
|
)
|
|
elif ext is not None:
|
|
raise TypeError(
|
|
'Extension "%s.%s" must be of type: "markdown.Extension"'
|
|
% (ext.__class__.__module__, ext.__class__.__name__))
|
|
|
|
return self
|
|
|
|
def build_extension(self, ext_name, configs):
|
|
"""Build extension by name, then return the module.
|
|
|
|
The extension name may contain arguments as part of the string in the
|
|
following format: "extname(key1=value1,key2=value2)"
|
|
|
|
"""
|
|
|
|
configs = dict(configs)
|
|
|
|
# Parse extensions config params (ignore the order)
|
|
pos = ext_name.find("(") # find the first "("
|
|
if pos > 0:
|
|
ext_args = ext_name[pos+1:-1]
|
|
ext_name = ext_name[:pos]
|
|
pairs = [x.split("=") for x in ext_args.split(",")]
|
|
configs.update([(x.strip(), y.strip()) for (x, y) in pairs])
|
|
warnings.warn('Setting configs in the Named Extension string is '
|
|
'deprecated. It is recommended that you '
|
|
'pass an instance of the extension class to '
|
|
'Markdown or use the "extension_configs" keyword. '
|
|
'The current behavior will raise an error in version 2.7. '
|
|
'See the Release Notes for Python-Markdown version '
|
|
'2.6 for more info.', DeprecationWarning)
|
|
|
|
# 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 loading the extension first from one place, then another
|
|
try:
|
|
# Assume string uses dot syntax (`path.to.some.module`)
|
|
module = importlib.import_module(ext_name)
|
|
logger.debug(
|
|
'Successfuly imported extension module "%s".' % ext_name
|
|
)
|
|
# For backward compat (until deprecation)
|
|
# check that this is an extension.
|
|
if ('.' not in ext_name and not (hasattr(module, 'makeExtension') or
|
|
(class_name and hasattr(module, class_name)))):
|
|
# We have a name conflict
|
|
# eg: extensions=['tables'] and PyTables is installed
|
|
raise ImportError
|
|
except ImportError:
|
|
# Preppend `markdown.extensions.` to name
|
|
module_name = '.'.join(['markdown.extensions', ext_name])
|
|
try:
|
|
module = importlib.import_module(module_name)
|
|
logger.debug(
|
|
'Successfuly imported extension module "%s".' %
|
|
module_name
|
|
)
|
|
warnings.warn('Using short names for Markdown\'s builtin '
|
|
'extensions is deprecated. Use the '
|
|
'full path to the extension with Python\'s dot '
|
|
'notation (eg: "%s" instead of "%s"). The '
|
|
'current behavior will raise an error in version '
|
|
'2.7. See the Release Notes for '
|
|
'Python-Markdown version 2.6 for more info.' %
|
|
(module_name, ext_name),
|
|
DeprecationWarning)
|
|
except ImportError:
|
|
# Preppend `mdx_` to name
|
|
module_name_old_style = '_'.join(['mdx', ext_name])
|
|
try:
|
|
module = importlib.import_module(module_name_old_style)
|
|
logger.debug(
|
|
'Successfuly imported extension module "%s".' %
|
|
module_name_old_style)
|
|
warnings.warn('Markdown\'s behavior of prepending "mdx_" '
|
|
'to an extension name is deprecated. '
|
|
'Use the full path to the '
|
|
'extension with Python\'s dot notation '
|
|
'(eg: "%s" instead of "%s"). The current '
|
|
'behavior will raise an error in version 2.7. '
|
|
'See the Release Notes for Python-Markdown '
|
|
'version 2.6 for more info.' %
|
|
(module_name_old_style, ext_name),
|
|
DeprecationWarning)
|
|
except ImportError as e:
|
|
message = "Failed loading extension '%s' from '%s', '%s' " \
|
|
"or '%s'" % (ext_name, ext_name, module_name,
|
|
module_name_old_style)
|
|
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):
|
|
""" This gets called by the extension """
|
|
self.registeredExtensions.append(extension)
|
|
return self
|
|
|
|
def reset(self):
|
|
"""
|
|
Resets all state variables so that we can start with a new text.
|
|
"""
|
|
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):
|
|
""" Set the output format for the class instance. """
|
|
self.output_format = format.lower()
|
|
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
|
|
|
|
def convert(self, source):
|
|
"""
|
|
Convert markdown to serialized XHTML or HTML.
|
|
|
|
Keyword arguments:
|
|
|
|
* source: Source text as a Unicode string.
|
|
|
|
Markdown processing takes place in five steps:
|
|
|
|
1. A bunch of "preprocessors" munge the input text.
|
|
2. BlockParser() parses the high-level structural elements of the
|
|
pre-processed text into an ElementTree.
|
|
3. A bunch of "treeprocessors" are run against the ElementTree. One
|
|
such treeprocessor runs InlinePatterns against the ElementTree,
|
|
detecting inline markup.
|
|
4. Some post-processors are run against the text after the ElementTree
|
|
has been serialized into text.
|
|
5. The output is written to a string.
|
|
|
|
"""
|
|
|
|
# Fixup the source text
|
|
if not source.strip():
|
|
return '' # a blank unicode string
|
|
|
|
try:
|
|
source = util.text_type(source)
|
|
except UnicodeDecodeError as e:
|
|
# Customise error message while maintaining original trackback
|
|
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.values():
|
|
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.values():
|
|
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: # 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())
|
|
|
|
# Run the text post-processors
|
|
for pp in self.postprocessors.values():
|
|
output = pp.run(output)
|
|
|
|
return output.strip()
|
|
|
|
def convertFile(self, input=None, output=None, encoding=None):
|
|
"""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' 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.)
|
|
|
|
Keyword 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, util.string_type):
|
|
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()
|
|
if not isinstance(text, util.text_type):
|
|
text = text.decode(encoding)
|
|
|
|
text = text.lstrip('\ufeff') # remove the byte-order mark
|
|
|
|
# Convert
|
|
html = self.convert(text)
|
|
|
|
# Write to file or stdout
|
|
if output:
|
|
if isinstance(output, util.string_type):
|
|
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")
|
|
try:
|
|
# Write bytes directly to buffer (Python 3).
|
|
sys.stdout.buffer.write(html)
|
|
except AttributeError:
|
|
# Probably Python 2, which works with bytes by default.
|
|
sys.stdout.write(html)
|
|
|
|
return self
|
|
|
|
|
|
"""
|
|
EXPORTED FUNCTIONS
|
|
=============================================================================
|
|
|
|
Those are the two functions we really mean to export: markdown() and
|
|
markdownFromFile().
|
|
"""
|
|
|
|
|
|
def markdown(text, *args, **kwargs):
|
|
"""Convert a Markdown string to HTML and return HTML as a Unicode string.
|
|
|
|
This is a shortcut function for `Markdown` class to cover the most
|
|
basic use case. It initializes an instance of Markdown, loads the
|
|
necessary extensions and runs the parser on the given text.
|
|
|
|
Keyword arguments:
|
|
|
|
* text: Markdown formatted text as Unicode or ASCII string.
|
|
* Any arguments accepted by the Markdown class.
|
|
|
|
Returns: An HTML document as a string.
|
|
|
|
"""
|
|
md = Markdown(*args, **kwargs)
|
|
return md.convert(text)
|
|
|
|
|
|
def markdownFromFile(*args, **kwargs):
|
|
"""Read markdown code from a file and write it to a file or a stream.
|
|
|
|
This is a shortcut function which initializes an instance of Markdown,
|
|
and calls the convertFile method rather than convert.
|
|
|
|
Keyword arguments:
|
|
|
|
* input: a file name or readable object.
|
|
* output: a file name or writable object.
|
|
* encoding: Encoding of input and output.
|
|
* Any arguments accepted by the Markdown class.
|
|
|
|
"""
|
|
# For backward compatibility loop through positional args
|
|
pos = ['input', 'output', 'extensions', 'encoding']
|
|
c = 0
|
|
for arg in args:
|
|
if pos[c] not in kwargs:
|
|
kwargs[pos[c]] = arg
|
|
c += 1
|
|
if c == len(pos):
|
|
break
|
|
if len(args):
|
|
warnings.warn('Positional arguments are depreacted in '
|
|
'Markdown and will raise an error in version 2.7. '
|
|
'Use keyword arguments only.',
|
|
DeprecationWarning)
|
|
|
|
md = Markdown(**kwargs)
|
|
md.convertFile(kwargs.get('input', None),
|
|
kwargs.get('output', None),
|
|
kwargs.get('encoding', None))
|