# ‹› `` `markdown.util`

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

Classes:

- `AtomicString` –

  A string which should not be further processed.

- `Processor` –

  The base class for all processors.

- `HtmlStash` –

  This class is used for stashing HTML objects that we extract

- `Registry` –

  A priority sorted registry.

Functions:

- `get_installed_extensions` –

  Return all entry_points in the `markdown.extensions` group.

- `deprecated` –

  Raise a `DeprecationWarning` when wrapped function/method is called.

- `parseBoolValue` –

  Parses a string representing a boolean value. If parsing was successful,

- `code_escape` –

  HTML escape a string of code.

- `nearing_recursion_limit` –

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

Attributes:

- `BLOCK_LEVEL_ELEMENTS` (`list[str]`) –

  List of HTML tags which get treated as block-level elements. Same as the `block_level_elements`

- `STX` –

  “Start of Text” marker for placeholder templates.

- `ETX` –

  “End of Text” marker for placeholder templates.

- `INLINE_PLACEHOLDER_PREFIX` –

  Prefix for inline placeholder template.

- `INLINE_PLACEHOLDER` –

  Placeholder template for stashed inline text.

- `INLINE_PLACEHOLDER_RE` –

  Regular Expression which matches inline placeholders.

- `AMP_SUBSTITUTE` –

  Placeholder template for HTML entities.

- `HTML_PLACEHOLDER` –

  Placeholder template for raw HTML.

- `HTML_PLACEHOLDER_RE` –

  Regular expression which matches HTML placeholders.

- `TAG_PLACEHOLDER` –

  Placeholder template for tags.

## ‹› `` `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',
        'center'
    ]

## ‹› `` `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.

Methods:

- `store` –

  Saves an HTML segment for later reinsertion. Returns a

- `reset` –

  Clear the stash.

- `store_tag` –

  Store tag data and return a placeholder.

### ‹› `` `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”.

Methods:

- `get_index_for_name` –

  Return the index of the given name.

- `register` –

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

- `deregister` –

  Remove an item from the registry.

### ‹› `` `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`.