markdown-exec 1.10.1__py3-none-any.whl → 1.10.3__py3-none-any.whl

markdown_exec/_internal/formatters/python.py

@@ -0,0 +1,85 @@
+# Formatter for executing Python code.
+
+from __future__ import annotations
+
+import re
+import sys
+import traceback
+from collections import defaultdict
+from functools import partial
+from io import StringIO
+from types import ModuleType
+from typing import Any
+
+from markdown_exec._internal.formatters._exec_python import exec_python
+from markdown_exec._internal.formatters.base import ExecutionError, base_format
+from markdown_exec._internal.rendering import code_block
+
+_sessions_globals: dict[str, dict] = defaultdict(dict)
+_sessions_counter: dict[str | None, int] = defaultdict(int)
+_code_blocks: dict[str, list[str]] = {}
+
+
+def _buffer_print(buffer: StringIO, *texts: str, end: str = "\n", **kwargs: Any) -> None:  # noqa: ARG001
+    buffer.write(" ".join(str(text) for text in texts) + end)
+
+
+def _code_block_id(
+    id: str | None = None,  # noqa: A002
+    session: str | None = None,
+    title: str | None = None,
+) -> str:
+    _sessions_counter[session] += 1
+    if id:
+        code_block_id = f"id {id}"
+    elif session:
+        code_block_id = f"session {session}; n{_sessions_counter[session]}"
+        if title:
+            code_block_id = f"{code_block_id}; title {title}"
+    else:
+        code_block_id = f"n{_sessions_counter[session]}"
+        if title:
+            code_block_id = f"{code_block_id}; title {title}"
+    return f"<code block: {code_block_id}>"
+
+
+def _run_python(
+    code: str,
+    returncode: int | None = None,  # noqa: ARG001
+    session: str | None = None,
+    id: str | None = None,  # noqa: A002
+    **extra: str,
+) -> str:
+    title = extra.get("title")
+    code_block_id = _code_block_id(id, session, title)
+    _code_blocks[code_block_id] = code.split("\n")
+    exec_globals = _sessions_globals[session] if session else {}
+
+    # Other libraries expect functions to have a valid `__module__` attribute.
+    # To achieve this, we need to add a `__name__` attribute to the globals.
+    # We compute the name from the code block ID, replacing invalid characters with `_`.
+    # We also create a module object with the same name and add it to `sys.modules`,
+    # because that's what yet other libraries expect (`dataclasses` for example).
+    module_name = re.sub(r"[^a-zA-Z\d]+", "_", code_block_id)
+    exec_globals["__name__"] = module_name
+    sys.modules[module_name] = ModuleType(module_name)
+
+    buffer = StringIO()
+    exec_globals["print"] = partial(_buffer_print, buffer)
+
+    try:
+        exec_python(code, code_block_id, exec_globals)
+    except Exception as error:
+        trace = traceback.TracebackException.from_exception(error)
+        for frame in trace.stack:
+            if frame.filename.startswith("<code block: "):
+                if sys.version_info >= (3, 13):
+                    frame._lines = _code_blocks[frame.filename][frame.lineno - 1]  # type: ignore[attr-defined,operator]
+                else:
+                    frame._line = _code_blocks[frame.filename][frame.lineno - 1]  # type: ignore[attr-defined,operator]
+        raise ExecutionError(code_block("python", "".join(trace.format()), **extra)) from error
+    return buffer.getvalue()
+
+
+def _format_python(**kwargs: Any) -> str:
+    return base_format(language="python", run=_run_python, **kwargs)

markdown_exec/_internal/formatters/sh.py

@@ -0,0 +1,32 @@
+# Formatter for executing shell code.
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+from markdown_exec._internal.formatters.base import ExecutionError, base_format
+from markdown_exec._internal.rendering import code_block
+
+
+def _run_sh(
+    code: str,
+    returncode: int | None = None,
+    session: str | None = None,  # noqa: ARG001
+    id: str | None = None,  # noqa: A002,ARG001
+    **extra: str,
+) -> str:
+    process = subprocess.run(  # noqa: S603
+        ["sh", "-c", code],  # noqa: S607
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        check=False,
+    )
+    if process.returncode != returncode:
+        raise ExecutionError(code_block("sh", process.stdout, **extra), process.returncode)
+    return process.stdout
+
+
+def _format_sh(**kwargs: Any) -> str:
+    return base_format(language="sh", run=_run_sh, **kwargs)

markdown_exec/_internal/formatters/tree.py

