triplate 0.3.0__py3-none-any.whl

triplate/__init__.py

@@ -0,0 +1,77 @@
+"""Triplate — a templating engine for RDF query & data languages.
+
+Templates declare their inputs in a ``---`` frontmatter header and use ``${ }``
+substitutions, ``$"…"`` / ``$<…>`` constructs, and ``{% for %}`` / ``{% if %}``
+directives. Values are validated and escaped per their declared RDF type, so
+rendered queries are injection-safe by construction. See https://triplate.dev.
+
+    from triplate import compile, render
+
+    tmpl = compile(template_string)            # parse once
+    sparql = tmpl.render(classes=[...])        # render many
+    render(template_string, classes=[...])     # one-shot convenience
+"""
+
+from ._examples import example_set_to_context, extract_prefixes
+from ._parser import parse as _parse
+from ._registry import register_type
+from ._renderer import render as _render
+from .errors import (
+    TriplateBindingError,
+    TriplateCardinalityError,
+    TriplateError,
+    TriplateSyntaxError,
+    TriplateTypeError,
+)
+
+__all__ = [
+    "CompiledTemplate",
+    "compile",
+    "render",
+    "register_type",
+    "TriplateError",
+    "TriplateSyntaxError",
+    "TriplateBindingError",
+    "TriplateTypeError",
+    "TriplateCardinalityError",
+]
+
+__version__ = "0.3.0"
+
+
+class CompiledTemplate:
+    """A parsed template that can be rendered many times."""
+
+    def __init__(self, data, source):
+        self._data = data
+        self._source = source
+
+    @property
+    def schema(self):
+        return self._data.schema
+
+    @property
+    def examples(self):
+        return self._data.examples
+
+    def render(self, context=None, **kwargs):
+        ctx = dict(context) if context else {}
+        ctx.update(kwargs)
+        return _render(self._data, ctx)
+
+    def preview_example(self, example_id):
+        for e in self._data.examples:
+            if e.id == example_id:
+                ctx = example_set_to_context(e, self._data.schema, extract_prefixes(self._source))
+                return _render(self._data, ctx)
+        raise TriplateError(f"no example set with id: {example_id}")
+
+
+def compile(template):
+    """Parses a template once; the result can be rendered many times."""
+    return CompiledTemplate(_parse(template), template)
+
+
+def render(template, context=None, **kwargs):
+    """One-shot convenience: compile and render in a single call."""
+    return compile(template).render(context, **kwargs)

triplate/_ast.py

