Python API

The triplate package requires Python 3.10+ and has no required dependencies. See Installation to add it (and the optional rdflib extra for the term type), and the API overview for the cross-language model.

from triplate import compile, render, is_template, register_type

Functions

compile(template)

def compile(template: str) -> CompiledTemplate

Parses template once. Raises TriplateSyntaxError if the template is malformed (including any reference to an undeclared parameter). Returns a reusable CompiledTemplate.

render(template, context=None, **kwargs)

def render(template: str, context: dict | None = None, **kwargs) -> str

One-shot convenience equivalent to compile(template).render(context, **kwargs). Values may be passed as a mapping, as keyword arguments, or both.

is_template(text)

def is_template(text: str) -> bool

Returns True if text opens with a --- frontmatter header. A cheap, non-throwing detector — unlike compile, it never parses or raises.

CompiledTemplate

class CompiledTemplate:
    schema: Schema                              # property
    examples: list[ExampleSet]                  # property
    def render(self, context=None, **kwargs) -> str
    def preview_example(self, example_id: str) -> str
    def context_from_strings(self, inputs: dict[str, str | None]) -> dict
    def frontmatter_prefixes(self) -> set[str]

Member	Description
schema	The declared parameter schema.
examples	The named example blocks from the frontmatter; each ExampleSet carries its source line/column.
render(context=None, **kwargs)	Renders against a mapping and/or kwargs. Raises a render-time error on a missing, unknown or mistyped value. Returns the rendered string.
preview_example(example_id)	Renders using the named example set (development/preview). Raises if no such set exists.
context_from_strings(inputs)	Builds a validated context from raw string inputs. See below.
frontmatter_prefixes()	The prefixes referenced in the frontmatter. See below.

context_from_strings(inputs)

Coerces raw string inputs (CLI args, editor prompts) to their declared scalar types and validates the result against the schema:

• An absent or blank input is omitted, so optional params stay absent.
• An array param is split on commas (items trimmed, blanks dropped) and coerced element-wise.
• A record param cannot be expressed as a string and is skipped — supply records via an example block instead.
• int / decimal / double / bool are parsed strictly; an uncoercible value raises TriplateTypeError. Structural problems (missing required, cardinality) raise the usual binding/cardinality errors.

tmpl = compile("---\nparams { ids: int[], active: bool }\n---\n…")
tmpl.context_from_strings({"ids": "1, 2, 3", "active": "true"})
# → {"ids": [1, 2, 3], "active": True}

frontmatter_prefixes()

Returns the set[str] of namespace prefixes referenced in the frontmatter — in example binding values (prefix:local), in literal datatypes on those values ("x"^^p:t), and in literal(p:t) parameter types. Because tools blank the frontmatter before tokenizing the body, these usages are invisible to a body token stream; a linter can use this set to avoid flagging a body PREFIX declaration as unused. A full <iri> contributes no prefix; the empty string denotes the default prefix.

tmpl = compile('---\nparams { t: iri }\nexample d "" { t: schema:Person }\n---\n${t}')
tmpl.frontmatter_prefixes()   # → {"schema"}

tmpl = compile(template_string)
tmpl.schema.params                              # declared inputs
tmpl.render(service="http://dbpedia.org/sparql",
            classes=["http://example.org/Person"], limit=10)
tmpl.render({"service": "…", "classes": [...]}) # or a mapping
tmpl.preview_example("demo")                    # render a named example block

Accepted values

Each declared header type accepts:

Header type	Python value
iri, pname, string, raw, literal(<dt>)	str
int	int
decimal, double	float (or int)
bool	bool
date, dateTime, time	datetime.date / datetime / time, or an ISO str
term	an rdflib term (requires the rdflib extra)
T[]	a list of the element type
{ … } record	a dict

Custom types

def register_type(name: str, serializer: Callable[[Any, Pos], str]) -> None

Register a serializer, then use name as a header type (params { id: name }). The serializer is called as serializer(value, pos) where pos has .line and .column; it must validate value and return the exact text to emit — it is fully responsible for injection safety.

from triplate import register_type, TriplateTypeError
import re

def uuidref(value, pos):
    if not re.fullmatch(r"[0-9a-f-]{36}", str(value)):
        raise TriplateTypeError("not a UUID", pos.line, pos.column)
    return f"<urn:uuid:{value}>"

register_type("uuidref", uuidref)

Errors

class TriplateError(Exception):
    line: int | None
    column: int | None

class TriplateSyntaxError(TriplateError): ...       # compile time
class TriplateBindingError(TriplateError): ...      # render: missing/unknown/absent
class TriplateTypeError(TriplateError): ...         # render: failed validation
class TriplateCardinalityError(TriplateError): ...  # render: min/max violated

All five names are exported from the top-level triplate package.