@@ -0,0 +1,60 @@
+# Formatter for file-system trees.
+
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any
+
+from markdown_exec._internal.rendering import MarkdownConverter, code_block
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+
+
+def _rec_build_tree(lines: list[str], parent: list, offset: int, base_indent: int) -> int:
+    while offset < len(lines):
+        line = lines[offset]
+        lstripped = line.lstrip()
+        indent = len(line) - len(lstripped)
+        if indent == base_indent:
+            parent.append((lstripped, []))
+            offset += 1
+        elif indent > base_indent:
+            offset = _rec_build_tree(lines, parent[-1][1], offset, indent)
+        else:
+            return offset
+    return offset
+
+
+def _build_tree(code: str) -> list[tuple[str, list]]:
+    lines = dedent(code.strip()).split("\n")
+    root_layer: list[tuple[str, list]] = []
+    _rec_build_tree(lines, root_layer, 0, 0)
+    return root_layer
+
+
+def _rec_format_tree(tree: list[tuple[str, list]], *, root: bool = True) -> list[str]:
+    lines = []
+    n_items = len(tree)
+    for index, node in enumerate(tree):
+        last = index == n_items - 1
+        prefix = "" if root else f"{'└' if last else '├'}── "
+        if node[1]:
+            lines.append(f"{prefix}📁 {node[0]}")
+            sublines = _rec_format_tree(node[1], root=False)
+            if root:
+                lines.extend(sublines)
+            else:
+                indent_char = " " if last else "│"
+                lines.extend([f"{indent_char}   {line}" for line in sublines])
+        else:
+            name = node[0].split()[0]
+            icon = "📁" if name.endswith("/") else "📄"
+            lines.append(f"{prefix}{icon} {node[0]}")
+    return lines
+
+
+def _format_tree(code: str, md: Markdown, result: str, **options: Any) -> str:
+    markdown = MarkdownConverter(md)
+    output = "\n".join(_rec_format_tree(_build_tree(code)))
+    return markdown.convert(code_block(result or "bash", output, **options.get("extra", {})))

markdown_exec/_internal/logger.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, ClassVar
+
+
+class _Logger:
+    _default_logger: Any = logging.getLogger
+    _instances: ClassVar[dict[str, _Logger]] = {}
+
+    # See same code in Griffe project.
+    def __init__(self, name: str) -> None:
+        # Default logger that can be patched by third-party.
+        self._logger = self.__class__._default_logger(name)
+
+    def __getattr__(self, name: str) -> Any:
+        # Forward everything to the logger.
+        return getattr(self._logger, name)
+
+    @classmethod
+    def get(cls, name: str) -> _Logger:
+        """Get a logger instance.
+
+        Parameters:
+            name: The logger name.
+
+        Returns:
+            The logger instance.
+        """
+        if name not in cls._instances:
+            cls._instances[name] = cls(name)
+        return cls._instances[name]
+
+    @classmethod
+    def _patch_loggers(cls, get_logger_func: Callable) -> None:
+        # Patch current instances.
+        for name, instance in cls._instances.items():
+            instance._logger = get_logger_func(name)
+        # Future instances will be patched as well.
+        cls._default_logger = get_logger_func
+
+
+def get_logger(name: str) -> _Logger:
+    """Create and return a new logger instance.
+
+    Parameters:
+        name: The logger name.
+
+    Returns:
+        The logger.
+    """
+    return _Logger.get(name)
+
+
+def patch_loggers(get_logger_func: Callable[[str], Any]) -> None:
+    """Patch loggers.
+
+    We provide the `patch_loggers`function so dependant libraries
+    can patch loggers as they see fit.
+
+    For example, to fit in the MkDocs logging configuration
+    and prefix each log message with the module name:
+
+    ```python
+    import logging
+    from markdown_exec.logger import patch_loggers
+
+
+    class LoggerAdapter(logging.LoggerAdapter):
+        def __init__(self, prefix, logger):
+            super().__init__(logger, {})
+            self.prefix = prefix
+
+        def process(self, msg, kwargs):
+            return f"{self.prefix}: {msg}", kwargs
+
+
+    def get_logger(name):
+        logger = logging.getLogger(f"mkdocs.plugins.{name}")
+        return LoggerAdapter(name.split(".", 1)[0], logger)
+
+
+    patch_loggers(get_logger)
+    ```
+
+    Parameters:
+        get_logger_func: A function accepting a name as parameter and returning a logger.
+    """
+    _Logger._patch_loggers(get_logger_func)

