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

markdown_exec/__init__.py

@@ -3,141 +3,53 @@
 Utilities to execute code blocks in Markdown files.
 """
 
-# https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences
-# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#snippets
-
-from __future__ import annotations
-
-import os
-import re
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from markdown import Markdown
-
-from markdown_exec.formatters.base import default_tabs
-from markdown_exec.formatters.bash import _format_bash
-from markdown_exec.formatters.console import _format_console
-from markdown_exec.formatters.markdown import _format_markdown
-from markdown_exec.formatters.pycon import _format_pycon
-from markdown_exec.formatters.pyodide import _format_pyodide
-from markdown_exec.formatters.python import _format_python
-from markdown_exec.formatters.sh import _format_sh
-from markdown_exec.formatters.tree import _format_tree
-
-__all__: list[str] = ["formatter", "validator"]
-
-MARKDOWN_EXEC_AUTO = [lang.strip() for lang in os.getenv("MARKDOWN_EXEC_AUTO", "").split(",")]
-
-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,
-}
-
-# 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]
-
-
-falsy_values = {"", "no", "off", "false", "0"}
-truthy_values = {"yes", "on", "true", "1"}
-
-
-def _to_bool(value: str) -> bool:
-    return value.lower() not in falsy_values
-
-
-def _to_bool_or_value(value: str) -> bool | str:
-    if value.lower() in falsy_values:
-        return False
-    if value.lower() in truthy_values:
-        return True
-    return value
+from markdown_exec._internal.formatters.base import (
+    ExecutionError,
+    base_format,
+    console_width,
+    default_tabs,
+    working_directory,
+)
+from markdown_exec._internal.logger import get_logger, patch_loggers
+from markdown_exec._internal.main import MARKDOWN_EXEC_AUTO, formatter, formatters, validator
+from markdown_exec._internal.mkdocs_plugin import MarkdownExecPlugin, MarkdownExecPluginConfig
+from markdown_exec._internal.processors import (
+    HeadingReportingTreeprocessor,
+    IdPrependingTreeprocessor,
+    InsertHeadings,
+    RemoveHeadings,
+)
+from markdown_exec._internal.rendering import (
+    MarkdownConfig,
+    MarkdownConverter,
+    add_source,
+    code_block,
+    markdown_config,
+    tabbed,
+)
+
+__all__ = [
+    "MARKDOWN_EXEC_AUTO",
+    "ExecutionError",
+    "HeadingReportingTreeprocessor",
+    "IdPrependingTreeprocessor",
+    "InsertHeadings",
+    "MarkdownConfig",
+    "MarkdownConverter",
+    "MarkdownExecPlugin",
+    "MarkdownExecPluginConfig",
+    "RemoveHeadings",
+    "add_source",
+    "base_format",
+    "code_block",
+    "console_width",
+    "default_tabs",
+    "formatter",
+    "formatters",
+    "get_logger",
+    "markdown_config",
+    "patch_loggers",
+    "tabbed",
+    "validator",
+    "working_directory",
+]

markdown_exec/{debug.py → _internal/debug.py}

@@ -1,5 +1,3 @@
-"""Debugging utilities."""
-
 from __future__ import annotations
 
 import os
@@ -10,7 +8,7 @@ from importlib import metadata
 
 
 @dataclass
-class Variable:
+class _Variable:
     """Dataclass describing an environment variable."""
 
     name: str
@@ -20,7 +18,7 @@ class Variable:
 
 
 @dataclass
-class Package:
+class _Package:
     """Dataclass describing a Python package."""
 
     name: str
@@ -30,7 +28,7 @@ class Package:
 
 
 @dataclass
-class Environment:
+class _Environment:
     """Dataclass to store environment information."""
 
     interpreter_name: str
@@ -41,9 +39,9 @@ class Environment:
     """Path to Python executable."""
     platform: str
     """Operating System."""
-    packages: list[Package]
+    packages: list[_Package]
     """Installed packages."""
-    variables: list[Variable]
+    variables: list[_Variable]
     """Environment variables."""
 
 
@@ -58,7 +56,7 @@ def _interpreter_name_version() -> tuple[str, str]:
     return "", "0.0.0"
 
 
-def get_version(dist: str = "markdown-exec") -> str:
+def _get_version(dist: str = "markdown-exec") -> str:
     """Get version of the given distribution.
 
     Parameters:
@@ -73,7 +71,7 @@ def get_version(dist: str = "markdown-exec") -> str:
         return "0.0.0"
 
 
