importpython-markdown 0.0.1__tar.gz → 0.1.0__tar.gz

importpython_markdown-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas H.Tollervey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

importpython_markdown-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: importpython-markdown
+Version: 0.1.0
+Summary: Runnable Python examples in Markdown, via importpython.org.
+Author-email: "Nicholas H.Tollervey" <ntoll@ntoll.org>
+License: MIT
+Project-URL: Homepage, https://importpython.org/
+Project-URL: Repository, https://codeberg.org/ntoll/importpython
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown>=3.4
+Requires-Dist: pygments>=2.14
+Dynamic: license-file
+
+# importpython-markdown
+
+Runnable Python examples in Markdown pages, for MkDocs, Zensical
+and anything else built on Python-Markdown, powered by
+[importpython.org](https://importpython.org/).
+
+Wrap a section of ordinary Markdown in `#!` and `!#` gates:
+
+    #!mpy terminal title="A first example"
+
+    A caption, rendered as normal Markdown.
+
+    ```python
+    print("Hello, world!")
+    ```
+
+    !#
+
+The section becomes a runnable example: the code, a Run button,
+and the program's output beneath - nothing downloaded until a
+reader presses Run. Plain fences are the program; a fence with
+`title="name.py"` is a file delivered beside it; `config` and
+`body` fences carry BFP settings and page markup (escaped for
+you). The `py` and `mpy` types choose Pyodide or MicroPython,
+and `terminal`, `debug`, `title="..."`, `run-label="..."`,
+`stop-label="..."`, `theme="..."`, `class` and `id` pass through
+to the element.
+
+Install and enable:
+
+    pip install importpython-markdown
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - importpython
+```
+
+```toml
+# zensical.toml
+[project.markdown_extensions]
+importpython = {}
+```
+
+Pre-release honesty: until BFP's first release, the default
+`script_url` points at the service's test channel, which may
+change; pin your own copy with the `script_url` option if that
+matters to you today.
+
+The full documentation lives at
+[importpython.org/docs](https://importpython.org/docs/).

importpython_markdown-0.1.0/README.md

@@ -0,0 +1,51 @@
+# importpython-markdown
+
+Runnable Python examples in Markdown pages, for MkDocs, Zensical
+and anything else built on Python-Markdown, powered by
+[importpython.org](https://importpython.org/).
+
+Wrap a section of ordinary Markdown in `#!` and `!#` gates:
+
+    #!mpy terminal title="A first example"
+
+    A caption, rendered as normal Markdown.
+
+    ```python
+    print("Hello, world!")
+    ```
+
+    !#
+
+The section becomes a runnable example: the code, a Run button,
+and the program's output beneath - nothing downloaded until a
+reader presses Run. Plain fences are the program; a fence with
+`title="name.py"` is a file delivered beside it; `config` and
+`body` fences carry BFP settings and page markup (escaped for
+you). The `py` and `mpy` types choose Pyodide or MicroPython,
+and `terminal`, `debug`, `title="..."`, `run-label="..."`,
+`stop-label="..."`, `theme="..."`, `class` and `id` pass through
+to the element.
+
+Install and enable:
+
+    pip install importpython-markdown
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - importpython
+```
+
+```toml
+# zensical.toml
+[project.markdown_extensions]
+importpython = {}
+```
+
+Pre-release honesty: until BFP's first release, the default
+`script_url` points at the service's test channel, which may
+change; pin your own copy with the `script_url` option if that
+matters to you today.
+
+The full documentation lives at
+[importpython.org/docs](https://importpython.org/docs/).

importpython_markdown-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "importpython-markdown"
+version = "0.1.0"
+description = "Runnable Python examples in Markdown, via importpython.org."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Nicholas H.Tollervey", email = "ntoll@ntoll.org" }]
+requires-python = ">=3.10"
+dependencies = ["markdown>=3.4", "pygments>=2.14"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Documentation",
+  "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+[project.urls]
+Homepage = "https://importpython.org/"
+Repository = "https://codeberg.org/ntoll/importpython"
+
+[project.entry-points."markdown.extensions"]
+importpython = "importpython_markdown:ImportPythonExtension"
+
+[tool.setuptools.packages.find]
+where = ["src"]

importpython_markdown-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

importpython_markdown-0.1.0/src/importpython_markdown/__init__.py

@@ -0,0 +1,431 @@
+"""
+Runnable Python examples in Markdown, for any renderer built on
+Python-Markdown, powered by importpython.org.
+
+A region between a ``#!`` gate line and a ``!#`` gate line
+becomes one ``<import-python>`` element. Inside the gates,
+ordinary Markdown is rendered as captions, and fenced code
+blocks map onto the element's parts: a plain fence is the
+program, ``title="name"`` on a fence is a file delivered beside
+it, and ``config`` and ``body`` fences carry BFP's settings and
+the frame's page markup. The plugin escapes what needs escaping,
+so a documenter never types an entity, and it validates at build
+time in the element's own vocabulary, so an authoring mistake is
+a loud build failure rather than a silent page.
+
+The emitted markup follows the element's contract exactly: each
+part is a bare ``<pre>``, a direct child of the element, in the
+order the author wrote it.
+"""
+
+import html
+import json
+import re
+
+from markdown import Markdown
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name, get_lexer_for_filename
+from pygments.util import ClassNotFound
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+
+# The gates. A #! line opens an example and carries its header;
+# a line that is exactly !# closes it. Both are recognised only
+# outside fenced code, so code about the gates can be quoted.
+OPEN_GATE = re.compile(r"^#!(\S+)(?:\s+(.*))?$")
+CLOSE_GATE = re.compile(r"^!#\s*$")
+
+# A fence opener or closer: three or more backticks or tildes.
+# The closer must use the same character, at least as many, and
+# carry nothing else - the CommonMark rules this plugin needs.
+FENCE = re.compile(r"^(`{3,}|~{3,})\s*(.*)$")
+
+# Attributes on the gate line: bare flags and key="value" pairs.
+ATTRIBUTE = re.compile(r'([\w-]+)(?:="([^"]*)")?')
+
+# The element's runtimes, and what the gate may pass through to
+# it. The allow-list is deliberate: a typo in an attribute should
+# fail the build, not be silently ignored in every reader's
+# browser.
+TYPES = ("py", "mpy")
+FLAGS = ("terminal", "debug")
+VALUED = ("title", "run-label", "stop-label", "theme", "class", "id")
+
+
+class ExampleError(ValueError):
+    """
+    An authoring mistake in an example, raised so the site build
+    fails loudly and names the problem - the documenter's version
+    of the element withholding its button.
+    """
+
+    def __init__(self, line, problem):
+        super().__init__(f"import-python example, line {line}: {problem}")
+
+
+def parse_gate(header, line):
+    """
+    Turn a gate header into the element's attributes, insisting on
+    a known runtime first and allow-listed attributes after it, so
+    every mistake is caught here rather than shipped.
+    """
+    match = OPEN_GATE.match(header)
+    kind = match.group(1)
+    if kind not in TYPES:
+        raise ExampleError(
+            line, f'unknown type "{kind}"; use one of {", ".join(TYPES)}'
+        )
+    attributes = {"type": kind}
+    rest = match.group(2) or ""
+    span = 0
+    for found in ATTRIBUTE.finditer(rest):
+        if rest[span:found.start()].strip():
+            raise ExampleError(
+                line, f'cannot parse attributes at "{rest[span:]}"'
+            )
+        span = found.end()
+        name, value = found.group(1), found.group(2)
+        if value is None:
+            if name not in FLAGS:
+                raise ExampleError(
+                    line,
+                    f'unknown flag "{name}"; '
+                    f'flags are {", ".join(FLAGS)}',
+                )
+            attributes[name] = None
+        else:
+            if name not in VALUED:
+                raise ExampleError(
+                    line,
+                    f'unknown attribute "{name}"; '
+                    f'attributes are {", ".join(VALUED)}',
+                )
+            attributes[name] = value
+    if rest[span:].strip():
+        raise ExampleError(
+            line, f'cannot parse attributes at "{rest[span:]}"'
+        )
+    return attributes
+
+
+def parse_fence_info(info):
+    """
+    Decide what a fence inside the gates is for. A title makes it
+    a file; the reserved words config and body claim their roles;
+    anything else - a language name or nothing - is the program.
+    The language is kept for the highlighter to use later.
+    """
+    title = None
+    found = re.search(r'title="([^"]*)"', info)
+    if found:
+        title = found.group(1)
+        info = (info[:found.start()] + info[found.end():]).strip()
+    language = info.split()[0] if info.split() else None
+    if title is not None:
+        return {"part": "file", "title": title, "language": language}
+    if language in ("config", "body"):
+        return {"part": language, "language": None}
+    return {"part": "program", "language": language}
+
+
+def split_example(lines, first_line):
+    """
+    Walk the region between the gates, separating fenced blocks
+    (the element's parts) from the prose between them (the
+    captions), preserving the author's order throughout.
+    """
+    pieces = []
+    prose = []
+    fence = None
+    block = None
+    for offset, line in enumerate(lines):
+        if fence is None:
+            found = FENCE.match(line)
+            if found:
+                if prose and any(p.strip() for p in prose):
+                    pieces.append({"part": "prose", "text": prose})
+                prose = []
+                fence = found.group(1)
+                block = parse_fence_info(found.group(2).strip())
+                block["text"] = []
+                block["line"] = first_line + offset
+                continue
+            prose.append(line)
+        else:
+            found = FENCE.match(line)
+            closes = (
+                found
+                and found.group(1)[0] == fence[0]
+                and len(found.group(1)) >= len(fence)
+                and not found.group(2).strip()
+            )
+            if closes:
+                pieces.append(block)
+                fence = None
+                block = None
+                continue
+            block["text"].append(line)
+    if fence is not None:
+        raise ExampleError(block["line"], "unclosed code fence")
+    if prose and any(p.strip() for p in prose):
+        pieces.append({"part": "prose", "text": prose})
+    return pieces
+
+
+def validate(pieces, line):
+    """
+    The element's own rules, applied at build time: exactly one
+    program, no duplicate filenames, at most one config (as valid
+    JSON) and one body. The wording follows classify() in
+    embed.js, so both layers speak with one voice.
+    """
+    programs = [p for p in pieces if p["part"] == "program"]
+    if not programs:
+        raise ExampleError(line, "no program block")
+    if len(programs) > 1:
+        raise ExampleError(programs[1]["line"], "more than one program block")
+    names = set()
+    for piece in [p for p in pieces if p["part"] == "file"]:
+        if piece["title"] in names:
+            raise ExampleError(
+                piece["line"],
+                f'two blocks name the file "{piece["title"]}"',
+            )
+        names.add(piece["title"])
+    for role in ("config", "body"):
+        found = [p for p in pieces if p["part"] == role]
+        if len(found) > 1:
+            raise ExampleError(
+                found[1]["line"], f"more than one {role} block"
+            )
+    for piece in [p for p in pieces if p["part"] == "config"]:
+        try:
+            json.loads("\n".join(piece["text"]))
+        except json.JSONDecodeError as error:
+            raise ExampleError(
+                piece["line"],
+                f"the config block is not valid JSON: {error}",
+            ) from None
+
+
+class ImportPythonPreprocessor(Preprocessor):
+    """
+    Find every gated region, build its element, and stash the
+    result so the surrounding renderer treats it as opaque HTML.
+    Fence state is tracked at the top level too, so gates quoted
+    inside ordinary code blocks stay code.
+    """
+
+    def __init__(self, md, config):
+        super().__init__(md)
+        self.config = config
+
+    def run(self, lines):
+        out = []
+        example = None
+        first = 0
+        fence = None
+        emitted = False
+        for number, line in enumerate(lines, start=1):
+            if example is None:
+                found = FENCE.match(line)
+                if fence is None and OPEN_GATE.match(line):
+                    example = []
+                    first = number
+                    continue
+                if found:
+                    if fence is None:
+                        fence = found.group(1)
+                    elif (
+                        found.group(1)[0] == fence[0]
+                        and len(found.group(1)) >= len(fence)
+                        and not found.group(2).strip()
+                    ):
+                        fence = None
+                out.append(line)
+            else:
+                if CLOSE_GATE.match(line) and not self.inside_fence(
+                    example
+                ):
+                    element = self.render(
+                        lines[first - 1], example, first
+                    )
+                    out.append("")
+                    out.append(self.md.htmlStash.store(element))
+                    out.append("")
+                    example = None
+                    emitted = True
+                    continue
+                example.append(line)
+        if example is not None:
+            raise ExampleError(first, "unclosed #! gate: no matching !#")
+        if emitted and self.config["inject_script"]:
+            # As a literal line rather than a stash entry: script
+            # opens an HTML block, so Markdown passes it through
+            # unwrapped, where a stashed placeholder at document
+            # end can be left inside a paragraph.
+            out.append("")
+            out.append(
+                '<script type="module" src="'
+                + html.escape(self.config["script_url"])
+                + '"></script>'
+            )
+            out.append("")
+        return out
+
+    def inside_fence(self, lines):
+        """
+        Whether the region so far ends inside a fenced block, in
+        which case a !# line is content rather than the gate.
+        """
+        fence = None
+        for line in lines:
+            found = FENCE.match(line)
+            if not found:
+                continue
+            if fence is None:
+                fence = found.group(1)
+            elif (
+                found.group(1)[0] == fence[0]
+                and len(found.group(1)) >= len(fence)
+                and not found.group(2).strip()
+            ):
+                fence = None
+        return fence is not None
+
+    def render(self, header, lines, first_line):
+        """
+        One example: parse, validate, and emit the element with
+        its parts and captions in the author's order.
+        """
+        attributes = parse_gate(header, first_line)
+        pieces = split_example(lines, first_line + 1)
+        validate(pieces, first_line)
+        parts = ["<import-python"]
+        for name, value in attributes.items():
+            if value is None:
+                parts.append(f" {name}")
+            else:
+                parts.append(f' {name}="{html.escape(value)}"')
+        parts.append(">\n")
+        for piece in pieces:
+            parts.append(self.render_piece(piece))
+        parts.append("</import-python>")
+        return "".join(parts)
+
+    def render_piece(self, piece):
+        """
+        A caption renders as Markdown through a fresh renderer,
+        so the example's own gates cannot nest; a part becomes a
+        bare pre, a direct child - the element's contract - with
+        its text either highlighted or escaped, and never both by
+        hand: Pygments escapes what it colours, and the plain
+        path escapes here, so the author never types an entity.
+        That is also what makes a body block safe to write as
+        plain markup.
+        """
+        if piece["part"] == "prose":
+            inner = Markdown(
+                extensions=self.config["inner_extensions"]
+            )
+            return inner.convert("\n".join(piece["text"])) + "\n"
+        text, lit = self.paint("\n".join(piece["text"]), piece)
+        if piece["part"] == "file":
+            title = html.escape(piece["title"])
+            return f'<pre{lit} title="{title}">\n{text}\n</pre>\n'
+        if piece["part"] in ("config", "body"):
+            role = piece["part"]
+            return f'<pre{lit} data-role="{role}">\n{text}\n</pre>\n'
+        return f"<pre{lit}>\n{text}\n</pre>\n"
+
+    def paint(self, code, piece):
+        """
+        Highlight a part's code as Pygments spans with no wrapper
+        of any kind, so the pre stays a bare direct child and its
+        textContent stays exactly the code. The class="highlight"
+        the coloured path adds is what lets a Material or
+        Zensical site's existing Pygments stylesheet colour these
+        blocks, palettes and all, with no CSS of ours.
+
+        The language comes from the fence, or a file's name, with
+        json and html assumed for config and body; an unknown or
+        absent language falls back to plain escaped text, as the
+        wider ecosystem does, because colour is decoration rather
+        than contract.
+        """
+        lexer = None
+        if self.config["highlight"]:
+            language = piece.get("language")
+            if piece["part"] == "config":
+                language = "json"
+            elif piece["part"] == "body":
+                language = "html"
+            try:
+                if language:
+                    lexer = get_lexer_by_name(language)
+                elif piece["part"] == "file":
+                    lexer = get_lexer_for_filename(piece["title"])
+            except ClassNotFound:
+                lexer = None
+        if lexer is None:
+            return html.escape(code, quote=False), ""
+        painted = highlight(
+            code, lexer, HtmlFormatter(nowrap=True)
+        ).rstrip("\n")
+        return painted, ' class="highlight"'
+
+
+class ImportPythonExtension(Extension):
+    """
+    The extension: register the preprocessor early, before other
+    preprocessors can mistake the gated region for their own.
+    """
+
+    def __init__(self, **kwargs):
+        self.config = {
+            "script_url": [
+                "https://importpython.org/bfp/test/embed.js",
+                "Where embed.js is served from; point this at "
+                "your own copy to use one.",
+            ],
+            "inject_script": [
+                True,
+                "Append one script tag to any page that carries "
+                "an example. Turn off for sites that load "
+                "embed.js themselves.",
+            ],
+            "inner_extensions": [
+                [],
+                "Markdown extensions applied to the captions "
+                "inside an example.",
+            ],
+            "highlight": [
+                True,
+                "Colour the code with Pygments spans inside the "
+                "bare pre, marked class=\"highlight\" so a "
+                "site's existing Pygments stylesheet applies.",
+            ],
+        }
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md):
+        # The element must be known as block-level, or the raw
+        # HTML postprocessor leaves the stashed element wrapped
+        # in a paragraph - and a pre inside a p makes browsers
+        # close the paragraph early, structurally breaking the
+        # direct-child contract the plugin exists to honour.
+        md.block_level_elements.append("import-python")
+        md.preprocessors.register(
+            ImportPythonPreprocessor(md, self.getConfigs()),
+            "import-python",
+            28,
+        )
+
+
+def makeExtension(**kwargs):
+    """
+    The hook Python-Markdown looks for when the extension is
+    named by its module path.
+    """
+    return ImportPythonExtension(**kwargs)

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: importpython-markdown
+Version: 0.1.0
+Summary: Runnable Python examples in Markdown, via importpython.org.
+Author-email: "Nicholas H.Tollervey" <ntoll@ntoll.org>
+License: MIT
+Project-URL: Homepage, https://importpython.org/
+Project-URL: Repository, https://codeberg.org/ntoll/importpython
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown>=3.4
+Requires-Dist: pygments>=2.14
+Dynamic: license-file
+
+# importpython-markdown
+
+Runnable Python examples in Markdown pages, for MkDocs, Zensical
+and anything else built on Python-Markdown, powered by
+[importpython.org](https://importpython.org/).
+
+Wrap a section of ordinary Markdown in `#!` and `!#` gates:
+
+    #!mpy terminal title="A first example"
+
+    A caption, rendered as normal Markdown.
+
+    ```python
+    print("Hello, world!")
+    ```
+
+    !#
+
+The section becomes a runnable example: the code, a Run button,
+and the program's output beneath - nothing downloaded until a
+reader presses Run. Plain fences are the program; a fence with
+`title="name.py"` is a file delivered beside it; `config` and
+`body` fences carry BFP settings and page markup (escaped for
+you). The `py` and `mpy` types choose Pyodide or MicroPython,
+and `terminal`, `debug`, `title="..."`, `run-label="..."`,
+`stop-label="..."`, `theme="..."`, `class` and `id` pass through
+to the element.
+
+Install and enable:
+
+    pip install importpython-markdown
+
+```yaml
+# mkdocs.yml
+markdown_extensions:
+  - importpython
+```
+
+```toml
+# zensical.toml
+[project.markdown_extensions]
+importpython = {}
+```
+
+Pre-release honesty: until BFP's first release, the default
+`script_url` points at the service's test channel, which may
+change; pin your own copy with the `script_url` option if that
+matters to you today.
+
+The full documentation lives at
+[importpython.org/docs](https://importpython.org/docs/).

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/importpython_markdown/__init__.py
+src/importpython_markdown.egg-info/PKG-INFO
+src/importpython_markdown.egg-info/SOURCES.txt
+src/importpython_markdown.egg-info/dependency_links.txt
+src/importpython_markdown.egg-info/entry_points.txt
+src/importpython_markdown.egg-info/requires.txt
+src/importpython_markdown.egg-info/top_level.txt
+tests/test_extension.py

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[markdown.extensions]
+importpython = importpython_markdown:ImportPythonExtension

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/requires.txt

@@ -0,0 +1,2 @@
+markdown>=3.4
+pygments>=2.14

importpython_markdown-0.1.0/src/importpython_markdown.egg-info/top_level.txt

@@ -0,0 +1 @@
+importpython_markdown

importpython_markdown-0.1.0/tests/test_extension.py

@@ -0,0 +1,274 @@
+"""
+Unit tests for importpython-markdown: the gates, the mappings,
+the escaping, the validation, and the script tag - one test per
+rule, so a failure names its rule.
+"""
+
+import markdown
+import pytest
+
+from importpython_markdown import ExampleError
+
+
+def render(text, **options):
+    """
+    Render Markdown with the extension configured as a user
+    would configure it.
+    """
+    md = markdown.Markdown(
+        extensions=["importpython_markdown"],
+        extension_configs={"importpython_markdown": options},
+    )
+    return md.convert(text)
+
+
+EXAMPLE = """\
+#!py terminal debug
+
+Here is the Foo module.
+
+```title="foo.py"
+def foo():
+    return 42
+```
+
+* Some
+* Random
+* Markdown
+
+```
+import foo
+
+print(foo.foo())
+```
+!#
+"""
+
+
+def test_the_worked_example():
+    """
+    Intent: the example from the design conversation renders as
+    one element with a file, two captions, and the program, in
+    the author's order, with the flags carried across.
+    """
+    out = render(EXAMPLE)
+    assert '<import-python type="py" terminal debug>' in out
+    assert 'title="foo.py"' in out
+    assert "foo" in out
+    assert "<li>Random</li>" in out
+    assert "print(foo.foo())" in out
+    assert out.index("Foo module") < out.index('title="foo.py"')
+    assert out.index("<li>Some") < out.index("import foo")
+    assert out.count("<import-python") == 1
+
+
+def test_untouched_without_gates():
+    """
+    Intent: a document with no gates is not our business, and no
+    script tag is added to it.
+    """
+    out = render("# Hello\n\nJust prose.\n")
+    assert "import-python" not in out
+    assert "embed.js" not in out
+
+
+def test_gate_inside_a_fence_is_code():
+    """
+    Intent: documentation about the gates can quote them - a #!
+    line inside an ordinary fenced block opens nothing.
+    """
+    out = render("```\n#!py\n!#\n```\n")
+    assert "import-python" not in out
+
+
+def test_close_gate_inside_inner_fence_is_content():
+    """
+    Intent: a !# inside a fenced block inside the gates is code
+    (somebody's shell snippet), not the closing gate.
+    """
+    out = render(
+        '#!mpy\n```title="notes.sh"\n!#\n```\n\n'
+        "```\nprint('hi')\n```\n!#\n"
+    )
+    assert out.count("<import-python") == 1
+    assert ">\n!#\n</pre>" in out
+
+
+def test_attributes_pass_through_escaped():
+    """
+    Intent: valued attributes reach the element, HTML-escaped,
+    and the accessible-name convention survives the trip.
+    """
+    out = render(
+        '#!mpy title="A & B" run-label="Go"\n\n'
+        "```\nprint(1)\n```\n!#\n"
+    )
+    assert 'title="A &amp; B"' in out
+    assert 'run-label="Go"' in out
+
+
+def test_program_is_escaped():
+    """
+    Intent: the two characters HTML cares about are escaped for
+    the author, so what runs is what was written.
+    """
+    out = render(
+        "#!mpy\n\n```\nprint(1 < 2 & 3)\n```\n!#\n",
+        highlight=False,
+    )
+    assert "print(1 &lt; 2 &amp; 3)" in out
+
+
+def test_body_is_escaped_for_the_author():
+    """
+    Intent: a body block is written as plain markup and arrives
+    escaped, the two-character chore done by the machine.
+    """
+    out = render(
+        "#!mpy\n\n```body\n<p id=\"out\"></p>\n```\n\n"
+        "```\nprint(1)\n```\n!#\n"
+    )
+    assert 'data-role="body"' in out
+    assert "&lt;" in out and "<p id=" not in out
+
+
+def test_config_maps_and_validates():
+    """
+    Intent: a config fence becomes the config block, and only
+    valid JSON is allowed through.
+    """
+    out = render(
+        '#!py\n\n```config\n{ "packages": ["arrr"] }\n```\n\n'
+        "```\nimport arrr\n```\n!#\n"
+    )
+    assert 'data-role="config"' in out
+    with pytest.raises(ExampleError, match="not valid JSON"):
+        render("#!py\n\n```config\nnope\n```\n\n```\nx\n```\n!#\n")
+
+
+def test_unknown_type_fails_the_build():
+    """
+    Intent: a typo in the runtime is a build failure that names
+    the valid choices.
+    """
+    with pytest.raises(ExampleError, match='unknown type "pyy"'):
+        render("#!pyy\n\n```\nx\n```\n!#\n")
+
+
+def test_unknown_flag_and_attribute_fail_the_build():
+    """
+    Intent: the allow-list catches typos at build time rather
+    than shipping silently ignored attributes.
+    """
+    with pytest.raises(ExampleError, match='unknown flag "terminl"'):
+        render("#!py terminl\n\n```\nx\n```\n!#\n")
+    with pytest.raises(ExampleError, match='unknown attribute "titel"'):
+        render('#!py titel="x"\n\n```\nx\n```\n!#\n')
+
+
+def test_the_element_rules_apply_at_build_time():
+    """
+    Intent: classify()'s structural rules, spoken here in the
+    same words: one program, no duplicate filenames, one config.
+    """
+    with pytest.raises(ExampleError, match="no program block"):
+        render("#!py\n\nJust prose.\n!#\n")
+    with pytest.raises(ExampleError, match="more than one program"):
+        render("#!py\n\n```\na\n```\n\n```\nb\n```\n!#\n")
+    with pytest.raises(ExampleError, match='name the file "a.py"'):
+        render(
+            '#!py\n\n```title="a.py"\nx\n```\n\n'
+            '```title="a.py"\ny\n```\n\n```\nz\n```\n!#\n'
+        )
+
+
+def test_unclosed_gate_fails_the_build():
+    """
+    Intent: a forgotten !# is a named build failure, not a page
+    quietly swallowed to its end.
+    """
+    with pytest.raises(ExampleError, match="unclosed #! gate"):
+        render("#!py\n\n```\nx\n```\n")
+
+
+def test_script_tag_once_for_many_examples():
+    """
+    Intent: a page with examples gets exactly one script tag,
+    however many examples it carries, and its URL is the
+    configured one.
+    """
+    two = EXAMPLE + "\n" + EXAMPLE
+    out = render(two, script_url="/bfp/test/embed.js")
+    assert out.count("<import-python") == 2
+    assert out.count('src="/bfp/test/embed.js"') == 1
+    assert 'type="module"' in out
+
+
+def test_script_injection_can_be_turned_off():
+    """
+    Intent: sites loading embed.js themselves can say so and get
+    no second copy.
+    """
+    out = render(EXAMPLE, inject_script=False)
+    assert "embed.js" not in out
+
+
+def test_highlighting_is_spans_in_a_bare_pre():
+    """
+    Intent: colour arrives as Pygments spans inside the bare pre
+    direct child, marked class="highlight" so a site's existing
+    Pygments stylesheet applies - never a wrapper element, which
+    would hide the pre from the element.
+    """
+    out = render("#!mpy\n\n```python\nprint(1)\n```\n!#\n")
+    assert '<pre class="highlight">' in out
+    assert '<span class="nb">print</span>' in out
+    assert "<div" not in out
+    assert "<code" not in out
+
+
+def test_file_language_guessed_from_its_name():
+    """
+    Intent: a file block with no language on the fence is
+    coloured by its filename's extension.
+    """
+    out = render(
+        '#!mpy\n\n```title="a.py"\nx = 1\n```\n\n'
+        "```\nimport a\n```\n!#\n"
+    )
+    assert 'class="highlight" title="a.py"' in out
+
+
+def test_unknown_language_falls_back_to_plain():
+    """
+    Intent: colour is decoration, not contract - a language
+    Pygments does not know renders plain and escaped, exactly as
+    the wider ecosystem behaves.
+    """
+    out = render("#!mpy\n\n```pyton\nprint(1 < 2)\n```\n!#\n")
+    assert "<span" not in out
+    assert "1 &lt; 2" in out
+
+
+def test_config_and_body_get_their_languages():
+    """
+    Intent: config is coloured as JSON and body as HTML, with the
+    body's markup still escaped so its textContent is the markup.
+    """
+    out = render(
+        '#!py\n\n```config\n{ "packages": ["x"] }\n```\n\n'
+        '```body\n<p id="o"></p>\n```\n\n```\nz\n```\n!#\n'
+    )
+    assert out.count("<span") >= 2
+    assert "<p id=" not in out
+
+
+def test_the_element_is_never_paragraph_wrapped():
+    """
+    Intent: the element and the script tag stand as blocks - a
+    pre inside a paragraph would make browsers close the
+    paragraph early and break the direct-child contract.
+    """
+    out = render(EXAMPLE)
+    assert "<p><import-python" not in out
+    assert "<p><script" not in out

importpython_markdown-0.0.1/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.5
-Name: importpython-markdown
-Version: 0.0.1
-Summary: A markdown plugin to use importpython in docs.
-Author-email: "Nicholas H.Tollervey" <ntoll@ntoll.org>
-License-Expression: MIT
-Requires-Python: >=3.11

importpython_markdown-0.0.1/pyproject.toml

@@ -1,16 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "importpython-markdown"
-dynamic = ["version"]
-description = "A markdown plugin to use importpython in docs."
-requires-python = ">=3.11"
-license = "MIT"
-authors = [
-    {name = "Nicholas H.Tollervey", email = "ntoll@ntoll.org"},
-]
-
-[tool.hatch.version]
-path = "src/importpython_markdown/__init__.py"

importpython_markdown-0.0.1/src/importpython_markdown/__init__.py

@@ -1,5 +0,0 @@
-"""
-importpython-markdown
-"""
-
-__version__ = "0.0.1"