triplate 0.3.0__tar.gz

triplate-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.astro/
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+build/
+.pytest_cache/
+coverage/
+target/
+.DS_Store

triplate-0.3.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: triplate
+Version: 0.3.0
+Summary: A templating engine for SPARQL queries with typed, injection-safe placeholders and loops
+Project-URL: Homepage, https://triplate.dev
+Project-URL: Repository, https://github.com/triplate/triplate
+Project-URL: Issues, https://github.com/triplate/triplate/issues
+Author: Triplate contributors
+License-Expression: MIT
+Keywords: injection-safe,query,rdf,sparql,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rdflib>=6.0; extra == 'dev'
+Provides-Extra: rdflib
+Requires-Dist: rdflib>=6.0; extra == 'rdflib'
+Description-Content-Type: text/markdown
+
+# Triplate (Python)
+
+A templating engine for RDF query & data languages (SPARQL, Turtle, …) with a
+typed `---` frontmatter header, injection-safe values, loops and conditionals.
+Python reference implementation of the [Triplate language](https://triplate.dev).
+
+```python
+from triplate import compile
+
+template = """\
+---
+params {
+  classes: iri[] min 1
+  limit:   int optional
+}
+---
+SELECT ?s WHERE {
+{% for c in classes join "UNION" %}
+  { ?s a ${c} }
+{% endfor %}
+}
+{% if limit %}LIMIT ${limit}{% endif %}
+"""
+
+tmpl = compile(template)
+sparql = tmpl.render(classes=["http://example.org/Person"], limit=10)
+```
+
+Every input is declared in the mandatory `---` frontmatter header with its RDF
+type; the context is validated and each value escaped accordingly, so rendered
+output is injection-safe and an unprocessed template fails fast.
+
+See [triplate.dev](https://triplate.dev) for the full guide and specification.

triplate-0.3.0/README.md

@@ -0,0 +1,33 @@
+# Triplate (Python)
+
+A templating engine for RDF query & data languages (SPARQL, Turtle, …) with a
+typed `---` frontmatter header, injection-safe values, loops and conditionals.
+Python reference implementation of the [Triplate language](https://triplate.dev).
+
+```python
+from triplate import compile
+
+template = """\
+---
+params {
+  classes: iri[] min 1
+  limit:   int optional
+}
+---
+SELECT ?s WHERE {
+{% for c in classes join "UNION" %}
+  { ?s a ${c} }
+{% endfor %}
+}
+{% if limit %}LIMIT ${limit}{% endif %}
+"""
+
+tmpl = compile(template)
+sparql = tmpl.render(classes=["http://example.org/Person"], limit=10)
+```
+
+Every input is declared in the mandatory `---` frontmatter header with its RDF
+type; the context is validated and each value escaped accordingly, so rendered
+output is injection-safe and an unprocessed template fails fast.
+
+See [triplate.dev](https://triplate.dev) for the full guide and specification.

triplate-0.3.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "triplate"
+version = "0.3.0"
+description = "A templating engine for SPARQL queries with typed, injection-safe placeholders and loops"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Triplate contributors" }]
+keywords = ["sparql", "template", "rdf", "query", "injection-safe"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://triplate.dev"
+Repository = "https://github.com/triplate/triplate"
+Issues = "https://github.com/triplate/triplate/issues"
+
+[project.optional-dependencies]
+rdflib = ["rdflib>=6.0"]
+dev = ["pytest>=8.0", "rdflib>=6.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/triplate"]

triplate-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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')