fancy-template 0.3.0__tar.gz → 0.4.0__tar.gz

{fancy_template-0.3.0 → fancy_template-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fancy-template
-Version: 0.3.0
+Version: 0.4.0
 Summary: Document templates for the Fancy document writers: a writer document with {{ tokens }} and JSON directives, plus a declaration of the data it needs. inspect() at save time, validate_data() before render, render() to plain writer JSON. No code execution, no includes, bounded everywhere. One spec, three runtimes, held to a shared conformance table.
 Project-URL: Homepage, https://github.com/Particle-Academy/fancy-template
 Project-URL: Issues, https://github.com/Particle-Academy/fancy-template/issues

{fancy_template-0.3.0 → fancy_template-0.4.0}/SPEC.md

@@ -331,7 +331,7 @@ index, `**` for zero or more. **Anything not listed refuses tokens**
 | encoding | result |
 |---|---|
 | `text` | the string, every token stringified |
-| `band` | as `text`, but a VALUE containing `{page}` or `{pages}` is `VALUE_PAGE_FIELD` |
+| `band` | as `text`, but a VALUE containing a writer's band field is `VALUE_PAGE_FIELD`: `{page}` `{pages}` `{section}` `{sectionpages}` `{author}` `{title}` `{filename}`, and `{date}` / `{time}`, each with an optional `:FORMAT` of one or more characters that are not a brace, a double quote or a backslash. Other braces are ordinary text |
 | `markup` | as `text`, each value escaped for the element's `format`: `markdown` backslash-escapes every ASCII punctuation character (CommonMark), `html` escapes `& < > " '` as entities, `plain` or absent leaves it |
 | `markdown` | as `markup` with format fixed to markdown |
 | `cell` | a whole token keeps a number, boolean or date as-is; every other result is written `{ "value": s }`, so user data can never become a formula. "Date" means: the token's path is DECLARED `date` and the result (after filters) is a valid `date` string (section 3) -- a date-shaped value of a `string` variable is wrapped, and `{{ d \| date:"yyyy" }}` is text. A valid date cannot begin with `=`. A literal (token-free) cell is the author's and is left as written |
@@ -339,10 +339,13 @@ index, `**` for zero or more. **Anything not listed refuses tokens**
 
 Wrong use of an image field is `TOKEN_IMAGE_FIELD`.
 
-**`{page}` is refused rather than escaped** because neither fine-print nor
-last-word has an escape for it: both replace the literal text in a band. A refusal
-is loud; any lookalike substitution would print a different character. When a
-writer gains an escape, the band encoding uses it.
+**A band field is refused rather than escaped** because neither fine-print nor
+last-word has an escape for it: both turn the literal text into a live value in a
+band, in a one-line slot and in a blocks band's run text alike, so a blocks band's
+run text is `band` too. The list is one for both writers, including the ones a
+writer writes literally today (fine-print's `{date}`), so a value that refuses in
+one refuses in the other. A refusal is loud; any lookalike substitution would print
+a different character. When a writer gains an escape, the band encoding uses it.
 
 **The markdown escape is CommonMark's, and the profile does not force `plain`.**
 dark-slide's PPTX writer (`MarkdownInline`, in all three of its languages) does

fancy_template-0.4.0/profiles/fine-print.json

@@ -0,0 +1,50 @@
+{
+  "writer": "fine-print",
+  "schema": "fine-print 0.3",
+  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, color, font, fonts, page geometry and every style field are deliberately absent. First match wins, so a band's own patterns come before the generic text ones. Every band slot and a blocks band's run text refuse a value holding a field token ({page}, {section}, {date}, ...): fine-print resolves them there and has no escape.",
+  "fields": [
+    { "path": "title", "encode": "text" },
+    { "path": "page.header.left", "encode": "band" },
+    { "path": "page.header.center", "encode": "band" },
+    { "path": "page.header.right", "encode": "band" },
+    { "path": "page.footer.left", "encode": "band" },
+    { "path": "page.footer.center", "encode": "band" },
+    { "path": "page.footer.right", "encode": "band" },
+    { "path": "page.firstHeader.left", "encode": "band" },
+    { "path": "page.firstHeader.center", "encode": "band" },
+    { "path": "page.firstHeader.right", "encode": "band" },
+    { "path": "page.firstFooter.left", "encode": "band" },
+    { "path": "page.firstFooter.center", "encode": "band" },
+    { "path": "page.firstFooter.right", "encode": "band" },
+    { "path": "page.evenHeader.left", "encode": "band" },
+    { "path": "page.evenHeader.center", "encode": "band" },
+    { "path": "page.evenHeader.right", "encode": "band" },
+    { "path": "page.evenFooter.left", "encode": "band" },
+    { "path": "page.evenFooter.center", "encode": "band" },
+    { "path": "page.evenFooter.right", "encode": "band" },
+    { "path": "blocks.*.page.header.left", "encode": "band" },
+    { "path": "blocks.*.page.header.center", "encode": "band" },
+    { "path": "blocks.*.page.header.right", "encode": "band" },
+    { "path": "blocks.*.page.footer.left", "encode": "band" },
+    { "path": "blocks.*.page.footer.center", "encode": "band" },
+    { "path": "blocks.*.page.footer.right", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.left", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.center", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.right", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.left", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.center", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.right", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.left", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.center", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.right", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.left", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.center", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.right", "encode": "band" },
+    { "path": "page.*.blocks.**.runs.*.text", "encode": "band" },
+    { "path": "blocks.*.page.*.blocks.**.runs.*.text", "encode": "band" },
+    { "path": "**.runs.*.text", "encode": "text" },
+    { "path": "**.blocks.*.text", "encode": "text" },
+    { "path": "**.blocks.*.alt", "encode": "text" },
+    { "path": "**.blocks.*.src", "encode": "image", "mime": ["image/png", "image/jpeg"] }
+  ]
+}

{fancy_template-0.3.0 → fancy_template-0.4.0}/profiles/last-word.json

@@ -1,9 +1,10 @@
 {
   "writer": "last-word",
   "schema": "last-word 0.x (Doc model shared with fine-print)",
-  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, chart option, color, font, fonts, page geometry and every style field are deliberately absent. Band slots refuse a value containing {page}/{pages}: last-word writes them as PAGE and NUMPAGES fields with str_replace and has no escape.",
+  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, chart option, color, font, fonts, page geometry and every style field are deliberately absent. First match wins, so a band's own patterns come before the generic text ones. Band slots and a blocks band's run text refuse a value holding a field token ({page}, {section}, {date}, ...): last-word writes them as live Word fields and has no escape.",
   "fields": [
     { "path": "title", "encode": "text" },
+    { "path": "page.*.blocks.**.runs.*.text", "encode": "band" },
     { "path": "**.runs.*.text", "encode": "text" },
     { "path": "**.blocks.*.text", "encode": "text" },
     { "path": "**.blocks.*.alt", "encode": "text" },

{fancy_template-0.3.0 → fancy_template-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-template"
-version = "0.3.0"
+version = "0.4.0"
 description = "Document templates for the Fancy document writers: a writer document with {{ tokens }} and JSON directives, plus a declaration of the data it needs. inspect() at save time, validate_data() before render, render() to plain writer JSON. No code execution, no includes, bounded everywhere. One spec, three runtimes, held to a shared conformance table."
 readme = "README.md"
 # 3.11, matching every other Fancy Python package (3.10 reaches end of life on

{fancy_template-0.3.0 → fancy_template-0.4.0}/src/fancy_template/__init__.py

@@ -49,7 +49,7 @@ __all__ = [
     "validate_data",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 
 def inspect(template: Any, options: dict[str, Any] | None = None) -> dict[str, Any]:

{fancy_template-0.3.0 → fancy_template-0.4.0}/src/fancy_template/_renderer.py

@@ -9,6 +9,7 @@ is refused before it is built rather than after.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Callable, Iterator
 from typing import Any
 
@@ -23,6 +24,13 @@ from ._limits import Limits
 from ._profile import Profile
 from ._scanner import LOOP_HEADS, is_digits, path_only, tokenize
 
+# A writer's band field, the grammar last-word's Schema::FIELD_TOKEN and
+# fine-print's share. Run over a VALUE, never over template text; a value holding
+# one is refused (SPEC.md section 9).
+BAND_FIELD = re.compile(
+    r'\{(?:(?:page|pages|section|sectionpages|author|title|filename)|(?:date|time)(?::[^{}"\\]+)?)\}'
+)
+
 
 def escape_markdown(s: str) -> str:
     """CommonMark: a backslash before every ASCII punctuation character (SPEC.md section 9)."""
@@ -232,7 +240,7 @@ class Renderer:
             except TemplateError as e:
                 raise TemplateError(e.code, path, variable) from None
 
-            if field["encode"] == "band" and ("{page}" in piece or "{pages}" in piece):
+            if field["encode"] == "band" and BAND_FIELD.search(piece):
                 raise TemplateError("VALUE_PAGE_FIELD", path, variable)
             out += escape(piece)
 

fancy_template-0.4.0/tests/test_band_value.py

@@ -0,0 +1,92 @@
+"""User data must not become a live field: a value holding a band token is refused,
+never rewritten. The PHP and TypeScript legs hold the same rows."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from fancy_template import TemplateError, render
+
+BANDS = ["header", "footer", "firstHeader", "firstFooter", "evenHeader", "evenFooter"]
+
+
+def tpl(writer: str, document: dict[str, Any]) -> dict[str, Any]:
+    return {"fancyTemplate": 1, "writer": writer, "variables": {"v": {"type": "string"}}, "document": document}
+
+
+def code(template: dict[str, Any], value: str) -> str | None:
+    try:
+        render(template, {"v": value})
+    except TemplateError as e:
+        return e.code
+    return None
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "{page}",
+        "{pages}",
+        "{section}",
+        "{sectionpages}",
+        "{author}",
+        "{title}",
+        "{filename}",
+        "{date}",
+        "{time}",
+        "see {section} here",
+        "{date:d MMMM yyyy}",
+        "{time:HH:mm}",
+    ],
+)
+@pytest.mark.parametrize("writer", ["fine-print", "last-word"])
+def test_refuses_a_band_value_holding_any_field_token(writer: str, value: str) -> None:
+    assert code(tpl(writer, {"blocks": [], "page": {"footer": {"left": "{{ v }}"}}}), value) == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("value", ["{Page}", "{pagex}", "x{ page }", "{date:}", "{date:a{b}", "no braces"])
+def test_keeps_a_value_that_is_only_brace_shaped(value: str) -> None:
+    out = render(tpl("fine-print", {"blocks": [], "page": {"footer": {"left": "{{ v }}"}}}), {"v": value})
+    assert out["page"]["footer"]["left"] == value
+
+
+@pytest.mark.parametrize("key", BANDS)
+@pytest.mark.parametrize("slot", ["left", "center", "right"])
+def test_every_fine_print_band_slot(key: str, slot: str) -> None:
+    template = tpl("fine-print", {"blocks": [], "page": {key: {slot: "{{ v }}"}}})
+    assert code(template, "Ada") is None
+    assert code(template, "{section}") == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("key", BANDS)
+def test_a_band_on_a_fine_print_break(key: str) -> None:
+    template = tpl(
+        "fine-print",
+        {"blocks": [{"type": "pageBreak", "page": {"orientation": "landscape", key: {"left": "{{ v }}"}}}]},
+    )
+    assert code(template, "Ada") is None
+    assert code(template, "{pages}") == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("writer", ["fine-print", "last-word"])
+def test_a_blocks_band_and_a_table_cell_in_it(writer: str) -> None:
+    para = {"type": "paragraph", "runs": [{"text": "{{ v }}"}]}
+    cell = {"type": "table", "rows": [{"cells": [{"blocks": [para]}]}]}
+    for block in (para, cell):
+        assert (
+            code(tpl(writer, {"blocks": [], "page": {"footer": {"blocks": [block]}}}), "see {page}")
+            == "VALUE_PAGE_FIELD"
+        )
+
+
+def test_a_body_run_keeps_a_token_shaped_value_literal() -> None:
+    assert code(tpl("fine-print", {"blocks": [{"type": "paragraph", "runs": [{"text": "{{ v }}"}]}]}), "{page}") is None
+
+
+def test_page_geometry_on_a_break_stays_closed_to_tokens() -> None:
+    assert (
+        code(tpl("fine-print", {"blocks": [{"type": "pageBreak", "page": {"orientation": "{{ v }}"}}]}), "landscape")
+        is not None
+    )

{fancy_template-0.3.0 → fancy_template-0.4.0}/tests/test_conformance.py

@@ -24,7 +24,7 @@ from template_runner import run_template_case
 # version (package.json's range + the committed lockfile; composer.json's exact
 # require-dev). Move all of them together, and only after re-running the tables in
 # every runtime; the tests below fail otherwise.
-PINNED_SUITE_VERSION = "0.36.0"
+PINNED_SUITE_VERSION = "0.44.0"
 
 SUITES = (
     "template/tokenize",

fancy_template-0.3.0/profiles/fine-print.json

@@ -1,18 +0,0 @@
-{
-  "writer": "fine-print",
-  "schema": "fine-print 0.3",
-  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, color, font, fonts, page geometry and every style field are deliberately absent. Band slots refuse a value containing {page}/{pages}: fine-print replaces them with str_replace and has no escape.",
-  "fields": [
-    { "path": "title", "encode": "text" },
-    { "path": "**.runs.*.text", "encode": "text" },
-    { "path": "**.blocks.*.text", "encode": "text" },
-    { "path": "**.blocks.*.alt", "encode": "text" },
-    { "path": "**.blocks.*.src", "encode": "image", "mime": ["image/png", "image/jpeg"] },
-    { "path": "page.header.left", "encode": "band" },
-    { "path": "page.header.center", "encode": "band" },
-    { "path": "page.header.right", "encode": "band" },
-    { "path": "page.footer.left", "encode": "band" },
-    { "path": "page.footer.center", "encode": "band" },
-    { "path": "page.footer.right", "encode": "band" }
-  ]
-}