markdown_exec/_internal/main.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+
+from markdown_exec._internal.formatters.base import default_tabs
+from markdown_exec._internal.formatters.bash import _format_bash
+from markdown_exec._internal.formatters.console import _format_console
+from markdown_exec._internal.formatters.markdown import _format_markdown
+from markdown_exec._internal.formatters.pycon import _format_pycon
+from markdown_exec._internal.formatters.pyodide import _format_pyodide
+from markdown_exec._internal.formatters.python import _format_python
+from markdown_exec._internal.formatters.sh import _format_sh
+from markdown_exec._internal.formatters.tree import _format_tree
+
+MARKDOWN_EXEC_AUTO = [lang.strip() for lang in os.getenv("MARKDOWN_EXEC_AUTO", "").split(",")]
+"""Languages to automatically execute."""
+
+formatters = {
+    "bash": _format_bash,
+    "console": _format_console,
+    "md": _format_markdown,
+    "markdown": _format_markdown,
+    "py": _format_python,
+    "python": _format_python,
+    "pycon": _format_pycon,
+    "pyodide": _format_pyodide,
+    "sh": _format_sh,
+    "tree": _format_tree,
+}
+"""Formatters for each language."""
+
+# negative look behind: matches only if | (pipe) if not preceded by \ (backslash)
+_tabs_re = re.compile(r"(?<!\\)\|")
+
+
+def validator(
+    language: str,
+    inputs: dict[str, str],
+    options: dict[str, Any],
+    attrs: dict[str, Any],  # noqa: ARG001
+    md: Markdown,  # noqa: ARG001
+) -> bool:
+    """Validate code blocks inputs.
+
+    Parameters:
+        language: The code language, like python or bash.
+        inputs: The code block inputs, to be sorted into options and attrs.
+        options: The container for options.
+        attrs: The container for attrs:
+        md: The Markdown instance.
+
+    Returns:
+        Success or not.
+    """
+    exec_value = language in MARKDOWN_EXEC_AUTO or _to_bool(inputs.pop("exec", "no"))
+    if language not in {"tree", "pyodide"} and not exec_value:
+        return False
+    id_value = inputs.pop("id", "")
+    id_prefix_value = inputs.pop("idprefix", None)
+    html_value = _to_bool(inputs.pop("html", "no"))
+    source_value = inputs.pop("source", "")
+    result_value = inputs.pop("result", "")
+    returncode_value = int(inputs.pop("returncode", "0"))
+    session_value = inputs.pop("session", "")
+    update_toc_value = _to_bool(inputs.pop("updatetoc", "yes"))
+    tabs_value = inputs.pop("tabs", "|".join(default_tabs))
+    tabs = tuple(_tabs_re.split(tabs_value, maxsplit=1))
+    workdir_value = inputs.pop("workdir", None)
+    width_value = int(inputs.pop("width", "0"))
+    options["id"] = id_value
+    options["id_prefix"] = id_prefix_value
+    options["html"] = html_value
+    options["source"] = source_value
+    options["result"] = result_value
+    options["returncode"] = returncode_value
+    options["session"] = session_value
+    options["update_toc"] = update_toc_value
+    options["tabs"] = tabs
+    options["workdir"] = workdir_value
+    options["width"] = width_value
+    options["extra"] = inputs
+    return True
+
+
+def formatter(
+    source: str,
+    language: str,
+    css_class: str,  # noqa: ARG001
+    options: dict[str, Any],
+    md: Markdown,
+    classes: list[str] | None = None,  # noqa: ARG001
+    id_value: str = "",  # noqa: ARG001
+    attrs: dict[str, Any] | None = None,  # noqa: ARG001
+    **kwargs: Any,  # noqa: ARG001
+) -> str:
+    """Execute code and return HTML.
+
+    Parameters:
+        source: The code to execute.
+        language: The code language, like python or bash.
+        css_class: The CSS class to add to the HTML element.
+        options: The container for options.
+        attrs: The container for attrs:
+        md: The Markdown instance.
+        classes: Additional CSS classes.
+        id_value: An optional HTML id.
+        attrs: Additional attributes
+        **kwargs: Additional arguments passed to SuperFences default formatters.
+
+    Returns:
+        HTML contents.
+    """
+    fmt = formatters.get(language, lambda source, **kwargs: source)
+    return fmt(code=source, md=md, **options)  # type: ignore[operator]
+
+
+def _to_bool(value: str) -> bool:
+    return value.lower() not in {"", "no", "off", "false", "0"}

