markdown

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://pythonhosted.org/Markdown/ 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. Continued and maintained by Yuri Takhteyev, Waylan Limberg and Artem Yunusov.

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).

Attributes

logger = logging.getLogger('MARKDOWN') module-attribute

Classes

Markdown(*args, **kwargs)

Bases: object

Convert Markdown to HTML.

Creates a new Markdown instance.

Parameters:

Name	Type	Description	Default
*args	Any	positional args	()
**kwargs	Any	keyword args	{}

Other Parameters:

Name	Type	Description
extensions	list[Extension | str]	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	dict[str, Any]	Configuration settings for extensions.
output_format	str	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	str	Deprecated! Disallow raw html. One of "remove", "replace" or "escape".
html_replacement_text	str	Deprecated! Text used when safe_mode is set to "replace".
tab_length	int	Length of tabs in the source. Default: 4
enable_attributes	bool	Enable the conversion of attributes. Default: True
smart_emphasis	bool	Treat _connected_words_ intelligently Default: True
lazy_ol	bool	Ignore number of first item of ordered lists. Default: True

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

def __init__(self, *args, **kwargs):
    """Creates a new Markdown instance.

    Args:
        *args (Any): positional args
        **kwargs (Any): keyword args

    Keyword Args:
        extensions (list[Extension | str]): 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 (dict[str, Any]): Configuration settings for extensions.
        output_format (str): 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 (str): Deprecated! Disallow raw html.
            One of "remove", "replace" or "escape".
        html_replacement_text (str): Deprecated! Text used when safe_mode
            is set to "replace".
        tab_length (int): Length of tabs in the source. Default: 4
        enable_attributes (bool): Enable the conversion of attributes.
            Default: True
        smart_emphasis (bool): Treat `_connected_words_` intelligently
            Default: True
        lazy_ol (bool): 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()

Attributes

doc_tag = 'div' class-attribute instance-attribute

option_defaults = {'html_replacement_text': '[HTML_REMOVED]', 'tab_length': 4, 'enable_attributes': True, 'smart_emphasis': True, 'lazy_ol': True} class-attribute instance-attribute

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} class-attribute instance-attribute

safeMode = kwargs.get('safe_mode', False) instance-attribute

enable_attributes = False instance-attribute

ESCAPED_CHARS = ['\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '>', '#', '+', '-', '.', '!'] instance-attribute

registeredExtensions = [] instance-attribute

docType = '' instance-attribute

stripTopLevelTags = True instance-attribute

references = {} instance-attribute

htmlStash = util.HtmlStash() instance-attribute

Functions

build_parser()

Build the parser from the various parts.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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

registerExtensions(extensions, configs)

Register extensions with this instance of Markdown.

Parameters:

Name	Type	Description	Default
extensions	list[Extension]	extensions strings or objects. See the docstring on Markdown.	required
configs	dict[str, Any]	A dictionary mapping module names to config options.	required

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

def registerExtensions(self, extensions, configs):
    """Register extensions with this instance of Markdown.

    Args:
        extensions (list[Extension]): extensions strings or objects.
            See the docstring on Markdown.
        configs (dict[str, Any]): 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

build_extension(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)"

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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

registerExtension(extension)

This gets called by the extension.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

def registerExtension(self, extension):
    """This gets called by the extension."""
    self.registeredExtensions.append(extension)
    return self

reset()

Resets all state variables so that we can start with a new text.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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

set_output_format(format)

Set the output format for the class instance.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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

convert(source)

Convert markdown to serialized XHTML or HTML.

Parameters:

Name	Type	Description	Default
source	str	Source text as a Unicode string.	required

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.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

def convert(self, source):
    """Convert markdown to serialized XHTML or HTML.

    Args:
        source (str): 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 = unicode(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()

convertFile(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.)

Parameters:

Name	Type	Description	Default
input	str | None	File object or path. Reads from stdin if None.	None
output	str | None	File object or path. Writes to stdout if None.	None
encoding	str	Encoding of input and output files. Defaults to utf-8.	None

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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.)

    Args:
        input (str | None): File object or path. Reads from stdin if `None`.
        output (str | None): File object or path. Writes to stdout if `None`.
        encoding (str): 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

Functions

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.

Parameters:

Name	Type	Description	Default
text	str	Markdown formatted text as Unicode or ASCII string.	required
*args	Any	Any arguments accepted by the Markdown class.	()
**kwargs	Any	Any arguments accepted by the Markdown class.	{}

Returns:

Type	Description
str	An HTML document as a string.

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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.

    Args:
        text (str): Markdown formatted text as Unicode or ASCII string.
        *args (Any): Any arguments accepted by the Markdown class.
        **kwargs (Any): Any arguments accepted by the Markdown class.

    Returns:
        (str): An HTML document as a string.

    """
    md = Markdown(*args, **kwargs)
    return md.convert(text)

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.

Parameters:

Name	Type	Description	Default
*args	Any	Any arguments accepted by the Markdown class. input (str): a file name or readable object. output (str): a file name or writable object. encoding (str): Encoding of input and output.	()
**kwargs	Any	Any arguments accepted by the Markdown class.	{}

Source code in pyrevitlib/pyrevit/coreutils/markdown/__init__.py

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.

    Args:
        *args (Any): Any arguments accepted by the Markdown class.
            input (str): a file name or readable object.
            output (str): a file name or writable object.
            encoding (str): Encoding of input and output.
        **kwargs (Any): 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))