fancy-template 0.2.0__py3-none-any.whl

fancy_template/__init__.py

@@ -0,0 +1,121 @@
+"""fancy-template -- document templates for the Fancy writers.
+
+One specification (``SPEC.md`` in the repository root, normative), three
+implementations: this one, ``@particle-academy/fancy-template`` (TypeScript) and
+``particle-academy/fancy-template`` (PHP). All three assert the same
+``template/*`` rows from ``fancy-conformance``.
+
+    >>> from fancy_template import inspect, render
+    >>> template = {"fancyTemplate": 1, "writer": "fine-print",
+    ...     "variables": {"name": {"type": "string", "required": True}},
+    ...     "document": {"blocks": [{"type": "paragraph", "runs": [{"text": "Dear {{ name }}"}]}]}}
+    >>> inspect(template)["ok"]
+    True
+    >>> render(template, {"name": "Ada"})["blocks"][0]["runs"][0]["text"]
+    'Dear Ada'
+
+The output is plain writer JSON, so the writers never depend on this package and
+stay zero-dependency. Pass it through the writer's own validate and write.
+
+Missing data is LOUD: ``render`` raises :class:`TemplateError` with a stable
+``code``, a JSON Pointer ``path`` into the template and the ``variable`` path --
+never a data value.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._declarations import apply_defaults, validate_members
+from ._errors import TemplateError
+from ._inspector import Inspector, declared_variables
+from ._json import first_too_deep, plain
+from ._limits import DEFAULT_LIMITS, Limits, limits_from
+from ._profile import Profile
+from ._renderer import Renderer
+from ._scanner import tokenize as _scan
+
+__all__ = [
+    "DEFAULT_LIMITS",
+    "TemplateError",
+    "inspect",
+    "preview",
+    "render",
+    "tokenize",
+    "validate_data",
+]
+
+__version__ = "0.2.0"
+
+
+def inspect(template: Any, options: dict[str, Any] | None = None) -> dict[str, Any]:
+    """``{"ok": bool, "issues": [{code, path, variable?}]}`` -- at SAVE time, no data."""
+    limits = limits_from(options)
+    is_plain, value = plain(template)
+    issues = Inspector.run(value, limits) if is_plain else [{"code": "TEMPLATE_SHAPE", "path": ""}]
+    return {"ok": not issues, "issues": issues}
+
+
+def validate_data(template: Any, data: Any, options: dict[str, Any] | None = None) -> list[dict[str, str]]:
+    """Data errors in declaration order; empty when valid."""
+    return _prepare(template, data, limits_from(options))[1]
+
+
+def render(template: Any, data: Any, options: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Render a template with data: inspect, then validate the data, then render.
+
+    Raises :class:`TemplateError` with the first failure (SPEC.md section 11).
+    """
+    limits = limits_from(options)
+    is_plain, value = plain(template)
+    if not is_plain or not isinstance(value, dict):
+        raise TemplateError("TEMPLATE_SHAPE", "")
+    issues = Inspector.run(value, limits)
+    if issues:
+        first = issues[0]
+        raise TemplateError(first["code"], first["path"], first.get("variable"))
+
+    defaulted, errors = _prepare(value, data, limits)
+    if errors:
+        raise TemplateError(errors[0]["code"], errors[0]["path"])
+
+    profile = Profile.for_writer(value["writer"])
+    assert profile is not None
+    return Renderer.run(value["document"], defaulted, declared_variables(value), profile, limits)
+
+
+def preview(template: Any, options: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Render with each variable's ``example``, falling back to its ``default``.
+
+    A required variable with neither fails, rather than inventing a value the
+    real data could not produce (template/resolve 0202).
+    """
+    data: dict[str, Any] = {}
+    is_plain, value = plain(template)
+    variables = value.get("variables") if is_plain and isinstance(value, dict) else None
+    if isinstance(variables, dict):
+        for name, decl in variables.items():
+            if isinstance(decl, dict) and "example" in decl:
+                data[name] = decl["example"]
+    return render(template, data, options)
+
+
+def tokenize(text: str, options: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    """Split one string into text and token parts (SPEC.md section 5)."""
+    return _scan(text, limits_from(options).token_length)
+
+
+def _prepare(template: Any, data: Any, limits: Limits) -> tuple[dict[str, Any], list[dict[str, str]]]:
+    plain_template, t = plain(template)
+    plain_data, d = plain(data)
+    if not plain_data:
+        return {}, [{"path": "", "code": "DATA_TYPE"}]
+    too_deep = first_too_deep(d, limits.depth)
+    if too_deep is not None:
+        return {}, [{"path": too_deep, "code": "DATA_TOO_DEEP"}]
+    if not isinstance(d, dict):
+        return {}, [{"path": "", "code": "DATA_TYPE"}]
+
+    members = declared_variables(t) if plain_template else {}
+    errors = validate_members(d, members, "")
+    return apply_defaults(d, members), errors

fancy_template/_dates.py

@@ -0,0 +1,172 @@
+"""The ``date`` type and the ``date:"pattern"`` filter (SPEC.md sections 3 and 7).
+
+English names only, no time-zone database, no locale, never ``datetime``
+arithmetic: a certificate's date is the date the issuer wrote, and an offset is
+carried but never applied.
+"""
+
+from __future__ import annotations
+
+import re
+
+_MONTHS = (
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+)
+_DAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
+
+#: Pattern letter => allowed run lengths.
+_RUNS: dict[str, tuple[int, ...]] = {
+    "y": (2, 4),
+    "M": (1, 2, 3, 4),
+    "d": (1, 2),
+    "E": (3, 4),
+    "H": (1, 2),
+    "h": (1, 2),
+    "m": (2,),
+    "s": (2,),
+    "a": (1,),
+}
+
+# Data, not template text, anchored with no nested quantifier: linear.
+# `[0-9]` and re.ASCII, never a bare `\d`: in Python `\d` matches every Unicode
+# digit, so a date spelled in Arabic-Indic digits would be one here and in no other leg. fullmatch,
+# never `$`, which also matches before a trailing newline.
+_ISO = re.compile(
+    r"([0-9]{4})-([0-9]{2})-([0-9]{2})"
+    r"(?:T([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.[0-9]+)?)?(Z|[+-]([0-9]{2}):([0-9]{2}))?)?",
+    re.ASCII,
+)
+
+CivilDate = dict[str, int]
+Piece = tuple[str, "str | int"]
+
+
+def parse_date(value: object) -> CivilDate | None:
+    """Parse an ISO date or date-time. None when it is not one, or not a real calendar date and time."""
+    if not isinstance(value, str):
+        return None
+    m = _ISO.fullmatch(value)
+    if m is None:
+        return None
+    y, mo, d = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    hour = int(m.group(4)) if m.group(4) is not None else 0
+    minute = int(m.group(5)) if m.group(5) is not None else 0
+    second = int(m.group(6)) if m.group(6) is not None else 0
+    if mo < 1 or mo > 12 or d < 1 or d > _days_in(y, mo):
+        return None
+    if hour > 23 or minute > 59 or second > 59:
+        return None
+    if m.group(8) is not None and (int(m.group(8)) > 23 or int(m.group(9)) > 59):
+        return None
+    return {"y": y, "m": mo, "d": d, "H": hour, "i": minute, "s": second}
+
+
+def _is_ascii_alpha(c: str) -> bool:
+    return "A" <= c <= "Z" or "a" <= c <= "z"
+
+
+def compile_pattern(pattern: str) -> list[Piece] | None:
+    """Compile a pattern to pieces, or None if invalid. Forward-only; quotes are literal, '' is one quote."""
+    out: list[Piece] = []
+    n = len(pattern)
+    i = 0
+    while i < n:
+        c = pattern[i]
+        if c == "'":
+            if i + 1 < n and pattern[i + 1] == "'":
+                out.append(("lit", "'"))
+                i += 2
+                continue
+            i += 1
+            lit = ""
+            while True:
+                if i >= n:
+                    return None
+                if pattern[i] == "'":
+                    if i + 1 < n and pattern[i + 1] == "'":
+                        lit += "'"
+                        i += 2
+                        continue
+                    i += 1
+                    break
+                lit += pattern[i]
+                i += 1
+            out.append(("lit", lit))
+            continue
+        if _is_ascii_alpha(c):
+            run = 1
+            while i + run < n and pattern[i + run] == c:
+                run += 1
+            if c not in _RUNS or run not in _RUNS[c]:
+                return None
+            out.append((c, run))
+            i += run
+            continue
+        out.append(("lit", c))
+        i += 1
+    return out
+
+
+def format_date(date: CivilDate, pieces: list[Piece]) -> str:
+    out = ""
+    for kind, value in pieces:
+        if kind == "lit":
+            out += str(value)
+        elif kind == "y":
+            out += f"{date['y']:04d}" if value == 4 else f"{date['y'] % 100:02d}"
+        elif kind == "M":
+            name = _MONTHS[date["m"] - 1]
+            out += {4: name, 3: name[:3], 2: f"{date['m']:02d}"}.get(int(value), str(date["m"]))
+        elif kind == "d":
+            out += f"{date['d']:02d}" if value == 2 else str(date["d"])
+        elif kind == "E":
+            day = _DAYS[_weekday(date)]
+            out += day if value == 4 else day[:3]
+        elif kind == "H":
+            out += f"{date['H']:02d}" if value == 2 else str(date["H"])
+        elif kind == "h":
+            h = _twelve(date["H"])
+            out += f"{h:02d}" if value == 2 else str(h)
+        elif kind == "m":
+            out += f"{date['i']:02d}"
+        elif kind == "s":
+            out += f"{date['s']:02d}"
+        elif kind == "a":
+            out += "AM" if date["H"] < 12 else "PM"
+    return out
+
+
+def _twelve(hour: int) -> int:
+    h = hour % 12
+    return 12 if h == 0 else h
+
+
+def _weekday(date: CivilDate) -> int:
+    """0 = Monday, from days since the civil epoch (Howard Hinnant's algorithm)."""
+    y = date["y"] - (1 if date["m"] <= 2 else 0)
+    # Truncating division, as in C: Python's // floors, which differs for negatives.
+    era = int((y if y >= 0 else y - 399) / 400)
+    yoe = y - era * 400
+    mp = (date["m"] + 9) % 12
+    doy = (153 * mp + 2) // 5 + date["d"] - 1
+    doe = yoe * 365 + yoe // 4 - yoe // 100 + doy
+    days = era * 146097 + doe - 719468
+    # 1970-01-01 was a Thursday (3). Python's % is already non-negative.
+    return (days % 7 + 3) % 7
+
+
+def _days_in(y: int, m: int) -> int:
+    if m == 2:
+        return 29 if y % 4 == 0 and (y % 100 != 0 or y % 400 == 0) else 28
+    return 30 if m in (4, 6, 9, 11) else 31

fancy_template/_declarations.py

@@ -0,0 +1,188 @@
+"""Variable declarations: checking them (inspect) and checking data against
+them (validate_data). SPEC.md sections 3 and 4."""
+
+from __future__ import annotations
+
+import copy
+import math
+from typing import Any
+
+from ._dates import parse_date
+from ._json import code_points, image_type, is_number, pointer
+from ._scanner import is_name
+
+TYPES = ("string", "number", "integer", "boolean", "date", "image", "array", "object")
+
+Issue = dict[str, str]
+
+
+def _is_count(v: Any) -> bool:
+    """A non-negative integer as section 3 defines integer: an integral VALUE, so 3.0 counts."""
+    return is_number(v) and math.isfinite(v) and float(v).is_integer() and v >= 0
+
+
+def inspect_decl(decl: Any, path: str, issues: list[Issue]) -> None:
+    """Issues in one declaration, its own keys before its nested declarations."""
+    if not isinstance(decl, dict) or len(decl) == 0 or "type" not in decl:
+        issues.append({"code": "DECL_INVALID", "path": path})
+        return
+    type_ = decl["type"]
+    if not isinstance(type_, str) or type_ not in TYPES:
+        issues.append({"code": "DECL_INVALID", "path": pointer(path, "type")})
+        return
+
+    nested: list[tuple[Any, str]] = []
+    for key, value in decl.items():
+        at = pointer(path, key)
+        if key == "type":
+            bad = False
+        elif key == "required":
+            bad = not isinstance(value, bool)
+        elif key == "description":
+            bad = not isinstance(value, str)
+        elif key == "enum":
+            bad = (
+                type_ not in ("string", "number", "integer")
+                or not isinstance(value, list)
+                or len(value) == 0
+                or not all(type_ok(type_, v) for v in value)
+            )
+        elif key == "maxLength":
+            bad = type_ not in ("string", "date", "image") or not _is_count(value)
+        elif key == "maxItems":
+            bad = type_ != "array" or not _is_count(value)
+        elif key == "items":
+            bad = type_ != "array"
+        elif key == "properties":
+            bad = type_ != "object" or not isinstance(value, dict)
+        elif key in ("default", "example"):
+            bad = len(validate(value, decl, "")) > 0
+        else:
+            bad = True
+        if bad:
+            issues.append({"code": "DECL_INVALID", "path": at})
+            continue
+        if key == "items":
+            nested.append((value, at))
+        if key == "properties":
+            for name, sub in value.items():
+                if not is_name(name):
+                    issues.append({"code": "DECL_INVALID", "path": pointer(at, name)})
+                    continue
+                nested.append((sub, pointer(at, name)))
+
+    if (type_ == "array" and "items" not in decl) or (type_ == "object" and "properties" not in decl):
+        issues.append({"code": "DECL_INVALID", "path": path})
+
+    for sub, at in nested:
+        inspect_decl(sub, at, issues)
+
+
+def usable(decl: Any) -> bool:
+    """Whether a declaration passed inspect, so that validation may lean on its shape."""
+    issues: list[Issue] = []
+    inspect_decl(decl, "", issues)
+    return not issues
+
+
+def validate(value: Any, decl: dict[str, Any], path: str) -> list[dict[str, str]]:
+    """Validate one PRESENT value against a declaration."""
+    type_ = decl["type"]
+    if not type_ok(type_, value):
+        return [{"path": path, "code": "DATA_TYPE"}]
+    if type_ == "date" and parse_date(value) is None:
+        return [{"path": path, "code": "DATA_FORMAT"}]
+    if type_ == "image" and image_type(value) is None:
+        return [{"path": path, "code": "DATA_FORMAT"}]
+
+    errors: list[dict[str, str]] = []
+    enum = decl.get("enum")
+    if enum is not None and not _in_enum(value, enum):
+        errors.append({"path": path, "code": "DATA_ENUM"})
+    max_length = decl.get("maxLength")
+    if is_number(max_length) and isinstance(value, str) and code_points(value) > max_length:
+        errors.append({"path": path, "code": "DATA_MAX_LENGTH"})
+    if type_ == "array" and isinstance(value, list):
+        max_items = decl.get("maxItems")
+        if is_number(max_items) and len(value) > max_items:
+            errors.append({"path": path, "code": "DATA_MAX_ITEMS"})
+        items = decl.get("items")
+        if isinstance(items, dict):
+            for i, item in enumerate(value):
+                errors.extend(validate(item, items, pointer(path, i)))
+    if type_ == "object" and isinstance(value, dict):
+        properties = decl.get("properties")
+        if isinstance(properties, dict):
+            errors.extend(validate_members(value, properties, path))
+    return errors
+
+
+def validate_members(obj: dict[str, Any], members: dict[str, Any], path: str) -> list[dict[str, str]]:
+    """Validate an object's declared members, in declaration order."""
+    errors: list[dict[str, str]] = []
+    for name, decl in members.items():
+        if not usable(decl):
+            continue
+        at = pointer(path, name)
+        if name not in obj:
+            if "default" not in decl and decl.get("required") is True:
+                errors.append({"path": at, "code": "DATA_REQUIRED"})
+            continue
+        errors.extend(validate(obj[name], decl, at))
+    return errors
+
+
+def apply_defaults(obj: dict[str, Any], members: dict[str, Any]) -> dict[str, Any]:
+    """Fill absent members that declare a default, recursively (SPEC.md section 4)."""
+    for name, decl in members.items():
+        if not isinstance(decl, dict):
+            continue
+        if name not in obj and "default" in decl:
+            # A copy: the default is the template's, and must not be edited in place below.
+            obj[name] = copy.deepcopy(decl["default"])
+        if name not in obj:
+            continue
+        current = obj[name]
+        properties = decl.get("properties")
+        if decl.get("type") == "object" and isinstance(properties, dict) and isinstance(current, dict):
+            obj[name] = apply_defaults(current, properties)
+        items = decl.get("items")
+        if (
+            decl.get("type") == "array"
+            and isinstance(items, dict)
+            and items.get("type") == "object"
+            and isinstance(items.get("properties"), dict)
+            and isinstance(current, list)
+        ):
+            for i, item in enumerate(current):
+                if isinstance(item, dict):
+                    current[i] = apply_defaults(item, items["properties"])
+    return obj
+
+
+def type_ok(type_: str, v: Any) -> bool:
+    if type_ in ("string", "date", "image"):
+        return isinstance(v, str)
+    if type_ == "number":
+        return is_number(v) and math.isfinite(v)
+    if type_ == "integer":
+        return is_number(v) and math.isfinite(v) and float(v).is_integer()
+    if type_ == "boolean":
+        return isinstance(v, bool)
+    if type_ == "array":
+        return isinstance(v, list)
+    if type_ == "object":
+        return isinstance(v, dict)
+    return False
+
+
+def _in_enum(value: Any, candidates: Any) -> bool:
+    if not isinstance(candidates, list):
+        return False
+    for c in candidates:
+        if isinstance(value, str) and isinstance(c, str) and value == c:
+            return True
+        # Compared by type AND value: `True == 1` is True in Python and must not be here.
+        if is_number(value) and is_number(c) and value == c:
+            return True
+    return False

fancy_template/_errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+
+class TemplateError(Exception):
+    """Every refusal this package makes (SPEC.md section 6).
+
+    A stable ``code``, a JSON Pointer ``path`` into the TEMPLATE, and optionally
+    the ``variable`` PATH a token named. Never a data value, in the message or
+    anywhere else (plan section 5): a certificate's recipient name is personal
+    data, and an error is the thing that gets logged, shown to an admin and
+    pasted into an issue.
+    """
+
+    def __init__(self, code: str, path: str, variable: str | None = None) -> None:
+        where = "the root" if path == "" else path
+        what = "" if variable is None else f" (variable `{variable}`)"
+        super().__init__(f"{code} at {where}{what}")
+        self.code = code
+        self.path = path
+        self.variable = variable
+
+    def to_dict(self) -> dict[str, str]:
+        out = {"code": self.code, "path": self.path}
+        if self.variable is not None:
+            out["variable"] = self.variable
+        return out

fancy_template/_filters.py

@@ -0,0 +1,118 @@
+"""The fixed filter list (SPEC.md section 7).
+
+Not extensible from a template, and not from a host either in v1: every filter
+is a conformance-pinned behaviour, and a host-registered one would be a fourth
+dialect.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from ._dates import compile_pattern, format_date, parse_date
+from ._errors import TemplateError
+from ._json import is_number
+from ._numbers import CURRENCIES, fixed, money, to_js_string
+from ._scanner import is_digits
+
+
+class _Absent:
+    """The absent value. A private singleton rather than a magic string because
+    data can contain any string -- a sentinel spelled in characters is one a
+    hostile value can forge -- and nothing that went through ``plain()`` is ever
+    an instance of this class."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "ABSENT"
+
+
+ABSENT: Final = _Absent()
+
+FILTER_NAMES = ("default", "upper", "lower", "number", "money", "date", "join")
+
+
+def check_filter(filt: dict[str, str]) -> str | None:
+    """Static check of one filter. None when fine, else the issue code."""
+    name = filt["name"]
+    if name not in FILTER_NAMES:
+        return "FILTER_UNKNOWN"
+    arg = filt.get("arg")
+    if name == "default":
+        ok = arg is not None
+    elif name in ("upper", "lower"):
+        ok = arg is None
+    elif name == "number":
+        ok = arg is not None and is_digits(arg) and len(arg) <= 2 and int(arg) <= 10
+    elif name == "money":
+        ok = arg is not None and arg in CURRENCIES
+    elif name == "date":
+        ok = arg is not None and compile_pattern(arg) is not None
+    else:  # join
+        ok = True
+    return None if ok else "FILTER_ARG"
+
+
+def _input() -> TemplateError:
+    return TemplateError("FILTER_INPUT", "")
+
+
+def scalar_text(value: Any) -> str:
+    """A scalar as text (SPEC.md section 6). Arrays and objects are not scalars."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):  # before int: bool IS an int in Python
+        return "true" if value else "false"
+    if is_number(value):
+        return to_js_string(value)
+    raise TemplateError("TEMPLATE_NOT_SCALAR", "")
+
+
+def _ascii_case(s: str, upper: bool) -> str:
+    # str.upper() is Unicode-aware ("ß".upper() is "SS"); the spec maps ASCII only.
+    if upper:
+        return "".join(chr(ord(c) - 32) if "a" <= c <= "z" else c for c in s)
+    return "".join(chr(ord(c) + 32) if "A" <= c <= "Z" else c for c in s)
+
+
+def apply_filter(filt: dict[str, str], value: Any) -> Any:
+    """Apply one filter. ``value`` may be ABSENT. Raises TemplateError with an empty path."""
+    name = filt["name"]
+    arg = filt.get("arg")
+
+    if name == "default":
+        return arg if value is ABSENT or value is None else value
+    if value is ABSENT:
+        raise TemplateError("TEMPLATE_MISSING", "")
+
+    if name == "upper":
+        return _ascii_case(scalar_text(value), True)
+    if name == "lower":
+        return _ascii_case(scalar_text(value), False)
+    if name == "number":
+        if not is_number(value):
+            raise _input()
+        return fixed(value, int(arg or "0"))
+    if name == "money":
+        minor = value
+        if isinstance(minor, float) and minor.is_integer() and abs(minor) < 2**53:
+            minor = int(minor)
+        if isinstance(minor, bool) or not isinstance(minor, int):
+            raise _input()
+        return money(minor, str(arg))
+    if name == "date":
+        date = parse_date(value)
+        pieces = compile_pattern(str(arg))
+        if date is None or pieces is None:
+            raise _input()
+        return format_date(date, pieces)
+    # join
+    if not isinstance(value, list):
+        raise _input()
+    parts = []
+    for item in value:
+        if item is None or isinstance(item, (dict, list)):
+            raise _input()
+        parts.append(scalar_text(item))
+    return (", " if arg is None else arg).join(parts)