fancy-template 0.2.0__py3-none-any.whl

fancy_template/_scanner.py

@@ -0,0 +1,284 @@
+"""Splits one string into text and ``{{ }}`` tokens (SPEC.md section 5).
+
+Hand-written and single-pass: every index only moves forward, and no regular
+expression ever runs over template text (plan section 5). Template text is
+authored by admins and agents and arrives over the wire, and a backtracking
+regex over it is a denial of service waiting for the right string.
+
+It scans UTF-8 BYTES, because the token-length bound is defined in bytes
+(SPEC.md section 10) and the three legs must refuse the same token at the same
+place. Every delimiter is ASCII, so a split never lands inside a character.
+
+Character classes are ASCII by hand: ``str.isalpha`` and ``str.isdigit`` are
+Unicode-aware, so ``"é".isalpha()`` and ``"٣".isdigit()`` are True and a name
+like ``café`` would parse here and nowhere else.
+
+Errors are raised as TemplateError with an empty path; the caller knows which
+field it was scanning and re-raises with the pointer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from ._errors import TemplateError
+
+LOOP_HEADS = ("$index", "$first", "$last")
+
+_OPEN = ord("{")
+_CLOSE = ord("}")
+_QUOTE = ord('"')
+_BACKSLASH = ord("\\")
+_SPACE = ord(" ")
+_TAB = ord("\t")
+
+
+def _is_alpha(c: int) -> bool:
+    return 0x41 <= c <= 0x5A or 0x61 <= c <= 0x7A
+
+
+def _is_digit(c: int) -> bool:
+    return 0x30 <= c <= 0x39
+
+
+def _is_name_char(c: int) -> bool:
+    return _is_alpha(c) or _is_digit(c) or c == 0x5F
+
+
+def _is_lower(c: int) -> bool:
+    return 0x61 <= c <= 0x7A
+
+
+def _is_bare(c: int) -> bool:
+    return _is_name_char(c) or c in (0x2E, 0x2B, 0x2D)
+
+
+def _syntax() -> TemplateError:
+    return TemplateError("TOKEN_SYNTAX", "")
+
+
+class _Cursor:
+    """A forward-only position in a byte string. Nothing here can move backwards."""
+
+    __slots__ = ("b", "i", "n")
+
+    def __init__(self, b: bytes) -> None:
+        self.b = b
+        self.i = 0
+        self.n = len(b)
+
+    def peek(self) -> int | None:
+        return self.b[self.i] if self.i < self.n else None
+
+    def advance(self) -> None:
+        self.i += 1
+
+    def done(self) -> bool:
+        return self.i >= self.n
+
+    def skip_ws(self) -> None:
+        # Spaces and tabs only. A newline is never whitespace inside a token.
+        while self.i < self.n and self.b[self.i] in (_SPACE, _TAB):
+            self.i += 1
+
+    def take_while(self, accept: Callable[[int], bool]) -> str:
+        start = self.i
+        while self.i < self.n and accept(self.b[self.i]):
+            self.i += 1
+        return self.b[start : self.i].decode("utf-8")
+
+
+def tokenize(text: str, token_length: int) -> list[dict[str, Any]]:
+    if "{{" not in text:
+        return [] if text == "" else [{"text": text}]
+
+    b = text.encode("utf-8")
+    n = len(b)
+    parts: list[dict[str, Any]] = []
+    buffer = ""
+    i = 0
+    while i < n:
+        open_at = b.find(b"{{", i)
+        if open_at == -1:
+            buffer += b[i:].decode("utf-8")
+            break
+        buffer += b[i:open_at].decode("utf-8")
+
+        start = open_at + 2
+        close = _find_close(b, start, n, token_length)
+        token = _parse_token(b[start:close])
+
+        if buffer != "":
+            parts.append({"text": buffer})
+            buffer = ""
+        parts.append(token)
+        i = close + 2
+
+    if buffer != "":
+        parts.append({"text": buffer})
+    return parts
+
+
+def count_tokens(text: str, token_length: int) -> int:
+    """How many tokens a string opens, stopping quietly at the first error (reported elsewhere)."""
+    if "{{" not in text:
+        return 0
+    b = text.encode("utf-8")
+    count = 0
+    i = 0
+    while True:
+        open_at = b.find(b"{{", i)
+        if open_at == -1:
+            break
+        count += 1
+        try:
+            i = _find_close(b, open_at + 2, len(b), token_length) + 2
+        except TemplateError:
+            break
+    return count
+
+
+def _find_close(b: bytes, start: int, n: int, limit: int) -> int:
+    """Index of the ``}}`` that closes a token whose inner text starts at ``start``."""
+    j = start
+    while True:
+        if j - start > limit:
+            raise TemplateError("TOKEN_TOO_LONG", "")
+        if j >= n:
+            raise TemplateError("TOKEN_UNCLOSED", "")
+        c = b[j]
+        if c == _QUOTE:
+            # A string literal: ``}}`` inside it does not close the token. An escape skips one byte.
+            j += 1
+            while j < n and b[j] != _QUOTE:
+                if j - start > limit:
+                    raise TemplateError("TOKEN_TOO_LONG", "")
+                j += 2 if b[j] == _BACKSLASH else 1
+            if j >= n:
+                if j - start > limit:
+                    raise TemplateError("TOKEN_TOO_LONG", "")
+                raise TemplateError("TOKEN_UNCLOSED", "")
+            j += 1
+            continue
+        if c == _CLOSE and j + 1 < n and b[j + 1] == _CLOSE:
+            return j
+        j += 1
+
+
+def _parse_token(inner: bytes) -> dict[str, Any]:
+    if all(c in (_SPACE, _TAB) for c in inner):
+        raise TemplateError("TOKEN_EMPTY", "")
+
+    p = _Cursor(inner)
+    p.skip_ws()
+    token: dict[str, Any] = {"literal": _string(p)} if p.peek() == _QUOTE else {"path": _path(p)}
+
+    filters: list[dict[str, str]] = []
+    while True:
+        p.skip_ws()
+        if p.done():
+            break
+        if p.peek() != ord("|"):
+            raise _syntax()
+        p.advance()
+        p.skip_ws()
+        name = p.take_while(_is_lower)
+        if name == "":
+            raise _syntax()
+        filt = {"name": name}
+        p.skip_ws()
+        if p.peek() == ord(":"):
+            p.advance()
+            p.skip_ws()
+            if p.peek() == _QUOTE:
+                filt["arg"] = _string(p)
+            else:
+                arg = p.take_while(_is_bare)
+                if arg == "":
+                    raise _syntax()
+                filt["arg"] = arg
+        filters.append(filt)
+
+    token["filters"] = filters
+    return token
+
+
+def _path(p: _Cursor) -> list[str]:
+    segments: list[str] = []
+    if p.peek() == ord("$"):
+        p.advance()
+        head = "$" + p.take_while(_is_name_char)
+        if head not in LOOP_HEADS:
+            raise _syntax()
+        segments.append(head)
+    else:
+        name = _name(p)
+        if name is None:
+            raise _syntax()
+        segments.append(name)
+
+    while p.peek() == ord("."):
+        p.advance()
+        digits = p.take_while(_is_digit)
+        if digits != "":
+            segments.append(digits)
+            continue
+        name = _name(p)
+        if name is None:
+            raise _syntax()
+        segments.append(name)
+    return segments
+
+
+def path_only(text: str) -> list[str] | None:
+    """Parse a whole string as a bare path, as ``$each`` takes one. None if it is not one."""
+    p = _Cursor(text.encode("utf-8"))
+    p.skip_ws()
+    try:
+        steps = _path(p)
+    except TemplateError:
+        return None
+    p.skip_ws()
+    return steps if p.done() else None
+
+
+def is_name(s: str) -> bool:
+    if s == "" or not s.isascii():
+        return False
+    b = s.encode("ascii")
+    if not (_is_alpha(b[0]) or b[0] == 0x5F):
+        return False
+    return all(_is_name_char(c) for c in b[1:])
+
+
+def is_digits(s: str) -> bool:
+    return s != "" and s.isascii() and all(_is_digit(c) for c in s.encode("ascii"))
+
+
+def _name(p: _Cursor) -> str | None:
+    c = p.peek()
+    if c is None or not (_is_alpha(c) or c == 0x5F):
+        return None
+    return p.take_while(_is_name_char)
+
+
+def _string(p: _Cursor) -> str:
+    p.advance()  # opening quote
+    out = bytearray()
+    while True:
+        c = p.peek()
+        if c is None:
+            raise _syntax()
+        p.advance()
+        if c == _QUOTE:
+            return out.decode("utf-8")
+        if c == _BACKSLASH:
+            nxt = p.peek()
+            if nxt not in (_QUOTE, _BACKSLASH):
+                raise _syntax()
+            assert nxt is not None
+            p.advance()
+            out.append(nxt)
+            continue
+        out.append(c)

fancy_template/profiles/dark-slide.json

@@ -0,0 +1,16 @@
+{
+  "writer": "dark-slide",
+  "schema": "dark-slide deck",
+  "notes": "Implemented in all three legs (phase 6). src and background.image are image fields so that a LITERAL local path is refused: dark-slide's ImageResolver reads local paths.",
+  "fields": [
+    { "path": "title", "encode": "text" },
+    { "path": "slides.*.elements.*.content", "encode": "markup" },
+    { "path": "slides.*.notes", "encode": "text" },
+    { "path": "slides.*.elements.*.alt", "encode": "text" },
+    { "path": "slides.*.elements.*.items.*", "encode": "text" },
+    { "path": "slides.*.elements.*.columns.*.label", "encode": "text" },
+    { "path": "slides.*.elements.*.rows.**", "encode": "text" },
+    { "path": "slides.*.elements.*.src", "encode": "image", "mime": ["image/png", "image/jpeg"] },
+    { "path": "slides.*.background.image", "encode": "image", "mime": ["image/png", "image/jpeg"] }
+  ]
+}

fancy_template/profiles/fine-print.json

@@ -0,0 +1,18 @@
+{
+  "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" }
+  ]
+}

fancy_template/profiles/holy-sheet.json

@@ -0,0 +1,11 @@
+{
+  "writer": "holy-sheet",
+  "schema": "holy-sheet workbook",
+  "notes": "Implemented in all three legs (phase 6). Every string result in a cell is written {value: s}, so user data can never become a formula. formula is deliberately absent.",
+  "fields": [
+    { "path": "sheets.*.name", "encode": "text" },
+    { "path": "sheets.*.rows.*.*", "encode": "cell" },
+    { "path": "sheets.*.cells.*", "encode": "cell" },
+    { "path": "sheets.*.cells.*.value", "encode": "text" }
+  ]
+}

fancy_template/profiles/last-word.json

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "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" }
+  ]
+}

fancy_template-0.2.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: fancy-template
+Version: 0.2.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
+Project-URL: Source, https://github.com/Particle-Academy/fancy-template
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic,certificate,cross-language,document,docx,particle-academy,pdf,pptx,template,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fancy-expr<2.0,>=0.2.0
+Description-Content-Type: text/markdown
+
+# fancy-template (Python)
+
+Document templates for the Fancy document writers: a writer document
+(fine-print, last-word, dark-slide, holy-sheet JSON) with `{{ tokens }}` in some
+string values and JSON directives on some array items, plus a declaration of the
+data it needs. **One specification, three implementations** (Python, TypeScript,
+PHP), all asserted against the same `template/*` table in `fancy-conformance`.
+
+```python
+from fancy_template import inspect, validate_data, render
+
+inspect(template)["issues"]  # at SAVE time, no data
+validate_data(template, data)  # before rendering
+doc = render(template, data)  # plain writer JSON, or raises TemplateError
+
+import holy_sheet
+
+holy_sheet.to_bytes(doc)  # the writer validates it again
+```
+
+## What it guarantees
+
+- **Missing data is loud.** An absent value raises `TemplateError` with a stable
+  `code`, a JSON Pointer `path` into the template and the `variable` path --
+  never the data value itself.
+- **No code execution, no includes.** Tokens are paths plus a fixed filter list;
+  `$if` is a sandboxed fancy-expr expression; data is reduced to plain JSON
+  before anything reads it, and no method of a host object is ever called.
+- **Profiles are allowlists.** Only listed fields take tokens. holy-sheet cells
+  write every string result as `{"value": s}`, so user data can never become a
+  formula; dark-slide escapes values for the element's markdown or html.
+- **Bounded everywhere**, with a stable error code per bound.
+
+## Where Python differs from its own instincts
+
+- `True == 1` is true in Python; here a boolean is never a number, and
+  `{"fancyTemplate": True}` is refused.
+- `str.isalpha`, `str.isdigit` and `re`'s `\d` are Unicode-aware; names, dates
+  and digits here are ASCII only, as in the other legs.
+- The recursion limit sits below the 4096 levels the other legs accept as JSON,
+  so every walk of unknown depth is iterative.
+
+The specification is `SPEC.md` in the repository root.

fancy_template-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+fancy_template/__init__.py,sha256=R1ltUO7ZH3TCEZ_-MHZJnGFvK6T70TwnYRvx7S7_US0,4776
+fancy_template/_dates.py,sha256=dlKm7PVppftAEWRKp2jzsjy78fZOWjcWP5iPpdDcVHM,5508
+fancy_template/_declarations.py,sha256=aFOuvwd2JeDHbTb22Q9pWCOdSJtrp35Dv2cI0kX76cE,7353
+fancy_template/_errors.py,sha256=1kHsoyHMFSElDxDG29kkWc9sjAnzEWLMRfJ2FsyvGno,1018
+fancy_template/_filters.py,sha256=xEh5tX5H5Cn4ToqNGYfu-m8sCnts_FazUb-EmMLSao8,3923
+fancy_template/_inspector.py,sha256=6_yp8W43cl0o3EXhsIZVu1Bc5vAUWmwYhDVR_To1G_M,14031
+fancy_template/_json.py,sha256=SnQP4e6reXBg-AV3Z4oojsKm2iQzQ_RAImRS82LsIXw,6616
+fancy_template/_limits.py,sha256=BOGIQE2pEw7ChoXE3xbI1ah_pqIQvz2q88tp0dlgGaw,1664
+fancy_template/_numbers.py,sha256=rsSh8LOUmX-q7CGUANJbovHI3Ja1_wiV53ZC6wUeq_c,4687
+fancy_template/_profile.py,sha256=pyhdFptrpdP3yvAC0NSfV9xF-nc9pQc1Y3jsn4gjZOc,3223
+fancy_template/_renderer.py,sha256=6SU5m6ZtMb2NjYXNbvF6cIJvzguEMKIdXiZT5ipaJvg,11027
+fancy_template/_scanner.py,sha256=-tzEUROCk0yV0tors7CWX43eKDtLmH6UGepXw2VCuL8,7979
+fancy_template/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fancy_template/profiles/dark-slide.json,sha256=9ve4c6BkILK4T_0spwSbEfJkeHmYO1gTTPHrSdWirsU,888
+fancy_template/profiles/fine-print.json,sha256=AEbv8WEziX5wNI0thMhtaszFOt0bgPLKGrPoOYhBKg0,977
+fancy_template/profiles/holy-sheet.json,sha256=ZUdvftUaVinQ6RVmBKVzykWVGVW3OnIeCvu2VIW9Bjg,483
+fancy_template/profiles/last-word.json,sha256=pSRQH3YFXrOiH0lZ3cc9fFKUdu4lRUMhzEWCWon106Q,1049
+fancy_template-0.2.0.dist-info/METADATA,sha256=MD4IWyld3XOObXg63rtkpZByfPwdjLZbmlhm6e6JEl4,3293
+fancy_template-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fancy_template-0.2.0.dist-info/licenses/LICENSE,sha256=nBlLZPUsduZ364Sj4w82nIJyfqWKvlBnDV3j-czSMnA,1073
+fancy_template-0.2.0.dist-info/RECORD,,

fancy_template-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fancy_template-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+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.