‹› markdown.util

This module contains various contacts, classes and functions which get referenced and used throughout the code base.

‹› markdown.util.BLOCK_LEVEL_ELEMENTS: list[str] module-attribute

List of HTML tags which get treated as block-level elements. Same as the block_level_elements attribute of the Markdown class. Generally one should use the attribute on the class. This remains for compatibility with older extensions.

Defined Value:

BLOCK_LEVEL_ELEMENTS: list[str] = [
    # Elements which are invalid to wrap in a `<p>` tag.
    # See https://w3c.github.io/html/grouping-content.html#the-p-element
    'address', 'article', 'aside', 'blockquote', 'details', 'div', 'dl',
    'fieldset', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3',
    'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'main', 'menu', 'nav', 'ol',
    'p', 'pre', 'section', 'table', 'ul',
    # Other elements which Markdown should not be mucking up the contents of.
    'canvas', 'colgroup', 'dd', 'body', 'dt', 'group', 'html', 'iframe', 'li', 'legend',
    'math', 'map', 'noscript', 'output', 'object', 'option', 'progress', 'script',
    'style', 'summary', 'tbody', 'td', 'textarea', 'tfoot', 'th', 'thead', 'tr', 'video'
]

‹› markdown.util.STX module-attribute

“Start of Text” marker for placeholder templates.

Defined Value:

STX = '\u0002'

‹› markdown.util.ETX module-attribute

“End of Text” marker for placeholder templates.

Defined Value:

ETX = '\u0003'

‹› markdown.util.INLINE_PLACEHOLDER_PREFIX module-attribute

Prefix for inline placeholder template.

Defined Value:

INLINE_PLACEHOLDER_PREFIX = STX+"klzzwxh:"

‹› markdown.util.INLINE_PLACEHOLDER module-attribute

Placeholder template for stashed inline text.

Defined Value:

INLINE_PLACEHOLDER = INLINE_PLACEHOLDER_PREFIX + "%s" + ETX

‹› markdown.util.INLINE_PLACEHOLDER_RE module-attribute

Regular Expression which matches inline placeholders.

Defined Value:

INLINE_PLACEHOLDER_RE = re.compile(INLINE_PLACEHOLDER % r'([0-9]+)')

‹› markdown.util.AMP_SUBSTITUTE module-attribute

Placeholder template for HTML entities.

Defined Value:

AMP_SUBSTITUTE = STX+"amp"+ETX

‹› markdown.util.HTML_PLACEHOLDER module-attribute

Placeholder template for raw HTML.

Defined Value:

HTML_PLACEHOLDER = STX + "wzxhzdk:%s" + ETX

‹› markdown.util.HTML_PLACEHOLDER_RE module-attribute

Regular expression which matches HTML placeholders.

Defined Value:

HTML_PLACEHOLDER_RE = re.compile(HTML_PLACEHOLDER % r'([0-9]+)')

‹› markdown.util.TAG_PLACEHOLDER module-attribute

Placeholder template for tags.

Defined Value:

TAG_PLACEHOLDER = STX + "hzzhzkh:%s" + ETX

‹› markdown.util.get_installed_extensions() cached

Return all entry_points in the markdown.extensions group.

‹› markdown.util.deprecated(message: str, stacklevel: int = 2)

Raise a DeprecationWarning when wrapped function/method is called.

Usage:

@deprecated("This method will be removed in version X; use Y instead.")
def some_method():
    pass

‹› markdown.util.parseBoolValue(value: str | None, fail_on_errors: bool = True, preserve_none: bool = False) -> bool | None

Parses a string representing a boolean value. If parsing was successful, returns True or False. If preserve_none=True, returns True, False, or None. If parsing was not successful, raises ValueError, or, if fail_on_errors=False, returns None.

‹› markdown.util.code_escape(text: str) -> str

HTML escape a string of code.

‹› markdown.util.nearing_recursion_limit() -> bool

Return true if current stack depth is within 100 of maximum limit.

‹› markdown.util.AtomicString

Bases: str

A string which should not be further processed.

‹› markdown.util.Processor(md: Markdown | None = None)

The base class for all processors.

Attributes:

  • Processor.md –

    The Markdown instance passed in an initialization.

Parameters:

  • md (Markdown | None, default: None ) –

    The Markdown instance this processor is a part of.

‹› markdown.util.HtmlStash()

This class is used for stashing HTML objects that we extract in the beginning and replace with place-holders.

‹› markdown.util.HtmlStash.store(html: str | etree.Element) -> str

Saves an HTML segment for later reinsertion. Returns a placeholder string that needs to be inserted into the document.

Other Parameters:

  • html (str | Element) –

    An html segment.

Returns:

  • str –

    A placeholder string.

‹› markdown.util.HtmlStash.reset() -> None

Clear the stash.

‹› markdown.util.HtmlStash.store_tag(tag: str, attrs: dict[str, str], left_index: int, right_index: int) -> str

Store tag data and return a placeholder.

‹› markdown.util.Registry()

Bases: Generic[_T]

A priority sorted registry.

A Registry instance provides two public methods to alter the data of the registry: register and deregister. Use register to add items and deregister to remove items. See each method for specifics.

When registering an item, a “name” and a “priority” must be provided. All items are automatically sorted by “priority” from highest to lowest. The “name” is used to remove (“deregister”) and get items.

A Registry instance it like a list (which maintains order) when reading data. You may iterate over the items, get an item and get a count (length) of all items. You may also check that the registry contains an item.

When getting an item you may use either the index of the item or the string-based “name”. For example:

registry = Registry()
registry.register(SomeItem(), 'itemname', 20)
# Get the item by index
item = registry[0]
# Get the item by name
item = registry['itemname']

When checking that the registry contains an item, you may use either the string-based “name”, or a reference to the actual item. For example:

someitem = SomeItem()
registry.register(someitem, 'itemname', 20)
# Contains the name
assert 'itemname' in registry
# Contains the item instance
assert someitem in registry

The method get_index_for_name is also available to obtain the index of an item using that item’s assigned “name”.

‹› markdown.util.Registry.get_index_for_name(name: str) -> int

Return the index of the given name.

‹› markdown.util.Registry.register(item: _T, name: str, priority: float) -> None

Add an item to the registry with the given name and priority.

Parameters:

  • item (_T) –

    The item being registered.

  • name (str) –

    A string used to reference the item.

  • priority (float) –

    An integer or float used to sort against all items.

If an item is registered with a “name” which already exists, the existing item is replaced with the new item. Treat carefully as the old item is lost with no way to recover it. The new item will be sorted according to its priority and will not retain the position of the old item.

‹› markdown.util.Registry.deregister(name: str, strict: bool = True) -> None

Remove an item from the registry.

Set strict=False to fail silently. Otherwise a ValueError is raised for an unknown name.