markdown_exec/_internal/mkdocs_plugin.py

@@ -0,0 +1,143 @@
+# This module contains an optional plugin for MkDocs.
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from mkdocs.config import config_options
+from mkdocs.config.base import Config
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin
+from mkdocs.utils import write_file
+
+from markdown_exec._internal.logger import patch_loggers
+from markdown_exec._internal.main import formatter, formatters, validator
+from markdown_exec._internal.rendering import MarkdownConverter, markdown_config
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from jinja2 import Environment
+    from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.files import Files
+
+try:
+    __import__("pygments_ansi_color")
+except ImportError:
+    _ansi_ok = False
+else:
+    _ansi_ok = True
+
+
+class _LoggerAdapter(logging.LoggerAdapter):
+    def __init__(self, prefix: str, logger: logging.Logger) -> None:
+        super().__init__(logger, {})
+        self.prefix = prefix
+
+    def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, MutableMapping[str, Any]]:
+        return f"{self.prefix}: {msg}", kwargs
+
+
+def _get_logger(name: str) -> _LoggerAdapter:
+    logger = logging.getLogger(f"mkdocs.plugins.{name}")
+    return _LoggerAdapter(name.split(".", 1)[0], logger)
+
+
+patch_loggers(_get_logger)
+
+
+class MarkdownExecPluginConfig(Config):
+    """Configuration of the plugin (for `mkdocs.yml`)."""
+
+    ansi = config_options.Choice(("auto", "off", "required", True, False), default="auto")
+    """Whether the `ansi` extra is required when installing the package."""
+    languages = config_options.ListOfItems(
+        config_options.Choice(formatters.keys()),
+        default=list(formatters.keys()),
+    )
+    """Which languages to enabled the extension for."""
+
+
+class MarkdownExecPlugin(BasePlugin[MarkdownExecPluginConfig]):
+    """MkDocs plugin to easily enable custom fences for code blocks execution."""
+
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
+        """Configure the plugin.
+
+        Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
+        In this hook, we add custom fences for all the supported languages.
+
+        We also save the Markdown extensions configuration
+        into [`markdown_config`][markdown_exec.markdown_config].
+
+        Arguments:
+            config: The MkDocs config object.
+
+        Returns:
+            The modified config.
+        """
+        if "pymdownx.superfences" not in config["markdown_extensions"]:
+            message = "The 'markdown-exec' plugin requires the 'pymdownx.superfences' Markdown extension to work."
+            raise PluginError(message)
+        if self.config.ansi in ("required", True) and not _ansi_ok:
+            raise PluginError(
+                "The configuration for the 'markdown-exec' plugin requires "
+                "that it is installed with the 'ansi' extra. "
+                "Install it with 'pip install markdown-exec[ansi]'.",
+            )
+        self.mkdocs_config_dir = os.getenv("MKDOCS_CONFIG_DIR")
+        os.environ["MKDOCS_CONFIG_DIR"] = os.path.dirname(config["config_file_path"])
+        self.languages = self.config.languages
+        mdx_configs = config.setdefault("mdx_configs", {})
+        superfences = mdx_configs.setdefault("pymdownx.superfences", {})
+        custom_fences = superfences.setdefault("custom_fences", [])
+        for language in self.languages:
+            custom_fences.append(
+                {
+                    "name": language,
+                    "class": language,
+                    "validator": validator,
+                    "format": formatter,
+                },
+            )
+        markdown_config.save(config.markdown_extensions, config.mdx_configs)
+        return config
+
+    def on_env(
+        self,
+        env: Environment,
+        *,
+        config: MkDocsConfig,
+        files: Files,  # noqa: ARG002
+    ) -> Environment | None:
+        """Add assets to the environment."""
+        if self.config.ansi in ("required", True) or (self.config.ansi == "auto" and _ansi_ok):
+            self._add_css(config, "ansi.css")
+        if "pyodide" in self.languages:
+            self._add_css(config, "pyodide.css")
+            self._add_js(config, "pyodide.js")
+        return env
+
+    def on_post_build(self, *, config: MkDocsConfig) -> None:  # noqa: ARG002
+        """Reset the plugin state."""
+        MarkdownConverter.counter = 0
+        markdown_config.reset()
+        if self.mkdocs_config_dir is None:
+            os.environ.pop("MKDOCS_CONFIG_DIR", None)
+        else:
+            os.environ["MKDOCS_CONFIG_DIR"] = self.mkdocs_config_dir
+
+    def _add_asset(self, config: MkDocsConfig, asset_file: str, asset_type: str) -> None:
+        asset_filename = f"assets/_markdown_exec_{asset_file}"
+        asset_content = Path(__file__).parent.parent.joinpath("assets", asset_file).read_text()
+        write_file(asset_content.encode("utf-8"), os.path.join(config.site_dir, asset_filename))
+        config[f"extra_{asset_type}"].insert(0, asset_filename)
+
+    def _add_css(self, config: MkDocsConfig, css_file: str) -> None:
+        self._add_asset(config, css_file, "css")
+
+    def _add_js(self, config: MkDocsConfig, js_file: str) -> None:
+        self._add_asset(config, js_file, "javascript")

