refactor: Setup a more robust Markdown converter

src/markdown_exec/python.py

@@ -7,7 +7,7 @@
 from markdown.core import Markdown
 from markupsafe import Markup
 
-from markdown_exec.markdown_helpers import code_block, tabbed
+from markdown_exec.rendering import code_block, markdown, tabbed
 
 md_copy = None
 
@@ -63,10 +63,8 @@ def exec_python( # noqa: WPS231
  Returns:
  HTML contents.
  """
- global md_copy # noqa: WPS420
- if md_copy is None:
- md_copy = Markdown() # noqa: WPS442
- md_copy.registerExtensions(md.registeredExtensions, {})
+ markdown.mimic(md)
+
  if isolate:
  exec_source = f"def _function():\n{indent(source, prefix=' ' * 4)}\n_function()\n"
  else:
@@ -90,4 +88,4 @@ def exec_python( # noqa: WPS231
  output = tabbed(("Source", source_block), ("Result", output))
  elif show_source == "tabbed-right":
  output = tabbed(("Result", output), ("Source", source_block))
- return Markup(md_copy.convert(output))
+ return markdown.convert(output)

src/markdown_exec/rendering.py

@@ -0,0 +1,119 @@
+"""Markdown extensions and helpers."""
+
+from __future__ import annotations
+
+from textwrap import indent
+from xml.etree.ElementTree import Element
+
+from markdown import Markdown
+from markdown.treeprocessors import Treeprocessor
+from markupsafe import Markup
+
+
+def code_block(language: str, code: str, **options: str) -> str:
+ """Format code as a code block.
+
+ Parameters:
+ language: The code block language.
+ code: The source code to format.
+ **options: Additional options passed from the source, to add back to the generated code block.
+
+ Returns:
+ The formatted code block.
+ """
+ opts = " ".join(f'{opt_name}="{opt_value}"' for opt_name, opt_value in options.items())
+ return f"```{language} {opts}\n{code}\n```"
+
+
+def tabbed(*tabs: tuple[str, str]) -> str:
+ """Format tabs using `pymdownx.tabbed` extension.
+
+ Parameters:
+ *tabs: Tuples of strings: title and text.
+
+ Returns:
+ The formatted tabs.
+ """
+ parts = []
+ for title, text in tabs:
+ title = title.replace("\\|", "|").strip()
+ parts.append(f'=== "{title}"')
+ parts.append(indent(text, prefix=" " * 4))
+ parts.append("")
+ return "\n".join(parts)
+
+
+# code taken from mkdocstrings, credits to @oprypin
+class _IdPrependingTreeprocessor(Treeprocessor):
+ """Prepend the configured prefix to IDs of all HTML elements."""
+
+ name = "markdown_exec_ids"
+
+ def __init__(self, md: Markdown, id_prefix: str): # noqa: D107
+ super().__init__(md)
+ self.id_prefix = id_prefix
+
+ def run(self, root: Element): # noqa: D102,WPS231
+ if not self.id_prefix:
+ return
+ for el in root.iter():
+ id_attr = el.get("id")
+ if id_attr:
+ el.set("id", self.id_prefix + id_attr)
+
+ href_attr = el.get("href")
+ if href_attr and href_attr.startswith("#"):
+ el.set("href", "#" + self.id_prefix + href_attr[1:])
+
+ name_attr = el.get("name")
+ if name_attr:
+ el.set("name", self.id_prefix + name_attr)
+
+ if el.tag == "label":
+ for_attr = el.get("for")
+ if for_attr:
+ el.set("for", self.id_prefix + for_attr)
+
+
+class _MarkdownConverter:
+ """Helper class to avoid breaking the original Markdown instance state."""
+
+ def __init__(self) -> None: # noqa: D107
+ self.md: Markdown = None
+ self.counter: int = 0
+
+ def mimic(self, md: Markdown) -> None:
+ """Mimic the passed Markdown instance by registering the same extensions.
+
+ Parameters:
+ md: A Markdown instance.
+ """
+ if self.md is None:
+ self.md = Markdown() # noqa: WPS442
+ self.md.registerExtensions(md.registeredExtensions + ["pymdownx.extra"], {})
+ self.md.treeprocessors.register(
+ _IdPrependingTreeprocessor(md, ""),
+ _IdPrependingTreeprocessor.name,
+ priority=4, # right after 'toc' (needed because that extension adds ids to headers)
+ )
+
+ def convert(self, text: str) -> Markup:
+ """Convert Markdown text to safe HTML.
+
+ Parameters:
+ text: Markdown text.
+
+ Returns:
+ Safe HTML.
+ """
+ self.md.treeprocessors[_IdPrependingTreeprocessor.name].id_prefix = f"exec-{self.counter}--"
+ self.counter += 1
+
+ try: # noqa: WPS501
+ return Markup(self.md.convert(text))
+ finally:
+ self.md.treeprocessors[_IdPrependingTreeprocessor.name].id_prefix = ""
+
+
+# provide a singleton
+markdown = _MarkdownConverter()