@@ -0,0 +1,181 @@
+"""AST and schema types. Mirrors the TypeScript implementation's ast.ts."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, Union
+
+RefPath = Tuple[str, ...]
+
+# A scalar/record "base" is a dict with a 'kind' key:
+#   {'kind': 'iri' | 'pname' | 'string' | ... | 'term' | 'raw'}
+#   {'kind': 'literal', 'datatype': str}
+#   {'kind': 'custom', 'name': str}
+#   {'kind': 'record', 'fields': Dict[str, TypeExpr]}
+
+
+@dataclass
+class TypeExpr:
+    base: dict
+    array: bool = False
+    optional: bool = False
+    min: Optional[int] = None
+    max: Optional[int] = None
+
+
+@dataclass
+class ParamDecl:
+    name: str
+    type: TypeExpr
+
+
+@dataclass
+class Schema:
+    params: List[ParamDecl]
+    by_name: Dict[str, TypeExpr]
+
+
+@dataclass(frozen=True)
+class LangStatic:
+    static: str
+
+
+@dataclass(frozen=True)
+class LangPath:
+    path: RefPath
+
+
+LangSpec = Union[LangStatic, LangPath]
+
+
+@dataclass(frozen=True)
+class PartText:
+    text: str
+
+
+@dataclass(frozen=True)
+class PartHole:
+    path: RefPath
+    line: int
+    column: int
+
+
+Part = Union[PartText, PartHole]
+
+
+@dataclass(frozen=True)
+class TextNode:
+    value: str
+
+
+@dataclass(frozen=True)
+class ValueNode:
+    path: RefPath
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class InterpNode:
+    parts: Tuple[Part, ...]
+    lang: Optional[LangSpec]
+    datatype: Optional[str]
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class IriNode:
+    parts: Tuple[Part, ...]
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class Cond:
+    negated: bool
+    path: RefPath
+    line: int
+    column: int
+
+
+@dataclass
+class ForNode:
+    item: str
+    source: RefPath
+    join: Optional[str]
+    join_exact: bool
+    body: List["Node"] = field(default_factory=list)
+    line: int = 0
+    column: int = 0
+
+
+@dataclass
+class Branch:
+    cond: Cond
+    body: List["Node"] = field(default_factory=list)
+
+
+@dataclass
+class IfNode:
+    branches: List[Branch]
+    else_body: Optional[List["Node"]]
+    line: int
+    column: int
+
+
+Node = Union[TextNode, ValueNode, InterpNode, IriNode, ForNode, IfNode]
+
+
+# Example values (RDF term literals)
+@dataclass(frozen=True)
+class ExIri:
+    value: str
+
+
+@dataclass(frozen=True)
+class ExPname:
+    prefix: str
+    local: str
+
+
+@dataclass(frozen=True)
+class ExString:
+    value: str
+    lang: Optional[str] = None
+    datatype: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ExNumber:
+    value: float
+
+
+@dataclass(frozen=True)
+class ExBoolean:
+    value: bool
+
+
+@dataclass(frozen=True)
+class ExList:
+    items: tuple
+
+
+@dataclass(frozen=True)
+class ExRecord:
+    fields: dict
+
+
+ExampleValue = Union[ExIri, ExPname, ExString, ExNumber, ExBoolean, ExList, ExRecord]
+
+
+@dataclass
+class ExampleSet:
+    id: str
+    description: Optional[str]
+    bindings: Dict[str, ExampleValue]
+
+
+@dataclass
+class CompiledTemplateData:
+    schema: Schema
+    examples: List[ExampleSet]
+    body: List[Node]

triplate/_examples.py

@@ -0,0 +1,60 @@
+"""Example-set preview support. Mirrors examples.ts."""
+
+import re
+
+from ._ast import ExBoolean, ExIri, ExList, ExNumber, ExPname, ExRecord, ExString
+from .errors import TriplateError
+
+_PREFIX_RE = re.compile(r"(?:PREFIX|@prefix)\s+([A-Za-z_][\w.-]*)?\s*:\s*<([^>]*)>", re.IGNORECASE)
+
+
+def extract_prefixes(template):
+    out = {}
+    for m in _PREFIX_RE.finditer(template):
+        out[m.group(1) or ""] = m.group(2)
+    return out
+
+
+def example_set_to_context(example_set, schema, prefixes):
+    ctx = {}
+    for name, ev in example_set.bindings.items():
+        type_ = schema.by_name.get(name)
+        if type_ is None:
+            raise TriplateError(f'example "{example_set.id}" binds unknown parameter: {name}')
+        ctx[name] = _convert(ev, type_, prefixes, example_set.id)
+    return ctx
+
+
+def _convert(ev, type_, prefixes, eid):
+    from ._ast import TypeExpr
+
+    if type_.array:
+        if not isinstance(ev, ExList):
+            raise TriplateError(f'example "{eid}": expected a list')
+        elem = TypeExpr(type_.base, False, False, None, None)
+        return [_convert(it, elem, prefixes, eid) for it in ev.items]
+    if type_.base["kind"] == "record":
+        if not isinstance(ev, ExRecord):
+            raise TriplateError(f'example "{eid}": expected a record')
+        out = {}
+        for f, ft in type_.base["fields"].items():
+            if f in ev.fields:
+                out[f] = _convert(ev.fields[f], ft, prefixes, eid)
+        return out
+    scalar = type_.base["kind"]
+    if isinstance(ev, ExIri):
+        return ev.value
+    if isinstance(ev, ExPname):
+        if scalar == "pname":
+            return f"{ev.prefix}:{ev.local}"
+        ns = prefixes.get(ev.prefix)
+        if ns is None:
+            raise TriplateError(f'example "{eid}": unknown prefix \'{ev.prefix}:\'')
+        return ns + ev.local
+    if isinstance(ev, ExString):
+        return ev.value
+    if isinstance(ev, ExNumber):
+        return ev.value
+    if isinstance(ev, ExBoolean):
+        return ev.value
+    raise TriplateError(f'example "{eid}": value does not match declared type')