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

markdown_exec/_internal/rendering.py

@@ -0,0 +1,280 @@
+# Markdown extensions and helpers.
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from functools import cache
+from textwrap import indent
+from typing import TYPE_CHECKING, Any
+
+from markdown import Markdown
+from markupsafe import Markup
+
+from markdown_exec._internal.processors import (
+    HeadingReportingTreeprocessor,
+    IdPrependingTreeprocessor,
+    InsertHeadings,
+    RemoveHeadings,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.etree.ElementTree import Element
+
+    from markdown import Extension
+
+
+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(r"\|", "|").strip()  # noqa: PLW2901
+        parts.append(f'=== "{title}"')
+        parts.append(indent(text, prefix=" " * 4))
+        parts.append("")
+    return "\n".join(parts)
+
+
+def _hide_lines(source: str) -> str:
+    return "\n".join(line for line in source.split("\n") if "markdown-exec: hide" not in line).strip()
+
+
+def add_source(
+    *,
+    source: str,
+    location: str,
+    output: str,
+    language: str,
+    tabs: tuple[str, str],
+    result: str = "",
+    **extra: str,
+) -> str:
+    """Add source code block to the output.
+
+    Parameters:
+        source: The source code block.
+        location: Where to add the source (above, below, tabbed-left, tabbed-right, console).
+        output: The current output.
+        language: The code language.
+        tabs: Tabs titles (if used).
+        result: Syntax to use when concatenating source and result with "console" location.
+        **extra: Extra options added back to source code block.
+
+    Raises:
+        ValueError: When the given location is not supported.
+
+    Returns:
+        The updated output.
+    """
+    source = _hide_lines(source)
+    if location == "console":
+        return code_block(result or language, source + "\n" + output, **extra)
+
+    source_block = code_block(language, source, **extra)
+    if location == "above":
+        return source_block + "\n\n" + output
+    if location == "below":
+        return output + "\n\n" + source_block
+    if location == "material-block":
+        return source_block + f'\n\n<div class="result" markdown="1" >\n\n{output}\n\n</div>'
+
+    source_tab_title, result_tab_title = tabs
+    if location == "tabbed-left":
+        return tabbed((source_tab_title, source_block), (result_tab_title, output))
+    if location == "tabbed-right":
+        return tabbed((result_tab_title, output), (source_tab_title, source_block))
+
+    raise ValueError(f"unsupported location for sources: {location}")
+
+
+class MarkdownConfig:
+    """This class returns a singleton used to store Markdown extensions configuration.
+
+    You don't have to instantiate the singleton yourself:
+    we provide it as [`markdown_config`][markdown_exec.markdown_config].
+    """
+
+    _singleton: MarkdownConfig | None = None
+
+    def __new__(cls) -> MarkdownConfig:  # noqa: PYI034
+        """Return the singleton instance."""
+        if cls._singleton is None:
+            cls._singleton = super().__new__(cls)
+        return cls._singleton
+
+    def __init__(self) -> None:
+        self.exts: list[str] | None = None
+        """The Markdown extensions."""
+        self.exts_config: dict[str, dict[str, Any]] | None = None
+        """The extensions configuration."""
+
+    def save(self, exts: list[str], exts_config: dict[str, dict[str, Any]]) -> None:
+        """Save Markdown extensions and their configuration.
+
+        Parameters:
+            exts: The Markdown extensions.
+            exts_config: The extensions configuration.
+        """
+        self.exts = exts
+        self.exts_config = exts_config
+
+    def reset(self) -> None:
+        """Reset Markdown extensions and their configuration."""
+        self.exts = None
+        self.exts_config = None
+
+
+markdown_config = MarkdownConfig()
+"""This object can be used to save the configuration of your Markdown extensions.
+
+For example, since we provide a MkDocs plugin, we use it to store the configuration
+that was read from `mkdocs.yml`:
+
+```python
+from markdown_exec.rendering import markdown_config
+
+# ...in relevant events/hooks, access and modify extensions and their configs, then:
+markdown_config.save(extensions, extensions_config)
+```
+
+See the actual event hook: [`on_config`][markdown_exec.MarkdownExecPlugin.on_config].
+See the [`save`][markdown_exec.MarkdownConfig.save]
+and [`reset`][markdown_exec.MarkdownConfig.reset] methods.
+
+Without it, Markdown Exec will rely on the `registeredExtensions` attribute
+of the original Markdown instance, which does not forward everything
+that was configured, notably extensions like `tables`. Other extensions
+such as `attr_list` are visible, but fail to register properly when
+reusing their instances. It means that the rendered HTML might differ
+from what you expect (tables not rendered, attribute lists not injected,
+emojis not working, etc.).
+"""
+
+# FIXME: When a heading contains an XML entity such as &mdash;,
+# the entity is stashed and replaced with a placeholder.
+# The heading therefore contains this placeholder.
+# When reporting the heading to the upper conversion layer (for the ToC),
+# the placeholder gets unstashed using the upper Markdown instance
+# instead of the neste one. If the upper instance doesn't know the placeholder,
+# nothing happens. But if it knows it, we then get a heading with garbabe/previous
+# contents within it, messing up the ToC.
+# We should fix this somehow. In the meantime, the workaround is to avoid
+# XML entities that get stashed in headings.
+
+
+@cache
+def _register_headings_processors(md: Markdown) -> None:
+    md.treeprocessors.register(
+        InsertHeadings(md),
+        InsertHeadings.name,
+        priority=75,  # right before markdown.blockprocessors.HashHeaderProcessor
+    )
+    md.treeprocessors.register(
+        RemoveHeadings(md),
+        RemoveHeadings.name,
+        priority=4,  # right after toc
+    )
+
+
+def _mimic(md: Markdown, headings: list[Element], *, update_toc: bool = True) -> Markdown:
+    new_md = Markdown()
+    extensions: list[Extension | str] = markdown_config.exts or md.registeredExtensions  # type: ignore[assignment]
+    extensions_config: dict[str, dict[str, Any]] = markdown_config.exts_config or {}
+    new_md.registerExtensions(extensions, extensions_config)
+    new_md.treeprocessors.register(
+        IdPrependingTreeprocessor(md, ""),
+        IdPrependingTreeprocessor.name,
+        priority=4,  # right after 'toc' (needed because that extension adds ids to headings)
+    )
+    new_md._original_md = md  # type: ignore[attr-defined]
+
+    if update_toc:
+        _register_headings_processors(md)
+        new_md.treeprocessors.register(
+            HeadingReportingTreeprocessor(new_md, headings),
+            HeadingReportingTreeprocessor.name,
+            priority=1,  # Close to the end.
+        )
+
+    return new_md
+
+
+@contextmanager
+def _id_prefix(md: Markdown, prefix: str | None) -> Iterator[None]:
+    MarkdownConverter.counter += 1
+    id_prepending_processor = md.treeprocessors[IdPrependingTreeprocessor.name]
+    id_prepending_processor.id_prefix = prefix if prefix is not None else f"exec-{MarkdownConverter.counter}--"  # type: ignore[attr-defined]
+    try:
+        yield
+    finally:
+        id_prepending_processor.id_prefix = ""  # type: ignore[attr-defined]
+
+
+class MarkdownConverter:
+    """Helper class to avoid breaking the original Markdown instance state."""
+
+    counter: int = 0
+    """A counter to generate unique IDs for code blocks."""
+
+    def __init__(self, md: Markdown, *, update_toc: bool = True) -> None:
+        self._md_ref: Markdown = md
+        self._headings: list[Element] = []
+        self._update_toc = update_toc
+
+    @property
+    def _original_md(self) -> Markdown:
+        return getattr(self._md_ref, "_original_md", self._md_ref)
+
+    def _report_headings(self, markup: Markup) -> None:
+        self._original_md.treeprocessors[InsertHeadings.name].headings[markup] = self._headings  # type: ignore[attr-defined]
+        self._headings = []
+
+    def convert(self, text: str, stash: dict[str, str] | None = None, id_prefix: str | None = None) -> Markup:
+        """Convert Markdown text to safe HTML.
+
+        Parameters:
+            text: Markdown text.
+            stash: An HTML stash.
+
+        Returns:
+            Safe HTML.
+        """
+        md = _mimic(self._original_md, self._headings, update_toc=self._update_toc)
+
+        # convert markdown to html
+        with _id_prefix(md, id_prefix):
+            converted = md.convert(text)
+
+        # restore html from stash
+        for placeholder, stashed in (stash or {}).items():
+            converted = converted.replace(placeholder, stashed)
+
+        markup = Markup(converted)  # noqa: S704
+
+        # pass headings to upstream conversion layer
+        if self._update_toc:
+            self._report_headings(markup)
+
+        return markup

markdown_exec/{pyodide.css → assets/pyodide.css}

@@ -47,4 +47,9 @@ html[data-theme="dark"] {
 .pyodide-clickable {
     cursor: pointer;
     text-align: right;
-}
+}
+
+/* For themes other than Material. */
+.pyodide .twemoji svg {
+    width: 1rem;
+}

markdown_exec/{pyodide.js → assets/pyodide.js}

@@ -22,9 +22,9 @@ async function evaluatePython(pyodide, editor, output, session) {
     try {
         result = await pyodide.runPythonAsync(code, { globals: getSession(session, pyodide) });
     } catch (error) {
-        writeOutput(output, error);
+        writeOutput(output, new Option(error.toString()).innerHTML);
     }
-    if (result) writeOutput(output, result);
+    if (result) writeOutput(output, new Option(result).innerHTML);
     hljs.highlightElement(output);
 }
 
@@ -91,11 +91,17 @@ async function setupPyodide(idPrefix, install = null, themeLight = 'tomorrow', t
     writeOutput(output, "Initializing...");
     let pyodide = await pyodidePromise;
     if (install && install.length) {
-        micropip = pyodide.pyimport("micropip");
-        for (const package of install)
-            await micropip.install(package);
+        try {
+            micropip = pyodide.pyimport("micropip");
+            for (const package of install)
+                await micropip.install(package);
+            clearOutput(output);
+        } catch (error) {
+            clearOutput(output);
+            writeOutput(output, `Could not install one or more packages: ${install.join(", ")}\n`);
+            writeOutput(output, new Option(error.toString()).innerHTML);
+        }
     }
-    clearOutput(output);
     run.onclick = () => evaluatePython(pyodide, editor, output, session);
     clear.onclick = () => clearOutput(output);
     output.parentElement.parentElement.addEventListener("keydown", (event) => {

markdown_exec/formatters/__init__.py

@@ -1 +1,17 @@
-"""This subpackage contains all the formatters."""
+"""Deprecated. Import from `markdown_exec` directly."""
+
+# YORE: Bump 2: Remove file.
+
+import warnings
+from typing import Any
+
+from markdown_exec._internal import formatters
+
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(formatters, name)

markdown_exec/formatters/base.py

@@ -1,188 +1,17 @@
-"""Generic formatter for executing code."""
+"""Deprecated. Import from `markdown_exec` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import os
-from contextlib import contextmanager
-from textwrap import indent
-from typing import TYPE_CHECKING, Any, Callable
-from uuid import uuid4
+import warnings
+from typing import Any
 
-from markupsafe import Markup
+from markdown_exec._internal.formatters import base
 
-from markdown_exec.logger import get_logger
-from markdown_exec.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")
-
-
-@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:  # noqa: D107
-        super().__init__(message)
-        self.returncode = returncode
-
-
-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)
-
-    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)
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.base` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(base, name)

markdown_exec/formatters/bash.py

@@ -1,32 +1,17 @@
-"""Formatter for executing shell code."""
+"""Deprecated. Import from `markdown_exec` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import subprocess
+import warnings
 from typing import Any
 
-from markdown_exec.formatters.base import ExecutionError, base_format
-from markdown_exec.rendering import code_block
+from markdown_exec._internal.formatters import bash
 
 
-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,
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.bash` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
     )
-    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)
+    return getattr(bash, name)

markdown_exec/formatters/console.py

@@ -1,29 +1,17 @@
-"""Formatter for executing shell console code."""
+"""Deprecated. Import from `markdown_exec` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import textwrap
-from typing import TYPE_CHECKING, Any
+import warnings
+from typing import Any
 
-from markdown_exec.formatters.base import base_format
-from markdown_exec.formatters.sh import _run_sh
-from markdown_exec.logger import get_logger
+from markdown_exec._internal.formatters import console
 
-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)
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.console` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(console, name)

markdown_exec/formatters/markdown.py

@@ -1,11 +1,17 @@
-"""Formatter for literate Markdown."""
+"""Deprecated. Import from `markdown_exec` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
+import warnings
 from typing import Any
 
-from markdown_exec.formatters.base import base_format
+from markdown_exec._internal.formatters import markdown
 
 
-def _format_markdown(**kwargs: Any) -> str:
-    return base_format(language="md", run=lambda code, **_: code, **kwargs)
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `markdown_exec.formatters.markdown` is deprecated. Import from `markdown_exec` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(markdown, name)