fancy-template 0.2.0__py3-none-any.whl

fancy_template/_inspector.py

@@ -0,0 +1,350 @@
+"""Everything that can be known about a template without data (SPEC.md sections
+2, 3, 5, 8, 9, 10 and 11). The answer an admin gets at SAVE time.
+
+Issues come in document order so that three runtimes produce comparable lists:
+envelope, declarations, then the document depth-first with an object's ``$``
+keys before its other entries.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fancy_expr import ExprSyntaxError, references
+
+from ._declarations import inspect_decl
+from ._errors import TemplateError
+from ._filters import check_filter
+from ._json import first_too_deep, image_type, pointer, string_bytes, utf8_length
+from ._limits import Limits
+from ._profile import Profile
+from ._scanner import LOOP_HEADS, count_tokens, is_digits, is_name, path_only, tokenize
+
+DeclFrame = dict[str, Any]  # {"name": str, "decl": Any}
+
+_ENVELOPE_REQUIRED = (
+    ("fancyTemplate", "TEMPLATE_VERSION"),
+    ("writer", "TEMPLATE_WRITER"),
+    ("document", "TEMPLATE_SHAPE"),
+)
+
+
+def declared_variables(template: Any) -> dict[str, Any]:
+    """The declared variables, every entry in written order, as the other legs read them."""
+    if not isinstance(template, dict):
+        return {}
+    variables = template.get("variables")
+    return dict(variables) if isinstance(variables, dict) else {}
+
+
+def resolve_decl(steps: list[str], frames: list[DeclFrame], variables: dict[str, Any]) -> tuple[bool, Any]:
+    """Walk a path through the declarations (SPEC.md section 6).
+
+    ``(found, decl)``; decl is None when the shape below is unknown (a broken
+    declaration has already been reported, and is not reported twice).
+    """
+    head = steps[0]
+    if head in LOOP_HEADS:
+        if not frames or len(steps) > 1:
+            return False, None
+        return True, {"type": "integer" if head == "$index" else "boolean"}
+
+    decl: Any = None
+    found = False
+    for frame in reversed(frames):
+        if frame["name"] == head:
+            found, decl = True, frame["decl"]
+            break
+    if not found:
+        if head not in variables:
+            return False, None
+        decl = variables[head]
+
+    for step in steps[1:]:
+        if not isinstance(decl, dict) or decl.get("type") is None:
+            return True, None
+        properties = decl.get("properties")
+        if decl["type"] == "object" and isinstance(properties, dict) and step in properties:
+            decl = properties[step]
+            continue
+        if decl["type"] == "array" and is_digits(step):
+            decl = decl.get("items")
+            continue
+        return False, None
+    return True, decl
+
+
+class Inspector:
+    def __init__(self, limits: Limits) -> None:
+        self.limits = limits
+        self.issues: list[dict[str, str]] = []
+        self.variables: dict[str, Any] = {}
+        self.profile: Profile | None = None
+
+    @classmethod
+    def run(cls, template: Any, limits: Limits) -> list[dict[str, str]]:
+        self = cls(limits)
+        self._inspect(template)
+        return self.issues
+
+    def _inspect(self, template: Any) -> None:
+        if not isinstance(template, dict):
+            self._issue("TEMPLATE_SHAPE", "")
+            return
+
+        # The three bounds that STOP inspect come first, in this order (template/inspect 0020).
+        too_deep = first_too_deep(template, self.limits.depth)
+        if too_deep is not None:
+            self._issue("TEMPLATE_TOO_DEEP", too_deep)
+            return
+        if string_bytes(template) > self.limits.template_bytes:
+            self._issue("TEMPLATE_TOO_LARGE", "")
+            return
+        if self._count_tokens(template.get("document")) > self.limits.tokens:
+            self._issue("TEMPLATE_TOO_MANY_TOKENS", "")
+            return
+
+        for key, value in template.items():
+            at = pointer("", key)
+            if key == "fancyTemplate":
+                # `True == 1` in Python; the version is the integer 1 and nothing else.
+                if not (type(value) is int and value == 1) and not (type(value) is float and value == 1.0):
+                    self._issue("TEMPLATE_VERSION", at)
+            elif key == "writer":
+                self.profile = Profile.for_writer(value)
+                if self.profile is None:
+                    self._issue("TEMPLATE_WRITER", at)
+            elif key == "description":
+                if not isinstance(value, str):
+                    self._issue("TEMPLATE_SHAPE", at)
+            elif key in ("variables", "document"):
+                if not isinstance(value, dict):
+                    self._issue("TEMPLATE_SHAPE", at)
+            else:
+                self._issue("TEMPLATE_SHAPE", at)
+        for key, code in _ENVELOPE_REQUIRED:
+            if key not in template:
+                self._issue(code, pointer("", key))
+
+        variables = template.get("variables")
+        if isinstance(variables, dict):
+            for name, decl in variables.items():
+                at = pointer("/variables", name)
+                if not is_name(name):
+                    self._issue("DECL_INVALID", at)
+                    continue
+                inspect_decl(decl, at, self.issues)
+                self.variables[name] = decl
+
+        document = template.get("document")
+        if self.profile is not None and isinstance(document, dict):
+            self._walk(document, "/document", [], [], 0, False)
+
+    def _count_tokens(self, value: Any) -> int:
+        if isinstance(value, str):
+            return count_tokens(value, self.limits.token_length)
+        if not isinstance(value, (dict, list)):
+            return 0
+        n = 0
+        for v in value.values() if isinstance(value, dict) else value:
+            n += self._count_tokens(v)
+            if n > self.limits.tokens:
+                break
+        return n
+
+    def _walk(
+        self,
+        value: Any,
+        path: str,
+        segments: list[str],
+        frames: list[DeclFrame],
+        directive_depth: int,
+        is_element: bool,
+    ) -> None:
+        if isinstance(value, str):
+            self._string(value, path, segments, frames)
+            return
+        if isinstance(value, list):
+            for i, item in enumerate(value):
+                self._walk(item, pointer(path, i), [*segments, str(i)], frames, directive_depth, True)
+            return
+        if not isinstance(value, dict):
+            return
+
+        directives = [k for k in value if k.startswith("$")]
+        if directives:
+            if not is_element:
+                for key in directives:
+                    self._issue("DIRECTIVE_MISPLACED", pointer(path, key))
+            else:
+                directive_depth += 1
+                if directive_depth > self.limits.directive_depth:
+                    self._issue("DIRECTIVE_TOO_DEEP", path)
+                    return
+                frames = self._directives(value, path, frames)
+                if "$value" in value:
+                    self._splice(value, path, segments, frames, directive_depth)
+                    return
+
+        for key, child in value.items():
+            if key.startswith("$"):
+                continue
+            at = pointer(path, key)
+            if "{{" in key:
+                self._issue("TOKEN_IN_KEY", at)
+            self._walk(child, at, [*segments, key], frames, directive_depth, False)
+
+    def _splice(
+        self, obj: dict[str, Any], path: str, segments: list[str], frames: list[DeclFrame], directive_depth: int
+    ) -> None:
+        """The rest of a splice (SPEC.md section 8), after its ``$`` keys.
+
+        Every other key is DIRECTIVE_SPLICE_KEY and is not walked. ``$value`` is
+        walked AT THE ELEMENT'S PATH (``$value`` is a pointer step, never a
+        profile segment) and as a non-element, so a ``$``-key on its top is
+        DIRECTIVE_MISPLACED. Without ``$each`` it is not walked: that is already
+        DIRECTIVE_INVALID.
+        """
+        for key in obj:
+            if not key.startswith("$"):
+                self._issue("DIRECTIVE_SPLICE_KEY", pointer(path, key))
+        if "$each" in obj:
+            self._walk(obj["$value"], pointer(path, "$value"), segments, frames, directive_depth, False)
+
+    def _each_binding(self, obj: dict[str, Any], frames: list[DeclFrame]) -> list[DeclFrame] | None:
+        """The frames an element's ``$each`` introduces, or None.
+
+        Worked out BEFORE the ordered pass so that ``$if`` sees the binding
+        whichever key was written first: SPEC.md section 8 says ``$each`` runs
+        first, and JSON key order is not something an author should get right.
+        """
+        each = obj.get("$each")
+        if not isinstance(each, str) or utf8_length(each) > self.limits.token_length:
+            return None
+        steps = path_only(each)
+        if steps is None:
+            return None
+        found, decl = resolve_decl(steps, frames, self.variables)
+        if not found or (isinstance(decl, dict) and decl.get("type") != "array"):
+            return None
+        as_name = obj.get("$as")
+        if as_name is None:
+            as_name = "item"
+        if not isinstance(as_name, str) or not is_name(as_name):
+            return None
+        return [*frames, {"name": as_name, "decl": decl.get("items") if isinstance(decl, dict) else None}]
+
+    def _directives(self, obj: dict[str, Any], path: str, frames: list[DeclFrame]) -> list[DeclFrame]:
+        has_each = "$each" in obj
+        inner = self._each_binding(obj, frames) or frames
+
+        for key, value in obj.items():
+            if not key.startswith("$"):
+                continue
+            at = pointer(path, key)
+
+            if key == "$each":
+                if not isinstance(value, str):
+                    self._issue("DIRECTIVE_INVALID", at)
+                    continue
+                if utf8_length(value) > self.limits.token_length:
+                    self._issue("TOKEN_TOO_LONG", at)
+                    continue
+                steps = path_only(value)
+                if steps is None:
+                    self._issue("DIRECTIVE_INVALID", at)
+                    continue
+                found, decl = resolve_decl(steps, frames, self.variables)
+                if not found:
+                    self._issue("DIRECTIVE_UNDECLARED", at, ".".join(steps))
+                    continue
+                if isinstance(decl, dict) and decl.get("type") != "array":
+                    self._issue("DIRECTIVE_NOT_ARRAY", at, ".".join(steps))
+                continue
+
+            if key == "$as":
+                shadows = isinstance(value, str) and (
+                    value in self.variables or any(f["name"] == value for f in frames)
+                )
+                if not has_each or not isinstance(value, str) or not is_name(value) or shadows:
+                    self._issue("DIRECTIVE_INVALID", at)
+                continue
+
+            if key == "$value":
+                # Any JSON is a valid $value; only a splice with nothing to
+                # repeat over is wrong (SPEC.md section 8).
+                if not has_each:
+                    self._issue("DIRECTIVE_INVALID", at)
+                continue
+
+            if key == "$if":
+                if not isinstance(value, str):
+                    self._issue("DIRECTIVE_INVALID", at)
+                    continue
+                if utf8_length(value) > self.limits.token_length:
+                    self._issue("TOKEN_TOO_LONG", at)
+                    continue
+                try:
+                    roots = references(value)
+                except ExprSyntaxError:
+                    self._issue("DIRECTIVE_EXPR", at)
+                    continue
+                # `$if` sees this element's own loop binding (SPEC.md section 8).
+                scope = inner if has_each else frames
+                for root in roots:
+                    if not self._in_scope(root, scope):
+                        self._issue("DIRECTIVE_UNDECLARED", at, root)
+                        break
+                continue
+
+            self._issue("DIRECTIVE_UNKNOWN", at)
+
+        return inner
+
+    def _in_scope(self, root: str, frames: list[DeclFrame]) -> bool:
+        if root in LOOP_HEADS:
+            return bool(frames)
+        return any(f["name"] == root for f in frames) or root in self.variables
+
+    def _string(self, value: str, path: str, segments: list[str], frames: list[DeclFrame]) -> None:
+        try:
+            parts = tokenize(value, self.limits.token_length)
+        except TemplateError as e:
+            self._issue(e.code, path)
+            return
+
+        tokens = [p for p in parts if "text" not in p]
+        assert self.profile is not None
+        field = self.profile.field(segments)
+
+        if not tokens:
+            if field is not None and field["encode"] == "image" and image_type(value) not in field["mime"]:
+                self._issue("TEMPLATE_IMAGE_INVALID", path)
+            return
+        if field is None:
+            self._issue("TOKEN_FORBIDDEN_FIELD", path)
+            return
+
+        if field["encode"] == "image":
+            token = tokens[0]
+            is_whole = len(parts) == 1 and "path" in token and token["filters"] == []
+            found, decl = resolve_decl(token["path"], frames, self.variables) if is_whole else (False, None)
+            if not is_whole or not found or not isinstance(decl, dict) or decl.get("type") != "image":
+                self._issue("TOKEN_IMAGE_FIELD", path)
+            return
+
+        for token in tokens:
+            if "path" in token:
+                found, _ = resolve_decl(token["path"], frames, self.variables)
+                if not found:
+                    self._issue("TOKEN_UNDECLARED", path, ".".join(token["path"]))
+            for filt in token["filters"]:
+                code = check_filter(filt)
+                if code is not None:
+                    self._issue(code, path)
+
+    def _issue(self, code: str, path: str, variable: str | None = None) -> None:
+        issue = {"code": code, "path": path}
+        if variable is not None:
+            issue["variable"] = variable
+        self.issues.append(issue)

fancy_template/_json.py

@@ -0,0 +1,207 @@
+"""Small JSON-shaped helpers shared by the inspector, validator and renderer.
+
+Everything that walks a value of unknown depth here is ITERATIVE. Python's
+recursion limit (1000 by default) sits well below the 4096 levels the other
+legs accept as plain JSON, so a recursive walk would refuse, or crash on, data
+the PHP and TypeScript legs handle.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import math
+from typing import Any, TypeGuard
+
+#: The deepest container a value may hold and still be plain JSON. PHP's
+#: ``json_encode`` refuses anything deeper (its depth argument, 4096), and the
+#: three legs must agree on what counts as plain, so this leg refuses it too.
+PLAIN_MAX_DEPTH = 4096
+
+_INT64_MIN = -(2**63)
+_INT64_MAX = 2**63 - 1
+
+
+def pointer(base: str, key: str | int) -> str:
+    return base + "/" + str(key).replace("~", "~0").replace("/", "~1")
+
+
+def is_object(v: Any) -> bool:
+    return isinstance(v, dict)
+
+
+def is_list(v: Any) -> bool:
+    return isinstance(v, list)
+
+
+def is_number(v: Any) -> TypeGuard[int | float]:
+    """A JSON number. ``bool`` is an ``int`` in Python and is NOT one here."""
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def utf8_length(s: str) -> int:
+    return len(s.encode("utf-8"))
+
+
+def code_points(s: str) -> int:
+    """Unicode code points, JSON Schema's unit for maxLength. A ``str`` IS code points."""
+    return len(s)
+
+
+class _NotPlainError(Exception):
+    pass
+
+
+def _key(k: Any) -> str:
+    if isinstance(k, str):
+        _check_text(k)
+        return str.__str__(k)
+    if isinstance(k, int) and not isinstance(k, bool):
+        return str(int.__int__(k))
+    raise _NotPlainError
+
+
+def _check_text(s: str) -> None:
+    # A lone surrogate is not Unicode text, and no other leg can represent it.
+    try:
+        str.encode(s, "utf-8")
+    except UnicodeEncodeError as exc:
+        raise _NotPlainError from exc
+
+
+def _scalar(v: Any) -> Any:
+    if v is None or isinstance(v, bool):
+        return v
+    if isinstance(v, int):
+        v = int.__int__(v)
+        if _INT64_MIN <= v <= _INT64_MAX:
+            return v
+        # Past int64 PHP decodes a JSON integer as a float; so does this leg.
+        try:
+            f = float(v)
+        except OverflowError as exc:
+            raise _NotPlainError from exc
+        if not math.isfinite(f):
+            raise _NotPlainError
+        return f
+    if isinstance(v, float):
+        if not math.isfinite(v):
+            raise _NotPlainError
+        return float.__float__(v)
+    if isinstance(v, str):
+        _check_text(v)
+        return str.__str__(v)
+    raise _NotPlainError
+
+
+def _is_container(v: Any) -> bool:
+    return isinstance(v, (dict, list, tuple))
+
+
+def plain(value: Any) -> tuple[bool, Any]:
+    """Reduce a host value to plain JSON data (SPEC.md section 4).
+
+    ``(True, copy)`` or ``(False, None)``. Accepts exactly what ``json.dumps``
+    accepts without a ``default`` hook -- dict (str or int keys), list, tuple,
+    str, int, float, bool, None -- refuses non-finite numbers like
+    ``allow_nan=False``, refuses a lone surrogate and a cycle, and never calls a
+    method on a host object: a subclass is read through its base type.
+    """
+    try:
+        return True, _convert(value)
+    except _NotPlainError:
+        return False, None
+
+
+def _convert(value: Any) -> Any:
+    if not _is_container(value):
+        return _scalar(value)
+
+    root: Any = {} if isinstance(value, dict) else []
+    # (source, destination, level) frames, with exit markers so the set of
+    # containers on the CURRENT path is known: a shared reference is fine
+    # (json.dumps allows it), a cycle is not.
+    stack: list[tuple[Any, Any, int] | int] = [(value, root, 1)]
+    on_path: set[int] = set()
+    while stack:
+        top = stack.pop()
+        if isinstance(top, int):
+            on_path.discard(top)
+            continue
+        src, dst, level = top
+        if level > PLAIN_MAX_DEPTH or id(src) in on_path:
+            raise _NotPlainError
+        on_path.add(id(src))
+        stack.append(id(src))
+        items = src.items() if isinstance(src, dict) else enumerate(src)
+        children: list[tuple[Any, Any, int]] = []
+        for k, v in items:
+            if _is_container(v):
+                child: Any = {} if isinstance(v, dict) else []
+                children.append((v, child, level + 1))
+            else:
+                child = _scalar(v)
+            if isinstance(dst, dict):
+                dst[_key(k)] = child
+            else:
+                dst.append(child)
+        stack.extend(reversed(children))
+    return root
+
+
+def first_too_deep(value: Any, limit: int) -> str | None:
+    """Pointer of the first container, in document order, above ``limit`` levels (the root is level 1)."""
+    stack: list[tuple[Any, str, int]] = [(value, "", 1)]
+    while stack:
+        v, path, level = stack.pop()
+        if not isinstance(v, (dict, list)):
+            continue
+        if level > limit:
+            return path
+        entries = list(v.items()) if isinstance(v, dict) else list(enumerate(v))
+        for k, child in reversed(entries):
+            stack.append((child, pointer(path, k), level + 1))
+    return None
+
+
+def string_bytes(value: Any) -> int:
+    """UTF-8 bytes of every string, object keys included."""
+    total = 0
+    stack = [value]
+    while stack:
+        v = stack.pop()
+        if isinstance(v, str):
+            total += utf8_length(v)
+        elif isinstance(v, list):
+            stack.extend(v)
+        elif isinstance(v, dict):
+            for k, child in v.items():
+                total += utf8_length(k)
+                stack.append(child)
+    return total
+
+
+_B64 = frozenset(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=")
+_MAGIC = (("image/png", b"\x89PNG\r\n\x1a\n"), ("image/jpeg", b"\xff\xd8\xff"))
+
+
+def image_type(value: Any) -> str | None:
+    """The MIME type of a valid PNG or JPEG data URL (base64 strict, magic bytes checked), else None."""
+    if not isinstance(value, str):
+        return None
+    for mime, magic in _MAGIC:
+        prefix = f"data:{mime};base64,"
+        if not value.startswith(prefix):
+            continue
+        b64 = value[len(prefix) :]
+        if not b64.isascii():
+            return None
+        raw_b64 = b64.encode("ascii")
+        if raw_b64 == b"" or len(raw_b64) % 4 != 0 or not set(raw_b64) <= _B64:
+            return None
+        try:
+            raw = base64.b64decode(raw_b64, validate=True)
+        except (binascii.Error, ValueError):
+            return None
+        return mime if raw.startswith(magic) else None
+    return None

fancy_template/_limits.py

@@ -0,0 +1,54 @@
+"""The bounds from SPEC.md section 10. Every one has a stable error code and
+every one is host-overridable through ``options["limits"]``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_LIMITS: dict[str, int] = {
+    "templateBytes": 262144,
+    "tokens": 10000,
+    "tokenLength": 512,
+    "directiveDepth": 8,
+    "iterations": 10000,
+    "outputNodes": 50000,
+    "outputBytes": 8388608,
+    "depth": 64,
+}
+
+
+@dataclass(frozen=True)
+class Limits:
+    template_bytes: int
+    tokens: int
+    token_length: int
+    directive_depth: int
+    iterations: int
+    output_nodes: int
+    output_bytes: int
+    depth: int
+
+
+def limits_from(options: dict[str, Any] | None) -> Limits:
+    given = (options or {}).get("limits") or {}
+    if not isinstance(given, dict):
+        raise TypeError("options.limits must be an object")
+    values = dict(DEFAULT_LIMITS)
+    for name, value in given.items():
+        if name not in DEFAULT_LIMITS:
+            raise ValueError(f"Unknown limit `{name}`")
+        # bool is an int in Python; a limit of `True` is not a number.
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            raise ValueError(f"Limit `{name}` must be a non-negative integer")
+        values[name] = value
+    return Limits(
+        template_bytes=values["templateBytes"],
+        tokens=values["tokens"],
+        token_length=values["tokenLength"],
+        directive_depth=values["directiveDepth"],
+        iterations=values["iterations"],
+        output_nodes=values["outputNodes"],
+        output_bytes=values["outputBytes"],
+        depth=values["depth"],
+    )