markdown_exec/_internal/processors.py

@@ -0,0 +1,136 @@
+# This module contains a Markdown extension
+# allowing to integrate generated headings into the ToC.
+
+from __future__ import annotations
+
+import copy
+import re
+from typing import TYPE_CHECKING
+from xml.etree.ElementTree import Element
+
+from markdown.treeprocessors import Treeprocessor
+from markdown.util import HTML_PLACEHOLDER_RE
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+    from markupsafe import Markup
+
+
+# code taken from mkdocstrings, credits to @oprypin
+class IdPrependingTreeprocessor(Treeprocessor):
+    """Prepend the configured prefix to IDs of all HTML elements."""
+
+    name = "markdown_exec_ids"
+    """The name of the treeprocessor."""
+
+    def __init__(self, md: Markdown, id_prefix: str) -> None:
+        super().__init__(md)
+        self.id_prefix = id_prefix
+        """The prefix to prepend to IDs."""
+
+    def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
+        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)
+
+
+# code taken from mkdocstrings, credits to @oprypin
+class HeadingReportingTreeprocessor(Treeprocessor):
+    """Records the heading elements encountered in the document."""
+
+    name = "markdown_exec_record_headings"
+    """The name of the treeprocessor."""
+    regex = re.compile("[Hh][1-6]")
+    """The regex to match heading tags."""
+
+    def __init__(self, md: Markdown, headings: list[Element]):
+        super().__init__(md)
+        self.headings = headings
+        """The list of heading elements."""
+
+    def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
+        for el in root.iter():
+            if self.regex.fullmatch(el.tag):
+                el = copy.copy(el)  # noqa: PLW2901
+                # 'toc' extension's first pass (which we require to build heading stubs/ids) also edits the HTML.
+                # Undo the permalink edit so we can pass this heading to the outer pass of the 'toc' extension.
+                if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class:  # type: ignore[attr-defined]
+                    del el[-1]
+                self.headings.append(el)
+
+
+class InsertHeadings(Treeprocessor):
+    """Our headings insertor."""
+
+    name = "markdown_exec_insert_headings"
+    """The name of the treeprocessor."""
+
+    def __init__(self, md: Markdown):
+        """Initialize the object.
+
+        Arguments:
+            md: A `markdown.Markdown` instance.
+        """
+        super().__init__(md)
+        self.headings: dict[Markup, list[Element]] = {}
+        """The dictionary of headings."""
+
+    def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
+        if not self.headings:
+            return
+
+        for el in root.iter():
+            match = HTML_PLACEHOLDER_RE.match(el.text or "")
+            if match:
+                counter = int(match.group(1))
+                markup: Markup = self.md.htmlStash.rawHtmlBlocks[counter]  # type: ignore[assignment]
+                if headings := self.headings.get(markup):
+                    div = Element("div", {"class": "markdown-exec"})
+                    div.extend(headings)
+                    el.append(div)
+
+
+class RemoveHeadings(Treeprocessor):
+    """Our headings remover."""
+
+    name = "markdown_exec_remove_headings"
+    """The name of the treeprocessor."""
+
+    def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
+        self._remove_duplicated_headings(root)
+
+    def _remove_duplicated_headings(self, parent: Element) -> None:
+        carry_text = ""
+        for el in reversed(parent):  # Reversed mainly for the ability to mutate during iteration.
+            if el.tag == "div" and el.get("class") == "markdown-exec":
+                # Delete the duplicated headings along with their container, but keep the text (i.e. the actual HTML).
+                carry_text = (el.text or "") + carry_text
+                parent.remove(el)
+            else:
+                if carry_text:
+                    el.tail = (el.tail or "") + carry_text
+                    carry_text = ""
+                self._remove_duplicated_headings(el)
+
+        if carry_text:
+            parent.text = (parent.text or "") + carry_text