fancy-template 0.2.0__py3-none-any.whl

fancy_template/_numbers.py

@@ -0,0 +1,144 @@
+"""Numbers to text, the same in every runtime (SPEC.md sections 6 and 7).
+
+Everything starts from the SHORTEST round-trip decimal digits -- ``repr()`` of a
+float gives exactly those, the same digits JavaScript's ``Number.toString``
+picks -- and then works on the digits as a decimal string. Never ``str()`` of a
+float (``str(3.0)`` is ``"3.0"``, JavaScript writes ``"3"``), never ``round()``
+(banker's rounding, and it rounds the binary double: ``round(2.675, 2)`` is
+2.67), never ``format(x, ",")`` (locale-free but binary-rounded).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+#: Currency => (minor-unit exponent, prefix symbol or None for "CODE ").
+CURRENCIES: dict[str, tuple[int, str | None]] = {
+    "USD": (2, "$"),
+    "EUR": (2, "€"),
+    "GBP": (2, "£"),
+    "JPY": (0, "¥"),
+    "INR": (2, "₹"),
+    "KRW": (0, "₩"),
+    "CAD": (2, None),
+    "AUD": (2, None),
+    "NZD": (2, None),
+    "CHF": (2, None),
+    "CNY": (2, None),
+    "BRL": (2, None),
+    "MXN": (2, None),
+    "SEK": (2, None),
+    "NOK": (2, None),
+    "DKK": (2, None),
+    "PLN": (2, None),
+    "SGD": (2, None),
+    "HKD": (2, None),
+    "ZAR": (2, None),
+    "CLP": (0, None),
+    "VND": (0, None),
+    "ISK": (0, None),
+    "KWD": (3, None),
+    "BHD": (3, None),
+    "JOD": (3, None),
+    "OMR": (3, None),
+    "TND": (3, None),
+}
+
+
+def shortest(value: int | float) -> tuple[bool, str, int]:
+    """Shortest round-trip decimal of a finite number: (negative, digits, point).
+
+    The value is 0.DIGITS x 10^point, with no leading or trailing zeros in
+    DIGITS ("0" for zero). An int is exact (PHP's int path).
+    """
+    if value == 0:
+        return False, "0", 1
+    negative = value < 0
+    if isinstance(value, int):
+        text = str(abs(value))
+        return negative, text.rstrip("0"), len(text)
+    _sign, digit_tuple, exponent = Decimal(repr(abs(value))).as_tuple()
+    raw = "".join(str(d) for d in digit_tuple)
+    assert isinstance(exponent, int)
+    point = len(raw) + exponent
+    stripped = raw.lstrip("0")
+    point -= len(raw) - len(stripped)
+    digits = stripped.rstrip("0")
+    return negative, digits or "0", point
+
+
+def to_js_string(value: int | float) -> str:
+    """JavaScript's Number.prototype.toString, for a finite number."""
+    negative, digits, point = shortest(value)
+    if digits == "0":
+        return "0"
+    k = len(digits)
+    sign = "-" if negative else ""
+    if k <= point <= 21:
+        return sign + digits + "0" * (point - k)
+    if 0 < point <= 21:
+        return sign + digits[:point] + "." + digits[point:]
+    if -6 < point <= 0:
+        return sign + "0." + "0" * (-point) + digits
+    e = point - 1
+    exp = "e" + ("-" if e < 0 else "+") + str(abs(e))
+    return sign + (digits if k == 1 else digits[0] + "." + digits[1:]) + exp
+
+
+def fixed(value: int | float, decimals: int) -> str:
+    """``number:decimals`` -- decimal rounding, half away from zero, comma groups."""
+    negative, digits, point = shortest(value)
+    if digits == "0":
+        int_part, frac = "0", ""
+    elif point <= 0:
+        int_part, frac = "0", "0" * (-point) + digits
+    elif point >= len(digits):
+        int_part, frac = digits + "0" * (point - len(digits)), ""
+    else:
+        int_part, frac = digits[:point], digits[point:]
+
+    frac = frac.ljust(decimals + 1, "0")
+    round_up = frac[decimals] >= "5"
+    kept = int_part + frac[:decimals]
+    if round_up:
+        kept = _increment(kept)
+
+    whole = kept[: len(kept) - decimals].lstrip("0") or "0"
+    frac_part = kept[len(kept) - decimals :]
+    is_zero = (whole + frac_part).strip("0") == ""
+    out = _group(whole) + ("." + frac_part if decimals > 0 else "")
+    return ("-" if negative and not is_zero else "") + out
+
+
+def money(minor: int, currency: str) -> str:
+    """``money:CUR`` -- integer minor units, never through a float."""
+    exponent, symbol = CURRENCIES[currency]
+    negative = minor < 0
+    digits = str(abs(minor)).rjust(exponent + 1, "0")
+    whole = digits[: len(digits) - exponent]
+    frac = "." + digits[len(digits) - exponent :] if exponent > 0 else ""
+    prefix = symbol if symbol is not None else currency + " "
+    return ("-" if negative else "") + prefix + _group(whole) + frac
+
+
+def _increment(digits: str) -> str:
+    d = list(digits)
+    i = len(d) - 1
+    while i >= 0:
+        if d[i] == "9":
+            d[i] = "0"
+            i -= 1
+            continue
+        d[i] = str(int(d[i]) + 1)
+        return "".join(d)
+    return "1" + "".join(d)
+
+
+def _group(whole: str) -> str:
+    out = ""
+    n = len(whole)
+    for i, ch in enumerate(whole):
+        if i > 0 and (n - i) % 3 == 0:
+            out += ","
+        out += ch
+    return out

fancy_template/_profile.py

@@ -0,0 +1,82 @@
+"""A writer profile (SPEC.md section 9): which string fields may hold tokens and
+how a value is encoded there.
+
+The profiles are DATA in the repository's ``profiles/``, shared by every
+implementation. An installed wheel carries a copy inside the package (built
+from that same directory); a source checkout reads the repository's own files,
+so there is no second copy to drift.
+
+An allowlist. A field that matches no pattern refuses tokens, so a writer gaining
+a new field (a link, a font, a URL) is closed to data by default.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, ClassVar
+
+#: The encodings this implementation has built. A profile needing any other is not offered.
+IMPLEMENTED_ENCODINGS = ("text", "band", "markup", "markdown", "cell", "image")
+
+_WRITER = re.compile(r"[a-z][a-z-]*", re.ASCII)
+
+
+def _profiles_dir() -> Path:
+    here = Path(__file__).resolve().parent
+    packaged = here / "profiles"
+    if packaged.is_dir():
+        return packaged
+    # python/src/fancy_template -> the repository root.
+    checkout = here.parents[2] / "profiles"
+    if checkout.is_dir():
+        return checkout
+    raise RuntimeError(
+        "fancy-template: no profiles/ directory, neither packaged nor in the checkout. "
+        "This is an error and not an empty profile set: a template engine that silently "
+        "knows no writers refuses everything and reads as broken data."
+    )
+
+
+class Profile:
+    _cache: ClassVar[dict[str, Profile | None]] = {}
+
+    def __init__(self, writer: str, fields: list[dict[str, Any]]) -> None:
+        self.writer = writer
+        self._fields = fields
+
+    @classmethod
+    def for_writer(cls, writer: Any) -> Profile | None:
+        """The profile for a writer, or None when unknown or not implemented here."""
+        if not isinstance(writer, str) or _WRITER.fullmatch(writer) is None:
+            return None
+        if writer in cls._cache:
+            return cls._cache[writer]
+        file = _profiles_dir() / f"{writer}.json"
+        profile: Profile | None = None
+        if file.is_file():
+            data = json.loads(file.read_text(encoding="utf-8"))
+            fields = [{**f, "pattern": f["path"].split(".")} for f in data["fields"]]
+            if all(f["encode"] in IMPLEMENTED_ENCODINGS for f in fields):
+                profile = cls(writer, fields)
+        cls._cache[writer] = profile
+        return profile
+
+    def field(self, segments: list[str]) -> dict[str, Any] | None:
+        """The field rule for a string at ``segments`` inside ``document``. First match wins."""
+        for f in self._fields:
+            if _matches(f["pattern"], 0, segments, 0):
+                return f
+        return None
+
+
+def _matches(pattern: list[str], p: int, path: list[str], s: int) -> bool:
+    """Glob match: ``*`` is one segment, ``**`` zero or more. Patterns come from this package."""
+    if p == len(pattern):
+        return s == len(path)
+    if pattern[p] == "**":
+        return any(_matches(pattern, p + 1, path, k) for k in range(s, len(path) + 1))
+    if s == len(path):
+        return False
+    return (pattern[p] == "*" or pattern[p] == path[s]) and _matches(pattern, p + 1, path, s + 1)

fancy_template/_renderer.py

@@ -0,0 +1,277 @@
+"""Template + validated, defaulted data -> writer document (SPEC.md sections 6-10).
+
+Runs only on a template that passed inspect and data that passed validate_data,
+so it does not re-check what those guarantee; it checks what only data can
+decide (absent paths, non-scalars, filter inputs, {page} in a band value) and
+the output bounds, counted AS the output is produced so that an oversized result
+is refused before it is built rather than after.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from fancy_expr import evaluate, truthy
+
+from ._dates import parse_date
+from ._errors import TemplateError
+from ._filters import ABSENT, apply_filter, scalar_text
+from ._inspector import resolve_decl
+from ._json import image_type, is_number, pointer, utf8_length
+from ._limits import Limits
+from ._profile import Profile
+from ._scanner import LOOP_HEADS, is_digits, path_only, tokenize
+
+
+def escape_markdown(s: str) -> str:
+    """CommonMark: a backslash before every ASCII punctuation character (SPEC.md section 9)."""
+    out = []
+    for ch in s:
+        o = ord(ch)
+        punct = 33 <= o <= 47 or 58 <= o <= 64 or 91 <= o <= 96 or 123 <= o <= 126
+        out.append("\\" + ch if punct else ch)
+    return "".join(out)
+
+
+_HTML = {"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"}
+
+
+def escape_html(s: str) -> str:
+    return "".join(_HTML.get(ch, ch) for ch in s)
+
+
+def _identity(s: str) -> str:
+    return s
+
+
+class Renderer:
+    def __init__(self, profile: Profile, data: dict[str, Any], variables: dict[str, Any], limits: Limits) -> None:
+        self.profile = profile
+        self.data = data
+        self.variables = variables
+        self.limits = limits
+        self.iterations = 0
+        self.nodes = 0
+        self.bytes = 0
+
+    @classmethod
+    def run(
+        cls, document: dict[str, Any], data: dict[str, Any], variables: dict[str, Any], profile: Profile, limits: Limits
+    ) -> dict[str, Any]:
+        self = cls(profile, data, variables, limits)
+        self._count(None)
+        return self._object(document, "/document", [], [])
+
+    def _object(
+        self, obj: dict[str, Any], path: str, segments: list[str], frames: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        for key, value in obj.items():
+            if key.startswith("$"):
+                continue
+            out[key] = self._value(value, pointer(path, key), [*segments, key], frames, obj)
+        return out
+
+    def _value(
+        self, value: Any, path: str, segments: list[str], frames: list[dict[str, Any]], parent: dict[str, Any] | None
+    ) -> Any:
+        if isinstance(value, str):
+            out = self._string(value, path, segments, frames, parent)
+            if isinstance(out, dict):
+                # A cell wrapper: one object and one string (SPEC.md section 10).
+                self._count(None)
+                self._count(out["value"])
+            else:
+                self._count(out)
+            return out
+        if not isinstance(value, (dict, list)):
+            self._count(value)
+            return value
+        self._count(None)
+        if isinstance(value, dict):
+            return self._object(value, path, segments, frames)
+
+        result: list[Any] = []
+        for i, item in enumerate(value):
+            at = pointer(path, i)
+            item_segments = [*segments, str(i)]
+            if not isinstance(item, dict) or not any(k.startswith("$") for k in item):
+                result.append(self._value(item, at, item_segments, frames, None))
+                continue
+            is_splice = "$value" in item
+            for inner in self._expand(item, at, frames):
+                if is_splice:
+                    # The splice object is not output: each copy is $value,
+                    # rendered at the element's path (SPEC.md section 8).
+                    result.append(self._value(item["$value"], pointer(at, "$value"), item_segments, inner, None))
+                    continue
+                self._count(None)
+                result.append(self._object(item, at, item_segments, inner))
+        return result
+
+    def _expand(self, item: dict[str, Any], path: str, frames: list[dict[str, Any]]) -> Iterator[list[dict[str, Any]]]:
+        """The frames each copy of a directive element renders with.
+
+        A generator on purpose: iterations are counted as copies are rendered,
+        interleaved, exactly as the other legs count them, so the same template
+        fails with the same code.
+        """
+        if "$each" not in item:
+            if self._condition(item["$if"], frames):
+                yield frames
+            return
+
+        at = pointer(path, "$each")
+        steps = path_only(item["$each"])
+        assert steps is not None
+        lst = self._resolve(steps, frames)
+        if lst is ABSENT:
+            raise TemplateError("TEMPLATE_MISSING", at, ".".join(steps))
+        if not isinstance(lst, list):
+            raise TemplateError("DIRECTIVE_NOT_ARRAY", at, ".".join(steps))
+
+        as_name = item.get("$as")
+        if as_name is None:
+            as_name = "item"
+        _, decl = resolve_decl(steps, frames, self.variables)
+        items_decl = decl.get("items") if isinstance(decl, dict) else None
+        last = len(lst) - 1
+        for index, element in enumerate(lst):
+            self.iterations += 1
+            if self.iterations > self.limits.iterations:
+                raise TemplateError("RENDER_TOO_MANY_ITERATIONS", at)
+            inner = [
+                *frames,
+                {
+                    "name": as_name,
+                    "decl": items_decl,
+                    "value": element,
+                    "$index": index,
+                    "$first": index == 0,
+                    "$last": index == last,
+                },
+            ]
+            if "$if" in item and not self._condition(item["$if"], inner):
+                continue
+            yield inner
+
+    def _condition(self, expression: str, frames: list[dict[str, Any]]) -> bool:
+        context = dict(self.data)
+        for frame in frames:
+            context[frame["name"]] = frame["value"]
+        if frames:
+            innermost = frames[-1]
+            for head in LOOP_HEADS:
+                context[head] = innermost[head]
+        # Parsed and bounded at inspect; fancy-expr never reaches the host.
+        return bool(truthy(evaluate(expression, context)))
+
+    def _resolve(self, steps: list[str], frames: list[dict[str, Any]]) -> Any:
+        head = steps[0]
+        if head in LOOP_HEADS:
+            return frames[-1][head] if frames else ABSENT
+
+        value: Any = ABSENT
+        for frame in reversed(frames):
+            if frame["name"] == head:
+                value = frame["value"]
+                break
+        if value is ABSENT:
+            if head not in self.data:
+                return ABSENT
+            value = self.data[head]
+
+        for step in steps[1:]:
+            if isinstance(value, list):
+                if not is_digits(step):
+                    return ABSENT
+                index = int(step)
+                if index >= len(value):
+                    return ABSENT
+                value = value[index]
+                continue
+            if not isinstance(value, dict) or step not in value:
+                return ABSENT
+            value = value[step]
+        return value
+
+    def _string(
+        self, text: str, path: str, segments: list[str], frames: list[dict[str, Any]], parent: dict[str, Any] | None
+    ) -> Any:
+        if "{{" not in text:
+            return text
+
+        field = self.profile.field(segments)
+        assert field is not None
+        parts = tokenize(text, self.limits.token_length)
+        escape = self._escaper(field, parent)
+        out = ""
+
+        for part in parts:
+            if "text" in part:
+                out += part["text"]
+                continue
+            variable = ".".join(part["path"]) if "path" in part else None
+            value = self._resolve(part["path"], frames) if "path" in part else part["literal"]
+
+            try:
+                for filt in part["filters"]:
+                    value = apply_filter(filt, value)
+                if value is ABSENT:
+                    raise TemplateError("TEMPLATE_MISSING", "")
+                if field["encode"] == "image":
+                    if image_type(value) not in field["mime"]:
+                        raise TemplateError("VALUE_IMAGE_TYPE", "")
+                    return value
+                if field["encode"] == "cell" and len(parts) == 1:
+                    kept = self._typed_cell(value, part.get("path"), frames)
+                    if kept is not ABSENT:
+                        return kept
+                piece = scalar_text(value)
+            except TemplateError as e:
+                raise TemplateError(e.code, path, variable) from None
+
+            if field["encode"] == "band" and ("{page}" in piece or "{pages}" in piece):
+                raise TemplateError("VALUE_PAGE_FIELD", path, variable)
+            out += escape(piece)
+
+        # Every other cell result is wrapped, so user data can never become a
+        # formula: holy-sheet promotes a BARE string starting with "=" and takes
+        # {value: s} as literal text (template/profiles 0201).
+        return {"value": out} if field["encode"] == "cell" else out
+
+    def _typed_cell(self, value: Any, steps: list[str] | None, frames: list[dict[str, Any]]) -> Any:
+        """A whole token in a cell keeps a number, a boolean, or a valid date DECLARED ``date``.
+
+        ABSENT when the result is to be wrapped. A valid date cannot begin with
+        "=", so nothing kept bare here can become a formula.
+        """
+        if is_number(value) or isinstance(value, bool):
+            return value
+        if not isinstance(value, str) or steps is None or parse_date(value) is None:
+            return ABSENT
+        found, decl = resolve_decl(steps, frames, self.variables)
+        return value if found and isinstance(decl, dict) and decl.get("type") == "date" else ABSENT
+
+    @staticmethod
+    def _escaper(field: dict[str, Any], parent: dict[str, Any] | None) -> Callable[[str], str]:
+        if field["encode"] == "markdown":
+            return escape_markdown
+        if field["encode"] == "markup":
+            fmt = parent.get("format") if parent is not None else None
+            if fmt == "markdown":
+                return escape_markdown
+            if fmt == "html":
+                return escape_html
+        return _identity
+
+    def _count(self, value: Any) -> None:
+        """One output value; a string also adds its bytes (SPEC.md section 10)."""
+        self.nodes += 1
+        if self.nodes > self.limits.output_nodes:
+            raise TemplateError("RENDER_TOO_MANY_NODES", "")
+        if isinstance(value, str):
+            self.bytes += utf8_length(value)
+            if self.bytes > self.limits.output_bytes:
+                raise TemplateError("RENDER_TOO_LARGE", "")