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

{importpython_markdown-0.1.0/src/importpython_markdown.egg-info → importpython_markdown-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: importpython-markdown
-Version: 0.1.0
+Version: 0.1.2
 Summary: Runnable Python examples in Markdown, via importpython.org.
 Author-email: "Nicholas H.Tollervey" <ntoll@ntoll.org>
 License: MIT
@@ -43,9 +43,11 @@ 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.
+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:
 

{importpython_markdown-0.1.0 → importpython_markdown-0.1.2}/README.md

@@ -22,9 +22,11 @@ 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.
+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:
 

{importpython_markdown-0.1.0 → importpython_markdown-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "importpython-markdown"
-version = "0.1.0"
+version = "0.1.2"
 description = "Runnable Python examples in Markdown, via importpython.org."
 readme = "README.md"
 license = { text = "MIT" }

{importpython_markdown-0.1.0 → importpython_markdown-0.1.2}/src/importpython_markdown/__init__.py

@@ -14,8 +14,11 @@ 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.
+part is a ``<pre>`` holding one ``<code>``, the pre a direct
+child of the element, in the order the author wrote it. The
+element reads a ``<pre><code>`` pair and a bare ``<pre>``
+identically; the inner ``<code>`` is for the surrounding theme,
+whose block styling and copy button expect it.
 """
 
 import html
@@ -49,8 +52,9 @@ ATTRIBUTE = re.compile(r'([\w-]+)(?:="([^"]*)")?')
 # 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")
+FLAGS = ("terminal", "debug", "send-embedder-url")
+VALUED = ("title", "run-label", "stop-label", "theme", "class",
+          "id", "terminal-rows", "terminal-cols")
 
 
 class ExampleError(ValueError):
@@ -106,6 +110,23 @@ def parse_gate(header, line):
         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
 
 
@@ -173,7 +194,7 @@ def split_example(lines, first_line):
     return pieces
 
 
-def validate(pieces, line):
+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
@@ -201,12 +222,37 @@ def validate(pieces, line):
             )
     for piece in [p for p in pieces if p["part"] == "config"]:
         try:
-            json.loads("\n".join(piece["text"]))
+            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):
@@ -301,7 +347,7 @@ class ImportPythonPreprocessor(Preprocessor):
         """
         attributes = parse_gate(header, first_line)
         pieces = split_example(lines, first_line + 1)
-        validate(pieces, first_line)
+        validate(pieces, attributes, first_line)
         parts = ["<import-python"]
         for name, value in attributes.items():
             if value is None:
@@ -331,22 +377,29 @@ class ImportPythonPreprocessor(Preprocessor):
             )
             return inner.convert("\n".join(piece["text"])) + "\n"
         text, lit = self.paint("\n".join(piece["text"]), piece)
+        # One code element inside every pre, highlighted or not:
+        # MkDocs-family themes hang block styling and the copy
+        # button on pre > code, and the element reads both shapes
+        # identically. No newline before the text - a pre swallows
+        # one after its own tag, a code does not - so textContent
+        # stays byte-identical to the bare-pre form.
+        text = f"<code>{text}\n</code>"
         if piece["part"] == "file":
             title = html.escape(piece["title"])
-            return f'<pre{lit} title="{title}">\n{text}\n</pre>\n'
+            return f'<pre{lit} title="{title}">{text}</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"
+            return f'<pre{lit} data-role="{role}">{text}</pre>\n'
+        return f"<pre{lit}>{text}</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.
+        of any kind - render_piece adds the one code element both
+        paths share, and the pre stays the direct child. 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
@@ -385,7 +438,7 @@ class ImportPythonExtension(Extension):
     def __init__(self, **kwargs):
         self.config = {
             "script_url": [
-                "https://importpython.org/bfp/test/embed.js",
+                "https://importpython.org/v/test/embed.js",
                 "Where embed.js is served from; point this at "
                 "your own copy to use one.",
             ],

{importpython_markdown-0.1.0 → importpython_markdown-0.1.2/src/importpython_markdown.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: importpython-markdown
-Version: 0.1.0
+Version: 0.1.2
 Summary: Runnable Python examples in Markdown, via importpython.org.
 Author-email: "Nicholas H.Tollervey" <ntoll@ntoll.org>
 License: MIT
@@ -43,9 +43,11 @@ 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.
+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:
 

{importpython_markdown-0.1.0 → importpython_markdown-0.1.2}/tests/test_extension.py

@@ -91,7 +91,7 @@ def test_close_gate_inside_inner_fence_is_content():
         "```\nprint('hi')\n```\n!#\n"
     )
     assert out.count("<import-python") == 1
-    assert ">\n!#\n</pre>" in out
+    assert "<code>!#\n</code></pre>" in out
 
 
 def test_attributes_pass_through_escaped():
@@ -198,9 +198,9 @@ def test_script_tag_once_for_many_examples():
     configured one.
     """
     two = EXAMPLE + "\n" + EXAMPLE
-    out = render(two, script_url="/bfp/test/embed.js")
+    out = render(two, script_url="/v/test/embed.js")
     assert out.count("<import-python") == 2
-    assert out.count('src="/bfp/test/embed.js"') == 1
+    assert out.count('src="/v/test/embed.js"') == 1
     assert 'type="module"' in out
 
 
@@ -213,18 +213,28 @@ def test_script_injection_can_be_turned_off():
     assert "embed.js" not in out
 
 
-def test_highlighting_is_spans_in_a_bare_pre():
+def test_highlighting_is_spans_in_a_pre_code_pair():
     """
-    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.
+    Intent: every part is a pre holding one code element - the
+    shape MkDocs-family themes hang block styling and the copy
+    button on, and one the element reads identically to a bare
+    pre. Colour is Pygments spans inside the code, the pre
+    marked class="highlight" so a site's existing stylesheet
+    applies - never a wrapper outside the pre, which would hide
+    it from the element. With highlighting off the code element
+    remains, so theme styling never depends on Pygments.
     """
     out = render("#!mpy\n\n```python\nprint(1)\n```\n!#\n")
-    assert '<pre class="highlight">' in out
+    assert '<pre class="highlight"><code>' in out
     assert '<span class="nb">print</span>' in out
+    assert "</code></pre>" in out
     assert "<div" not in out
-    assert "<code" not in out
+    plain = render(
+        "#!mpy\n\n```python\nprint(1)\n```\n!#\n",
+        highlight=False,
+    )
+    assert "<pre><code>print(1)\n</code></pre>" in plain
+    assert "<span" not in plain
 
 
 def test_file_language_guessed_from_its_name():
@@ -272,3 +282,74 @@ def test_the_element_is_never_paragraph_wrapped():
     out = render(EXAMPLE)
     assert "<p><import-python" not in out
     assert "<p><script" not in out
+
+
+def test_send_embedder_url_flag_passes_through():
+    """
+    Intent: the flag is allow-listed and reaches the element as
+    its attribute, so the page's embed.js can act on it.
+    """
+    out = render(
+        "#!mpy send-embedder-url\n\n```\nimport importpython\n```\n!#\n"
+    )
+    assert "send-embedder-url" in out.split(">")[0]
+
+
+def test_send_embedder_url_reserves_the_filename():
+    """
+    Intent: while the flag is on, importpython.py belongs to the
+    service - a titled block or a configured files entry by that
+    name is a named build failure, never a silent overwrite.
+    """
+    with pytest.raises(ExampleError, match="reserves the file"):
+        render(
+            "#!mpy send-embedder-url\n\n"
+            '```title="importpython.py"\nx\n```\n\n'
+            "```\nimport importpython\n```\n!#\n"
+        )
+    with pytest.raises(ExampleError, match="reserves the file"):
+        render(
+            "#!mpy send-embedder-url\n\n"
+            "```config\n"
+            '{ "files": { "data:x": "./importpython.py" } }\n'
+            "```\n\n```\nimport importpython\n```\n!#\n"
+        )
+    # Without the flag, the name is the author's to use.
+    out = render(
+        '#!mpy\n\n```title="importpython.py"\nx = 1\n```\n\n'
+        "```\nimport importpython\n```\n!#\n"
+    )
+    assert 'title="importpython.py"' in out
+
+
+def test_terminal_size_passes_through():
+    """
+    Intent: terminal-rows and terminal-cols are allow-listed valued
+    attributes that reach the element, sized and named as BFP
+    has them.
+    """
+    out = render(
+        '#!mpy terminal terminal-rows="4" terminal-cols="60"\n\n'
+        "```\nprint(1)\n```\n!#\n"
+    )
+    assert 'terminal-rows="4"' in out
+    assert 'terminal-cols="60"' in out
+
+
+def test_terminal_size_is_validated_at_build_time():
+    """
+    Intent: a dimension without the terminal flag, or a value
+    that is not a positive whole number, fails the build with
+    the element's own words - never a runtime error in a
+    reader's browser.
+    """
+    with pytest.raises(ExampleError, match="requires the terminal"):
+        render('#!mpy terminal-rows="4"\n\n```\nx\n```\n!#\n')
+    with pytest.raises(ExampleError, match="positive whole"):
+        render(
+            '#!mpy terminal terminal-rows="0"\n\n```\nx\n```\n!#\n'
+        )
+    with pytest.raises(ExampleError, match="positive whole"):
+        render(
+            '#!mpy terminal terminal-cols="wide"\n\n```\nx\n```\n!#\n'
+        )