importpython-markdown 0.0.1__py3-none-any.whl → 0.1.1__py3-none-any.whl

importpython_markdown/__init__.py

@@ -1,5 +1,474 @@
 """
-importpython-markdown
+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.
 """
 
-__version__ = "0.0.1"
+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", "send-embedder-url")
+VALUED = ("title", "run-label", "stop-label", "theme", "class",
+          "id", "terminal-rows", "terminal-cols")
+
+
+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:]}"'
+        )
+    # The terminal's explicit size: each dimension needs the
+    # terminal it sizes, and only a positive whole number will do
+    # - the same rules the element applies, failing the build
+    # here instead of a reader's browser there.
+    for name in ("terminal-rows", "terminal-cols"):
+        if name in attributes:
+            if "terminal" not in attributes:
+                raise ExampleError(
+                    line, f"{name} requires the terminal flag"
+                )
+            value = attributes[name]
+            if not (value.isdigit() and int(value) >= 1):
+                raise ExampleError(
+                    line,
+                    f'{name} is "{value}"; use a positive whole '
+                    "number",
+                )
+    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, attributes, 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:
+            settings = 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
+        # send-embedder-url writes importpython.py, so while the
+        # flag is on the name is reserved - here in the author's
+        # own config files too, matching the element's rule.
+        if "send-embedder-url" in attributes:
+            names = (settings.get("files") or {}).values()
+            if any(
+                str(name).removeprefix("./") == "importpython.py"
+                for name in names
+            ):
+                raise ExampleError(
+                    piece["line"],
+                    "the send-embedder-url flag reserves the "
+                    'file "importpython.py"',
+                )
+    if "send-embedder-url" in attributes:
+        for piece in pieces:
+            if (
+                piece["part"] == "file"
+                and piece["title"] == "importpython.py"
+            ):
+                raise ExampleError(
+                    piece["line"],
+                    "the send-embedder-url flag reserves the "
+                    'file "importpython.py"',
+                )
+
+
+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, attributes, 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/v/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.1.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: importpython-markdown
+Version: 0.1.1
+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`, `send-embedder-url`, `title="..."`,
+`run-label="..."`, `stop-label="..."`, `theme="..."`,
+`terminal-rows="..."`, `terminal-cols="..."`, `class` and `id`
+pass through to the element - each documented at
+[importpython.org](https://importpython.org/docs/writing-markdown/).
+
+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.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+importpython_markdown/__init__.py,sha256=Un8CqZvwxhC8YT21jS2LxZM4_qOaVtczn0wM_kSqfUE,17832
+importpython_markdown-0.1.1.dist-info/licenses/LICENSE,sha256=ksfiPPZ3bBB4_KgmDo6-NLda44B_-onAZ3JLVxYSIVg,1077
+importpython_markdown-0.1.1.dist-info/METADATA,sha256=1S3ya5P9DRheIA2oMrBS3JXZYWCFws7WbHr8T1vXQCE,2335
+importpython_markdown-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+importpython_markdown-0.1.1.dist-info/entry_points.txt,sha256=0Fo68SFJa3rmdmuysJyRTCu35rve3xGdegmhOutPs18,81
+importpython_markdown-0.1.1.dist-info/top_level.txt,sha256=gZT7U42MZK8PK1UxWpt0IGHGv8ynHvdYlxn-OjZRQ-0,22
+importpython_markdown-0.1.1.dist-info/RECORD,,

{importpython_markdown-0.0.1.dist-info → importpython_markdown-0.1.1.dist-info}/WHEEL

@@ -1,4 +1,5 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
+

importpython_markdown-0.1.1.dist-info/entry_points.txt

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

importpython_markdown-0.1.1.dist-info/licenses/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.1.dist-info/top_level.txt

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

importpython_markdown-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -1,4 +0,0 @@
-importpython_markdown/__init__.py,sha256=hWrpMAM0x9bx9Wfg7DDdLNr7neoKJwcgs5Ilfb3gYi0,53
-importpython_markdown-0.0.1.dist-info/METADATA,sha256=Q9RMRdm8VIn1qAKr58FR7x7YaikPMJe38bckj6w5q4E,224
-importpython_markdown-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-importpython_markdown-0.0.1.dist-info/RECORD,,