refactor: Move code under internal folder

Author: pawamoy

docs/reference/api.md

@@ -5,3 +5,5 @@ hide:
 ---
 
 # ::: markdown_exec
+    options:
+        show_submodules: true

pyproject.toml

@@ -47,7 +47,7 @@ Gitter = "https://gitter.im/markdown-exec/community"
 Funding = "https://github.com/sponsors/pawamoy"
 
 [project.entry-points."mkdocs.plugins"]
-markdown-exec = "markdown_exec.mkdocs_plugin:MarkdownExecPlugin"
+markdown-exec = "markdown_exec:MarkdownExecPlugin"
 
 [tool.pdm.version]
 source = "call"

src/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",
+]

src/markdown_exec/_internal/formatters/__init__.py

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

src/markdown_exec/formatters/_exec_python.py renamed to src/markdown_exec/_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
 

src/markdown_exec/formatters/base.py renamed to src/markdown_exec/_internal/formatters/base.py

@@ -1,4 +1,4 @@
-"""Generic formatter for executing code."""
+# Generic formatter for executing code.
 
 from __future__ import annotations
 
@@ -10,8 +10,8 @@
 
 from markupsafe import Markup
 
-from markdown_exec.logger import get_logger
-from markdown_exec.rendering import MarkdownConverter, add_source, code_block
+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
@@ -71,7 +71,7 @@ class ExecutionError(Exception):
         returncode: The code returned by the execution of the code block.
     """
 
-    def __init__(self, message: str, returncode: int | None = None) -> None:  # noqa: D107
+    def __init__(self, message: str, returncode: int | None = None) -> None:
         super().__init__(message)
         self.returncode = returncode
 

src/markdown_exec/formatters/bash.py renamed to src/markdown_exec/_internal/formatters/bash.py

@@ -1,12 +1,12 @@
-"""Formatter for executing shell code."""
+# Formatter for executing shell code.
 
 from __future__ import annotations
 
 import subprocess
 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.base import ExecutionError, base_format
+from markdown_exec._internal.rendering import code_block
 
 
 def _run_bash(

src/markdown_exec/formatters/console.py renamed to src/markdown_exec/_internal/formatters/console.py

@@ -1,13 +1,13 @@
-"""Formatter for executing shell console code."""
+# Formatter for executing shell console code.
 
 from __future__ import annotations
 
 import textwrap
 from typing import TYPE_CHECKING, 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.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

src/markdown_exec/formatters/markdown.py renamed to src/markdown_exec/_internal/formatters/markdown.py

@@ -1,10 +1,10 @@
-"""Formatter for literate Markdown."""
+# Formatter for literate Markdown.
 
 from __future__ import annotations
 
 from typing import Any
 
-from markdown_exec.formatters.base import base_format
+from markdown_exec._internal.formatters.base import base_format
 
 
 def _format_markdown(**kwargs: Any) -> str:

src/markdown_exec/formatters/pycon.py renamed to src/markdown_exec/_internal/formatters/pycon.py

@@ -1,12 +1,12 @@
-"""Formatter for executing `pycon` code."""
+# Formatter for executing `pycon` code.
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-from markdown_exec.formatters.base import base_format
-from markdown_exec.formatters.python import _run_python
-from markdown_exec.logger import get_logger
+from markdown_exec._internal.formatters.base import base_format
+from markdown_exec._internal.formatters.python import _run_python
+from markdown_exec._internal.logger import get_logger
 
 if TYPE_CHECKING:
     from markupsafe import Markup

src/markdown_exec/formatters/pyodide.py renamed to src/markdown_exec/_internal/formatters/pyodide.py

@@ -1,4 +1,4 @@
-"""Formatter for creating a Pyodide interactive editor."""
+# Formatter for creating a Pyodide interactive editor.
 
 from __future__ import annotations
 

src/markdown_exec/formatters/python.py renamed to src/markdown_exec/_internal/formatters/python.py

@@ -1,4 +1,4 @@
-"""Formatter for executing Python code."""
+# Formatter for executing Python code.
 
 from __future__ import annotations
 
@@ -11,9 +11,9 @@
 from types import ModuleType
 from typing import Any
 
-from markdown_exec.formatters._exec_python import exec_python
-from markdown_exec.formatters.base import ExecutionError, base_format
-from markdown_exec.rendering import code_block
+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)

src/markdown_exec/formatters/sh.py renamed to src/markdown_exec/_internal/formatters/sh.py

@@ -1,12 +1,12 @@
-"""Formatter for executing shell code."""
+# Formatter for executing shell code.
 
 from __future__ import annotations
 
 import subprocess
 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.base import ExecutionError, base_format
+from markdown_exec._internal.rendering import code_block
 
 
 def _run_sh(

src/markdown_exec/formatters/tree.py renamed to src/markdown_exec/_internal/formatters/tree.py

@@ -1,11 +1,11 @@
-"""Formatter for file-system trees."""
+# Formatter for file-system trees.
 
 from __future__ import annotations
 
 from textwrap import dedent
 from typing import TYPE_CHECKING, Any
 
-from markdown_exec.rendering import MarkdownConverter, code_block
+from markdown_exec._internal.rendering import MarkdownConverter, code_block
 
 if TYPE_CHECKING:
     from markdown import Markdown