-def get_debug_info() -> Environment:
+def _get_debug_info() -> _Environment:
     """Get debug/environment information.
 
     Returns:
@@ -82,19 +80,19 @@ def get_debug_info() -> Environment:
     py_name, py_version = _interpreter_name_version()
     packages = ["markdown-exec"]
     variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("MARKDOWN_EXEC")]]
-    return Environment(
+    return _Environment(
         interpreter_name=py_name,
         interpreter_version=py_version,
         interpreter_path=sys.executable,
         platform=platform.platform(),
-        variables=[Variable(var, val) for var in variables if (val := os.getenv(var))],
-        packages=[Package(pkg, get_version(pkg)) for pkg in packages],
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
     )
 
 
-def print_debug_info() -> None:
+def _print_debug_info() -> None:
     """Print debug/environment information."""
-    info = get_debug_info()
+    info = _get_debug_info()
     print(f"- __System__: {info.platform}")
     print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
     print("- __Environment variables__:")
@@ -106,4 +104,4 @@ def print_debug_info() -> None:
 
 
 if __name__ == "__main__":
-    print_debug_info()
+    _print_debug_info()

markdown_exec/_internal/formatters/__init__.py

@@ -0,0 +1 @@
+# This subpackage contains all the formatters.

markdown_exec/{formatters → _internal/formatters}/_exec_python.py

@@ -1,4 +1,4 @@
-"""Special module without future annotations for executing Python code."""
+# Special module without future annotations for executing Python code.
 
 from typing import Any, Optional
 

markdown_exec/_internal/formatters/base.py

@@ -0,0 +1,191 @@
+# Generic formatter for executing code.
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from textwrap import indent
+from typing import TYPE_CHECKING, Any, Callable
+from uuid import uuid4
+
+from markupsafe import Markup
+
+from markdown_exec._internal.logger import get_logger
+from markdown_exec._internal.rendering import MarkdownConverter, add_source, code_block
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from markdown.core import Markdown
+
+_logger = get_logger(__name__)
+
+default_tabs = ("Source", "Result")
+"""Default tab titles."""
+
+
+@contextmanager
+def working_directory(path: str | None = None) -> Iterator[None]:
+    """Change the working directory for the duration of the context.
+
+    Parameters:
+        path: The path to change the working directory to.
+    """
+    if path:
+        old_cwd = os.getcwd()
+        os.chdir(path)
+        try:
+            yield
+        finally:
+            os.chdir(old_cwd)
+    else:
+        yield
+
+
+@contextmanager
+def console_width(width: int | None = None) -> Iterator[None]:
+    """Set the console width for the duration of the context.
+
+    The console width is set using the `COLUMNS` environment variable.
+
+    Parameters:
+        width: The width to set the console to.
+    """
+    if width:
+        old_width = os.environ.get("COLUMNS", None)
+        os.environ["COLUMNS"] = str(width)
+        try:
+            yield
+        finally:
+            if old_width is None:
+                del os.environ["COLUMNS"]
+            else:
+                os.environ["COLUMNS"] = old_width
+    else:
+        yield
+
+
+class ExecutionError(Exception):
+    """Exception raised for errors during execution of a code block.
+
+    Attributes:
+        message: The exception message.
+        returncode: The code returned by the execution of the code block.
+    """
+
+    def __init__(self, message: str, returncode: int | None = None) -> None:
+        super().__init__(message)
+        self.returncode = returncode
+        """The code returned by the execution of the code block."""
+
+
+def _format_log_details(details: str, *, strip_fences: bool = False) -> str:
+    if strip_fences:
+        lines = details.split("\n")
+        if lines[0].startswith("```") and lines[-1].startswith("```"):
+            details = "\n".join(lines[1:-1])
+    return indent(details, " " * 2)
+
+
+def base_format(
+    *,
+    language: str,
+    run: Callable,
+    code: str,
+    md: Markdown,
+    html: bool = False,
+    source: str = "",
+    result: str = "",
+    tabs: tuple[str, str] = default_tabs,
+    id: str = "",  # noqa: A002
+    id_prefix: str | None = None,
+    returncode: int = 0,
+    transform_source: Callable[[str], tuple[str, str]] | None = None,
+    session: str | None = None,
+    update_toc: bool = True,
+    workdir: str | None = None,
+    width: int | None = None,
+    **options: Any,
+) -> Markup:
+    """Execute code and return HTML.
+
+    Parameters:
+        language: The code language.
+        run: Function that runs code and returns output.
+        code: The code to execute.
+        md: The Markdown instance.
+        html: Whether to inject output as HTML directly, without rendering.
+        source: Whether to show source as well, and where.
+        result: If provided, use as language to format result in a code block.
+        tabs: Titles of tabs (if used).
+        id: An optional ID for the code block (useful when warning about errors).
+        id_prefix: A string used to prefix HTML ids in the generated HTML.
+        returncode: The expected exit code.
+        transform_source: An optional callable that returns transformed versions of the source.
+            The input source is the one that is ran, the output source is the one that is
+            rendered (when the source option is enabled).
+        session: A session name, to persist state between executed code blocks.
+        update_toc: Whether to include generated headings
+            into the Markdown table of contents (toc extension).
+        workdir: The working directory to use for the execution.
+        **options: Additional options passed from the formatter.
+
+    Returns:
+        HTML contents.
+    """
+    markdown = MarkdownConverter(md, update_toc=update_toc)
+    extra = options.get("extra", {})
+
+    if transform_source:
+        source_input, source_output = transform_source(code)
+    else:
+        source_input = code
+        source_output = code
+
+    try:
+        with working_directory(workdir), console_width(width):
+            output = run(source_input, returncode=returncode, session=session, id=id, **extra)
+    except ExecutionError as error:
+        identifier = id or extra.get("title", "")
+        identifier = identifier and f"'{identifier}' "
+        exit_message = "errors" if error.returncode is None else f"unexpected code {error.returncode}"
+        log_message = (
+            f"Execution of {language} code block {identifier}exited with {exit_message}\n\n"
+            f"Code block is:\n\n{_format_log_details(source_input)}\n\n"
+            f"Output is:\n\n{_format_log_details(str(error), strip_fences=True)}\n"
+        )
+        _logger.warning(log_message)
+        return markdown.convert(str(error))
+
+    if not output and not source:
+        return Markup()
+
+    if html:
+        if source:
+            placeholder = f'<div class="{uuid4()}"></div>'
+            wrapped_output = add_source(
+                source=source_output,
+                location=source,
+                output=placeholder,
+                language=language,
+                tabs=tabs,
+                **extra,
+            )
+            return markdown.convert(wrapped_output, stash={placeholder: output})
+        return Markup(output)  # noqa: S704
+
+    wrapped_output = output
+    if result and source != "console":
+        wrapped_output = code_block(result, output)
+    if source:
+        wrapped_output = add_source(
+            source=source_output,
+            location=source,
+            output=wrapped_output,
+            language=language,
+            tabs=tabs,
+            result=result,
+            **extra,
+        )
+    prefix = id_prefix if id_prefix is not None else (f"{id}-" if id else None)
+    return markdown.convert(wrapped_output, id_prefix=prefix)

markdown_exec/_internal/formatters/bash.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_bash(
+    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
+        ["bash", "-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_bash(**kwargs: Any) -> str:
+    return base_format(language="bash", run=_run_bash, **kwargs)

markdown_exec/_internal/formatters/console.py

@@ -0,0 +1,29 @@
+# Formatter for executing shell console code.
+
+from __future__ import annotations
+
+import textwrap
+from typing import TYPE_CHECKING, Any
+
+from markdown_exec._internal.formatters.base import base_format
+from markdown_exec._internal.formatters.sh import _run_sh
+from markdown_exec._internal.logger import get_logger
+
+if TYPE_CHECKING:
+    from markupsafe import Markup
+
+_logger = get_logger(__name__)
+
+
+def _transform_source(code: str) -> tuple[str, str]:
+    sh_lines = []
+    for line in code.split("\n"):
+        prompt = line[:2]
+        if prompt in {"$ ", "% "}:
+            sh_lines.append(line[2:])
+    sh_code = "\n".join(sh_lines)
+    return sh_code, textwrap.indent(sh_code, prompt)
+
+
+def _format_console(**kwargs: Any) -> Markup:
+    return base_format(language="console", run=_run_sh, transform_source=_transform_source, **kwargs)

markdown_exec/_internal/formatters/markdown.py

@@ -0,0 +1,11 @@
+# Formatter for literate Markdown.
+
+from __future__ import annotations
+
+from typing import Any
+
+from markdown_exec._internal.formatters.base import base_format
+
+
+def _format_markdown(**kwargs: Any) -> str:
+    return base_format(language="md", run=lambda code, **_: code, **kwargs)

markdown_exec/_internal/formatters/pycon.py

@@ -0,0 +1,26 @@
+# Formatter for executing `pycon` code.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from markdown_exec._internal.formatters.base import base_format
+from markdown_exec._internal.formatters.python import _run_python
+
+if TYPE_CHECKING:
+    from markupsafe import Markup
+
+
+def _transform_source(code: str) -> tuple[str, str]:
+    python_lines = []
+    pycon_lines = []
+    for line in code.split("\n"):
+        if line.startswith((">>> ", "... ")):
+            pycon_lines.append(line)
+            python_lines.append(line[4:])
+    python_code = "\n".join(python_lines)
+    return python_code, "\n".join(pycon_lines)
+
+
+def _format_pycon(**kwargs: Any) -> Markup:
+    return base_format(language="pycon", run=_run_python, transform_source=_transform_source, **kwargs)

markdown_exec/_internal/formatters/pyodide.py

@@ -0,0 +1,73 @@
+# Formatter for creating a Pyodide interactive editor.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+
+# All Ace.js themes listed here:
+# https://github.com/ajaxorg/ace/tree/master/src/theme
+
+_play_emoji = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8 5.14v14l11-7-11-7Z"></path></svg>'
+)
+_clear_emoji = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.14 3c-.51 0-1.02.2-1.41.59L2.59 14.73c-.78.77-.78 2.04 0 2.83L5.03 20h7.66l8.72-8.73c.79-.77.79-2.04 0-2.83l-4.85-4.85c-.39-.39-.91-.59-1.42-.59M17 18l-2 2h7v-2"></path></svg>'
+
+_assets = """
+<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.16.0/ace.js"></script>
+<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
+<script type="text/javascript" src="https://cdn.jsdelivr.net/pyodide/v{version}/full/pyodide.js"></script>
+<link title="light" rel="alternate stylesheet" href="https://cdn.jsdelivr.net/npm/highlightjs-themes@1.0.0/tomorrow.min.css" disabled="disabled">
+<link title="dark" rel="alternate stylesheet" href="https://cdn.jsdelivr.net/npm/highlightjs-themes@1.0.0/tomorrow-night-blue.min.css" disabled="disabled">
+"""
+
+_template = """
+<div class="pyodide">
+<div class="pyodide-editor-bar">
+<span class="pyodide-bar-item">Editor (session: %(session)s)</span><span id="%(id_prefix)srun" title="Run: press Ctrl-Enter" class="pyodide-bar-item pyodide-clickable"><span class="twemoji">%(play_emoji)s</span> Run</span>
+</div>
+<div><pre id="%(id_prefix)seditor" class="pyodide-editor">%(initial_code)s</pre></div>
+<div class="pyodide-editor-bar">
+<span class="pyodide-bar-item">Output</span><span id="%(id_prefix)sclear" class="pyodide-bar-item pyodide-clickable"><span class="twemoji">%(clear_emoji)s</span> Clear</span>
+</div>
+<pre><code id="%(id_prefix)soutput" class="pyodide-output"></code></pre>
+</div>
+
+<script>
+document.addEventListener('DOMContentLoaded', (event) => {
+    setupPyodide('%(id_prefix)s', install=%(install)s, themeLight='%(theme_light)s', themeDark='%(theme_dark)s', session='%(session)s');
+});
+</script>
+"""
+
+_counter = 0
+
+
+def _format_pyodide(code: str, md: Markdown, session: str, extra: dict, **options: Any) -> str:  # noqa: ARG001
+    global _counter  # noqa: PLW0603
+    _counter += 1
+    version = extra.pop("version", "0.26.4").lstrip("v")
+    install = extra.pop("install", "")
+    install = install.split(",") if install else []
+    exclude_assets = extra.pop("assets", "1").lower() in {"0", "false", "no", "off"}
+    theme = extra.pop("theme", "tomorrow,tomorrow_night")
+    if "," not in theme:
+        theme = f"{theme},{theme}"
+    theme_light, theme_dark = theme.split(",")
+
+    data = {
+        "id_prefix": f"exec-{_counter}--",
+        "initial_code": code,
+        "install": install,
+        "theme_light": theme_light.strip(),
+        "theme_dark": theme_dark.strip(),
+        "session": session or "default",
+        "play_emoji": _play_emoji,
+        "clear_emoji": _clear_emoji,
+    }
+    rendered = _template % data
+    if exclude_assets:
+        return rendered
+    return _assets.format(version=version) + rendered