linked-data-python 0.0.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

ldpy/runtime.py

@@ -0,0 +1,931 @@
+"""Runtime Linked-Data Python v2.
+
+The code generated by the transpiler imports this module under the reserved
+alias `_ldpy_` and uses ONLY this facade — never rdflib directly. rdflib is
+the default backend; the facade allows an alternative one (urdflib / a
+MicroPython implementation) without changing the generated code.
+
+Emission and runtime choices are explained in docs/explanation/.
+"""
+
+import itertools
+
+import rdflib
+from rdflib import RDF, BNode, Literal, Variable, Namespace
+from rdflib.term import Node
+
+_URI_CACHE = {}
+
+
+def URIRef(value, base=None):
+    """rdflib.URIRef with a cache (key = the string). The IRIs emitted by the
+    transpiler are CONSTANTS of the program: without a cache, every turn of a
+    loop over a g{...} rebuilt them (see OPTIMIZATION.md). The cache is
+    bounded by the text of the programs; a 1M-entry guard covers dynamic uses
+    through the API."""
+    if base is not None:
+        return rdflib.URIRef(value, base)
+    u = _URI_CACHE.get(value)
+    if u is None:
+        if len(_URI_CACHE) > 1_000_000:
+            return rdflib.URIRef(value)
+        u = _URI_CACHE.setdefault(value, rdflib.URIRef(value))
+    return u
+
+try:
+    from urllib.parse import urljoin as _urljoin
+except ImportError:  # MicroPython
+    def _urljoin(base, rel):
+        return base + rel
+
+import re
+_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*:")
+
+__all__ = [
+    "RDF", "URIRef", "BNode", "Literal", "Variable", "Namespace",
+    "node", "bn", "slot", "firi", "bnode", "dtype", "graph", "instantiateBGP",
+    "pname", "new_graph", "add_to", "remove_from", "match", "prepared",
+    "Bindings", "as_bindings_iter", "Coercion",
+    "sparql",
+]
+
+
+def __getattr__(name):
+    """Load ldpy.sparql on demand (avoids a circular import: sparql imports
+    node() from here)."""
+    if name == "sparql":
+        from ldpy import sparql as _s
+        globals()["sparql"] = _s
+        return _s
+    raise AttributeError(name)
+
+
+class bn:
+    """A blank-node placeholder inside a graph() call.
+
+    The index is deterministic (syntactic position in the source g{...});
+    graph() creates a fresh BNode per index AT EVERY evaluation. The
+    instances, immutable, are pooled (one per index)."""
+
+    __slots__ = ("index",)
+    _pool = {}
+
+    def __new__(cls, index):
+        inst = cls._pool.get(index)
+        if inst is None:
+            inst = super().__new__(cls)
+            object.__setattr__(inst, "index", index)
+            cls._pool[index] = inst
+        return inst
+
+    def __init__(self, index):
+        pass
+
+    def __repr__(self):
+        return "bn(%d)" % self.index
+
+
+class slot:
+    """A term shared by several triples of the same g{...}.
+
+    A term coming from an interpolation (`ex:{expr}`, `f<...{expr}...>`,
+    `{expr}`) that is the subject of several triples must be evaluated ONLY
+    ONCE: the expression is emitted at its first occurrence, `slot(i)` recalls
+    ensuite. Voir docs/explanation/emission-and-semantics.md."""
+
+    __slots__ = ("index", "value", "bound")
+
+    def __init__(self, index, *value):
+        self.index = index
+        self.bound = bool(value)
+        self.value = value[0] if value else None
+
+    def __repr__(self):
+        return "slot(%d)" % self.index
+
+
+_BNODE_SAFE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_\-]*\Z")
+
+
+def bnode(value):
+    """A blank node with a DETERMINISTIC IDENTITY derived from the data: the
+    ``_:{expr}`` .
+
+    - un BNode passe tel quel ;
+    - a string that is a safe label (letters/digits/_/-) becomes the label
+      itself: ``_:{key}`` == BNode(key);
+    - everything else — tuples in particular — is canonically encoded then
+      (``_:{(fname, lname)}`` ne
+      collide with ``_:{fname + lname}``, and the label produced stays
+      serialisable in N-Triples).
+
+    Unlike ``_:label`` (fresh at every evaluation, scoped to the island),
+    ``_:{expr}`` denotes THE SAME node wherever the value is equal — this is
+    the deduplication and blank-node-join idiom of R2RML (cases RMLTC0012a/b).
+    R2RML (cas RMLTC0012a/b)."""
+    if isinstance(value, BNode):
+        return value
+    if isinstance(value, str) and _BNODE_SAFE.match(value):
+        return _bnode_cached(value)
+    if isinstance(value, tuple):
+        canon = "\x1f".join("%d:%s" % (len(str(p)), p) for p in value)
+    else:
+        canon = "%s:%r" % (type(value).__name__, value)
+    import hashlib
+    return _bnode_cached("b" + hashlib.md5(canon.encode("utf-8")).hexdigest())
+
+
+def _bnode_cached(label, _cache={}):
+    """Reuse the existing BNode object for a label already seen (deduplication
+    workloads keep coming back to the same keys)."""
+    b = _cache.get(label)
+    if b is None:
+        if len(_cache) > 1_000_000:
+            return BNode(label)
+        b = _cache.setdefault(label, BNode(label))
+    return b
+
+
+_PASSTHROUGH = frozenset((rdflib.URIRef, Literal, BNode, Variable, bn))
+
+
+_COERCION_STACK = []
+
+
+class Coercion:
+    """Python -> RDF conversion policy (record ldpy/020): a value one names,
+    passes around and reuses — not a global setting.
+
+    Dictionary keys: a tuple of field names, or a Python type (resolved after
+    the field, through the MRO). Conversions: a datatype (IRI), URIRef to
+    build an IRI, or any function returning a term.
+    Scope: `with policy:` pushes then pops (an inner with refines the outer
+    one); `policy.install()` pushes without popping — a library uses with, an
+    application may install()."""
+
+    def __init__(self, rules):
+        self._fields = {}
+        self._types = {}
+        for key, conv in rules.items():
+            if isinstance(key, tuple):
+                for f in key:
+                    self._fields[f] = conv
+            elif isinstance(key, type):
+                self._types[key] = conv
+            else:
+                raise TypeError(
+                    "Coercion key: a tuple of field names or a Python type, "
+                    "got %r" % (key,))
+
+    def __enter__(self):
+        """Push the policy for the duration of the with."""
+        _COERCION_STACK.append(self)
+        return self
+
+    def __exit__(self, *exc):
+        """Pop, exceptions included."""
+        _COERCION_STACK.pop()
+        return False
+
+    def install(self):
+        """Push for good (a module-wide or application-wide policy)."""
+        _COERCION_STACK.append(self)
+        return self
+
+    def _rule(self, field, value_type):
+        conv = self._fields.get(field) if field is not None else None
+        if conv is None:
+            for klass in value_type.__mro__:
+                conv = self._types.get(klass)
+                if conv is not None:
+                    break
+        return conv
+
+
+def _apply_conv(conv, value):
+    """Apply a Coercion conversion: datatype, IRI, or function."""
+    if conv is rdflib.URIRef or conv is URIRef:
+        return rdflib.URIRef(str(value))
+    if conv is Literal:
+        return Literal(value)
+    if isinstance(conv, rdflib.URIRef):        # un datatype (XSD.integer, ...)
+        return Literal(value, datatype=conv)
+    return node(conv(value))
+
+
+def node(value, field=None):
+    """Coerce a Python value into an RDF term (fnode / interpolations,
+    bindings, instantiation — the single entry point of record ldpy/020).
+    An already built RDF term is never reconverted. With no policy pushed,
+    Python -> Literal, rdflib choosing the datatype.
+    Dispatch on the exact type first: rdflib's isinstance/ABC path dominated
+    the materialisation profile (see OPTIMIZATION.md)."""
+    if type(value) in _PASSTHROUGH:
+        return value
+    if isinstance(value, (Node, bn)):
+        return value
+    if _COERCION_STACK:
+        vt = type(value)
+        for pol in reversed(_COERCION_STACK):
+            conv = pol._rule(field, vt)
+            if conv is not None:
+                return _apply_conv(conv, value)
+    return Literal(value)
+
+
+def dtype(value):
+    """Coerce a value into a datatype IRI ({expr} after '^^').
+
+    A datatype is ALWAYS an IRI: unlike node(), a string is therefore read as
+    an IRI and not as a literal. Also accepts an object exposing its IRI
+    through str() (URIRef, a DefinedNamespace term)."""
+    if type(value) is rdflib.URIRef:
+        return value
+    if isinstance(value, str):
+        return URIRef(value)
+    return URIRef(str(value))
+
+
+def pname(ns, *parts):
+    """A dynamic prefixed name (record ldpy/013): concatenates the namespace
+    IRI (imported prefix, or computed IRI) and the local part."""
+    return rdflib.URIRef(
+        str(ns) + "".join(p if isinstance(p, str) else str(p) for p in parts))
+
+
+def firi(*parts, base=None):
+    """A formatted IRI: concatenate str(part), then resolve against base if relative."""
+    iri = "".join(p if isinstance(p, str) else str(p) for p in parts)
+    if base and not _SCHEME_RE.match(iri):
+        iri = _urljoin(base, iri)
+    return URIRef(iri)
+
+
+_graph_ids = itertools.count()
+_NM_CACHE = {}
+
+
+def _nm_for(namespaces):
+    """A COSMETIC NamespaceManager, shared for a given state of the
+    __namespaces__ dict: binding the prefixes costs ~100x creating the graph,
+    and a g{...} evaluated in a loop pays that price every turn (see
+    OPTIMIZATION.md). The manager is cached and attached to the graphs
+    produced — the same sharing pattern as instantiateBGP. The cache is
+    invalidated by a snapshot of the content (identity alone is not enough:
+    block scope obliges)."""
+    if not namespaces:
+        return None
+    key = id(namespaces)
+    snap = tuple(sorted((p, str(u)) for p, u in namespaces.items()))
+    hit = _NM_CACHE.get(key)
+    if hit is not None and hit[0] == snap:
+        return hit[1]
+    holder = rdflib.Graph()
+    nm = holder.namespace_manager
+    for prefix, ns in namespaces.items():
+        nm.bind(prefix, ns, replace=True)
+    _NM_CACHE[key] = (snap, nm)
+    return nm
+
+
+class _EmittedGraph(rdflib.Graph):
+    """The graph emitted by g{...}, materialised LAZILY.
+
+    The triples wait in a list; the store is only populated on the first real
+    access. rdflib reads its storage through the private attribute
+    ``_Graph__store``: a PROPERTY of the same name (a data descriptor, hence
+    taking precedence over the instance attribute) is the single point of
+    passage — any internal rdflib access materialises first. But ``__iter__``
+    serves the list WITHOUT materialising: ``target += g{...}`` then transfers
+    the triples directly — ONE store insertion instead of two (a measured
+    bottleneck: half the per-row materialisation cost)."""
+
+    __slots__ = ("_real_store", "_pending")
+
+    def __init__(self, *args, **kw):
+        self._real_store = None
+        self._pending = None
+        super().__init__(*args, **kw)
+
+    @property
+    def _Graph__store(self):
+        pending = self._pending
+        if pending is not None:
+            # `is not None`, not the truthiness of the list: an EMPTY list
+            # must switch lazy mode off too, otherwise __len__/__iter__ would
+            # keep serving [] while the store itself fills up (g{ } then
+            # .add(), or `g += g{…}`).
+            self._pending = None
+            if pending:
+                self._real_store.addN(
+                    (s, p, o, self) for s, p, o in dict.fromkeys(pending))
+        return self._real_store
+
+    @_Graph__store.setter
+    def _Graph__store(self, store):
+        self._real_store = store
+
+    def __iter__(self):
+        pending = self._pending
+        if pending is not None:
+            return iter(dict.fromkeys(pending))
+        return super().__iter__()
+
+    def __len__(self):
+        pending = self._pending
+        if pending is not None:
+            return len(dict.fromkeys(pending))
+        return super().__len__()
+
+    def __call__(self, bindings=None):
+        """g{ ... }(b): the template instantiated against the mapping b — the
+        call suffix of record ldpy/019. Bound variables and deferred
+        expressions become terms; a triple with a term still unbound is
+        dropped; blank nodes are fresh at every instantiation."""
+        pending = self._pending
+        if pending is None:
+            pending = list(super().__iter__())
+        g = _EmittedGraph(base=self.base,
+                          identifier=rdflib.URIRef("urn:x-ldpy:g%d"
+                                                   % next(_graph_ids)))
+        nm = self._Graph__namespace_manager
+        if nm is not None:
+            g.namespace_manager = nm
+        term0 = _materializer(bindings if bindings is not None else {},
+                              keep_vars=False)
+        bm = {}
+
+        def term(x):
+            v = term0(x)
+            if type(v) is BNode:
+                b = bm.get(v)
+                if b is None:
+                    b = bm[v] = BNode()
+                return b
+            return v
+
+        g._pending = [tr for tr in
+                      ((term(s), term(p), term(o)) for s, p, o in pending)
+                      if tr[0] is not None and tr[1] is not None
+                      and tr[2] is not None]
+        return g
+
+    def _merged(self, left, right):
+        """Nouveau graphe paresseux contenant left puis right (listes)."""
+        g = _EmittedGraph(base=self.base,
+                          identifier=rdflib.URIRef("urn:x-ldpy:g%d"
+                                                   % next(_graph_ids)))
+        nm = self._Graph__namespace_manager
+        if nm is not None:
+            g.namespace_manager = nm
+        g._pending = left + right
+        return g
+
+    def __add__(self, other):
+        """Lazy g1 + g2: concatenates the pending lists, no store involved.
+
+        Compositional addition (templates returning sums of g{...}) becomes
+        O(total) instead of O(n²) store insertions; deduplication (union
+        semantics) is still guaranteed at flush time."""
+        pending = self._pending
+        if pending is not None and isinstance(other, rdflib.Graph):
+            if type(other) is _EmittedGraph and other._pending is not None:
+                return self._merged(pending, other._pending)
+            return self._merged(pending, list(other))
+        return super().__add__(other)
+
+    def __iadd__(self, other):
+        """g += other, lazy as long as nothing has been materialised: the
+        boucle d'accumulation `g = g{ } ; g += g{…}` reste O(total) en
+        store insertions instead of paying one per turn."""
+        pending = self._pending
+        if pending is not None and isinstance(other, rdflib.Graph):
+            if type(other) is _EmittedGraph and other._pending is not None:
+                self._pending = pending + other._pending
+            else:
+                self._pending = pending + list(other)
+            return self
+        return super().__iadd__(other)
+
+    def __radd__(self, other):
+        """Graph() + g{...} (and therefore sum(...)) with no materialisation."""
+        pending = self._pending
+        if pending is not None and isinstance(other, rdflib.Graph):
+            return self._merged(list(other), pending)
+        return NotImplemented
+
+
+class Bindings(dict):
+    """The current bindings (record ldpy/017): a dict with str or Variable
+    keys (normalised to str), values coerced into RDF terms on assignment.
+    Everything Python can do to a dict works: b[?x] = v, update, del, **b,
+    iteration over the keys."""
+
+    def __init__(self, mapping=None):
+        dict.__init__(self)
+        if mapping is not None:
+            if not hasattr(mapping, "items"):
+                raise TypeError(
+                    "Bindings expects a mapping, got %s"
+                    % type(mapping).__name__)
+            for k, v in mapping.items():
+                self[k] = v
+
+    def __setitem__(self, key, value):
+        dict.__setitem__(self, str(key), node(value, field=str(key)))
+
+    def __getitem__(self, key):
+        return dict.__getitem__(self, str(key))
+
+    def __delitem__(self, key):
+        dict.__delitem__(self, str(key))
+
+    def __contains__(self, key):
+        return dict.__contains__(self, str(key))
+
+    def get(self, key, default=None):
+        """dict.get, str or Variable key."""
+        return dict.get(self, str(key), default)
+
+    def update(self, other=(), **kw):
+        """dict.update, going through __setitem__'s coercion."""
+        items = other.items() if hasattr(other, "items") else other
+        for k, v in items:
+            self[k] = v
+        for k, v in kw.items():
+            self[k] = v
+
+
+def as_bindings_iter(iterable):
+    """'for @bindings in ...' (record ldpy/017): every element becomes the
+    current bindings of the body. An m{ ... } yields its solutions (anonymous
+    variables excluded); any other iterable must produce mappings."""
+    if isinstance(iterable, Match):
+        for sm in iterable.solutions():
+            b = Bindings()
+            for k, v in sm.items():
+                if not str(k).startswith("__bn"):
+                    dict.__setitem__(b, str(k), v)      # already terms
+            yield b
+        return
+    for item in iterable:
+        if isinstance(item, Bindings):
+            yield item
+        elif hasattr(item, "items"):
+            yield Bindings(item)
+        else:
+            raise TypeError(
+                "for @bindings in ...: the iterable must produce mappings, "
+                "got %s" % type(item).__name__)
+
+
+_EXPR_CLASS = None
+
+
+def _expr_class():
+    """The Expression class of ldpy.sparql, loaded on demand (None if the
+    module is unavailable)."""
+    global _EXPR_CLASS
+    if _EXPR_CLASS is None:
+        try:
+            from ldpy.sparql import Expression
+            _EXPR_CLASS = Expression
+        except ImportError:
+            _EXPR_CLASS = False
+    return _EXPR_CLASS
+
+
+def _bind_get(bindings, var):
+    """A variable's value in a mapping with str or Variable keys;
+    None = unbound (the instantiateBGP convention)."""
+    v = bindings.get(var)
+    if v is None:
+        v = bindings.get(str(var))
+    return v
+
+
+def _materializer(bindings=None, keep_vars=True):
+    """Build the term materialiser of the islands (records ldpy/014, 016, 017).
+
+    bn(i) -> a BNode fresh per evaluation (memoised per index); slot -> a
+    shared value; Variable -> the bound value if bound, else the Variable
+    itself (keep_vars, template regime) or None (triple to drop)."""
+    bnodes = {}
+    slots = {}
+
+    def _term(t):
+        tt = type(t)
+        if tt in _PASSTHROUGH:
+            if tt is bn:
+                b = bnodes.get(t.index)
+                if b is None:
+                    b = bnodes[t.index] = BNode()
+                return b
+            if tt is Variable:
+                if bindings is not None:
+                    v = _bind_get(bindings, t)
+                    if v is not None:
+                        return node(v, field=str(t))
+                return t if keep_vars else None
+            return t
+        if tt is slot:
+            if t.bound:
+                # recursion, not node(): the shared value may itself be a
+                # term to materialise — a deferred expression e{ … } / e<…>
+                # in the subject position of a predicate-object list comes
+                # through here (record ldpy/017).
+                slots[t.index] = _term(t.value)
+            return slots[t.index]
+        cls = _expr_class()
+        if cls and tt is cls:
+            # e{ ... } in term position (records ldpy/007, 017): deferred
+            # without bindings, evaluated against the current bindings
+            # otherwise — a SPARQL error leaves the term unbound, the triple
+            if bindings is None:
+                return t if keep_vars else None
+            try:
+                return node(t(bindings))
+            except Exception:
+                return None
+        return node(t)
+
+    return _term
+
+
+def new_graph(namespaces, base, identifier=None):
+    """A graph created by '@graph as g' (record ldpy/014): a plain
+    rdflib.Graph, with the serialisation bindings of the prefixes in scope."""
+    g = rdflib.Graph(base=base, identifier=identifier)
+    nm = _nm_for(namespaces)
+    if nm is not None:
+        g.namespace_manager = nm
+    return g
+
+
+def add_to(graph, *triples, bindings=None):
+    """'+{ ... }': instantiate and add to the current graph (record ldpy/014).
+    A triple with a term still unbound is dropped — one cannot write an
+    unknown term."""
+    term = _materializer(bindings, keep_vars=False)
+    for s, p, o in triples:
+        s2, p2, o2 = term(s), term(p), term(o)
+        if s2 is not None and p2 is not None and o2 is not None:
+            graph.add((s2, p2, o2))
+    return graph
+
+
+def remove_from(graph, *patterns, bindings=None):
+    """'-{ ... }': removal from the current graph (record ldpy/014). An
+    unbound variable is a wildcard (rdflib's remove((s, p, None)) semantics);
+    with several patterns sharing a variable, DELETE WHERE by matching
+    (fiche 016)."""
+    has_vars = any(isinstance(x, (Variable, bn))
+                   for tr in patterns for x in tr)
+    if len(patterns) > 1 and has_vars:
+        # DELETE WHERE: match the BGP (record ldpy/016) then remove the
+        # instantiated triples — collected first, the graph must not be
+        # modified while matching.
+        prepared_pats, _ = _match_prepare(patterns, bindings)
+        to_remove = set()
+        for sm in Match(graph, patterns, (), bindings).solutions():
+            for tr in prepared_pats:
+                inst = tuple(sm.get(x) if isinstance(x, Variable) else x
+                             for x in tr)
+                if all(t is not None for t in inst):
+                    to_remove.add(inst)
+        for tr in to_remove:
+            graph.remove(tr)
+        return graph
+    term = _materializer(bindings, keep_vars=True)
+    for s, p, o in patterns:
+        tr = tuple(None if isinstance(x, (Variable, bn)) else x
+                   for x in (term(s), term(p), term(o)))
+        graph.remove(tr)
+    return graph
+
+
+def graph(namespaces, base, *triples, bindings=None):
+    """Build an rdflib.Graph (a lazy subtype) from triples
+    aplatis.
+
+    namespaces: dict prefix -> Namespace (serialisation bindings, shared
+    through _nm_for); base: lexical base IRI (str or None);
+    triples : tuples (s, p, o) pouvant contenir des placeholders bn(i).
+    With no bindings, a g{ } with variables or e{ } stays a template; with
+    the current bindings in scope, it is instantiated (record ldpy/017) — a
+    triple with a term still unbound is dropped."""
+    g = _EmittedGraph(base=base,
+                      identifier=rdflib.URIRef("urn:x-ldpy:g%d"
+                                               % next(_graph_ids)))
+    nm = _nm_for(namespaces)
+    if nm is not None:
+        g.namespace_manager = nm
+    _term = _materializer(bindings, keep_vars=(bindings is None))
+    if bindings is None:
+        g._pending = [(_term(s), _term(p), _term(o)) for s, p, o in triples]
+    else:
+        g._pending = [tr for tr in
+                      ((_term(s), _term(p), _term(o))
+                       for s, p, o in triples)
+                      if tr[0] is not None and tr[1] is not None
+                      and tr[2] is not None]
+    return g
+
+
+# ---------------------------------------------------------------- m{ ... }
+
+class Row(tuple):
+    """A solution of an m{ ... } of arity >= 2: an unpackable tuple, named
+    access (row.s) and access by variable (row[?v] or row['v'])."""
+
+    def __new__(cls, values, fields):
+        r = tuple.__new__(cls, values)
+        r._fields = fields
+        return r
+
+    def __getattr__(self, name):
+        try:
+            return self[self._fields.index(name)]
+        except ValueError:
+            raise AttributeError(name)
+
+    def __getitem__(self, key):
+        if isinstance(key, (str, Variable)):
+            return tuple.__getitem__(self, self._fields.index(str(key)))
+        return tuple.__getitem__(self, key)
+
+    def __repr__(self):
+        return "Row(%s)" % ", ".join(
+            "%s=%r" % (f, tuple.__getitem__(self, i))
+            for i, f in enumerate(self._fields))
+
+
+def _match_prepare(patterns, bindings):
+    """Patterns ready for matching: bn -> an anonymous variable shared by
+    index, slot -> a value, variables bound by the bindings -> a term."""
+    init = {}
+    if bindings:
+        for k, v in bindings.items():
+            init[Variable(str(k))] = node(v)
+    out = []
+    slots = {}
+    for s, p, o in patterns:
+        tr = []
+        for t in (s, p, o):
+            tt = type(t)
+            if tt is bn:
+                t = Variable("__bn%d" % t.index)
+            elif tt is slot:
+                if t.bound:
+                    slots[t.index] = node(t.value)
+                t = slots[t.index]
+            if isinstance(t, Variable) and t in init:
+                t = init[t]
+            tr.append(t)
+        out.append(tuple(tr))
+    return out, init
+
+
+class Match:
+    """The value of an m{ ... } island (record ldpy/016): a nested-loop join
+    over graph.triples(), in the order written — no engine, no heuristic.
+    Lazy: iterating, testing or first() only matches as much as is needed.
+    """
+
+    __slots__ = ("graph", "patterns", "project", "bindings")
+
+    def __init__(self, graph, patterns, project, bindings=None):
+        self.graph = graph
+        self.patterns = patterns
+        self.project = project
+        self.bindings = bindings
+
+    def __call__(self, graph=None, bindings=None):
+        return Match(self.graph if graph is None else graph,
+                     self.patterns, self.project,
+                     self.bindings if bindings is None else bindings)
+
+    def solutions(self):
+        """Generator of solution mappings (Bindings variable -> term),
+        initial bindings included (projected, record ldpy/019)."""
+        if self.graph is None:
+            raise RuntimeError(
+                "m{ } with no graph: declare '@graph ...' in scope, or "
+                "apply the pattern to a graph — m{ ... }(g)")
+        patterns, init = _match_prepare(self.patterns, self.bindings)
+        graph = self.graph
+
+        def join(i, sm):
+            if i == len(patterns):
+                yield sm
+                return
+            pat = []
+            var_pos = []
+            for k, t in enumerate(patterns[i]):
+                if isinstance(t, Variable):
+                    v = sm.get(t)
+                    if v is None:
+                        var_pos.append((k, t))
+                        v = None
+                    pat.append(v)
+                else:
+                    pat.append(t)
+            for found in graph.triples(tuple(pat)):
+                sm2 = dict(sm)
+                ok = True
+                for k, var in var_pos:
+                    val = found[k]
+                    prev = sm2.get(var)
+                    if prev is not None and prev != val:
+                        ok = False
+                        break
+                    sm2[var] = val
+                if ok:
+                    yield from join(i + 1, sm2)
+
+        yield from join(0, dict(init))
+
+    def __iter__(self):
+        proj = self.project
+        if len(proj) == 1:
+            v = Variable(proj[0])
+            for sm in self.solutions():
+                yield sm.get(v)
+        else:
+            vs = [Variable(x) for x in proj]
+            for sm in self.solutions():
+                yield Row((sm.get(x) for x in vs), list(proj))
+
+    def __bool__(self):
+        for _ in self.solutions():
+            return True
+        return False
+
+    def first(self):
+        """The first solution, or None if there is none (~ g.value)."""
+        for x in self:
+            return x
+        return None
+
+    def one(self):
+        """The single solution; raises if there are zero or several."""
+        it = iter(self)
+        try:
+            first = next(it)
+        except StopIteration:
+            raise ValueError("m{ }.one() : aucune solution")
+        for _ in it:
+            raise ValueError("m{ }.one() : plusieurs solutions")
+        return first
+
+    def count(self):
+        """Number of solutions — consumes the matching (len() fails)."""
+        n = 0
+        for _ in self.solutions():
+            n += 1
+        return n
+
+    def __repr__(self):
+        return "m{ %d motif(s), projection %r }" % (
+            len(self.patterns), tuple(self.project))
+
+
+def match(graph, patterns, project, bindings=None):
+    """Build the value of an m{ ... } island (record ldpy/016)."""
+    return Match(graph, patterns, project, bindings)
+
+
+# ---------------------------------------------------------------- s{ ... }
+
+_SPARQL_CACHE = {}      # (text, ns key) -> prepared query
+_SPARQL_CACHE_MAX = 64  # bounded; hand-written (no lru_cache: record ldpy/008)
+
+
+def _prepare_sparql(text, namespaces, update):
+    key = (text, update, tuple(sorted((k, str(v))
+                                      for k, v in namespaces.items())))
+    hit = _SPARQL_CACHE.get(key)
+    if hit is not None:
+        return hit
+    from rdflib.plugins.sparql import prepareQuery, prepareUpdate
+    prep = (prepareUpdate if update else prepareQuery)(
+        text, initNs=dict(namespaces))
+    if len(_SPARQL_CACHE) >= _SPARQL_CACHE_MAX:
+        _SPARQL_CACHE.pop(next(iter(_SPARQL_CACHE)))
+    _SPARQL_CACHE[key] = prep
+    return prep
+
+
+class PreparedQuery:
+    """The value of an s{ ... } island (record ldpy/015): a prepared, lazy query.
+
+    Iterating it (or testing it) runs it on its graph; calling it binds it —
+    the call suffix of record ldpy/019: graph first, bindings second."""
+
+    __slots__ = ("text", "interps", "namespaces", "base",
+                 "graph", "bindings", "update")
+
+    def __init__(self, text, interps, namespaces, base,
+                 graph=None, bindings=None, update=False):
+        self.text = text
+        self.interps = interps
+        self.namespaces = namespaces
+        self.base = base
+        self.graph = graph
+        self.bindings = bindings
+        self.update = update
+
+    def __call__(self, graph=None, bindings=None):
+        return PreparedQuery(self.text, self.interps, self.namespaces,
+                             self.base,
+                             graph if graph is not None else self.graph,
+                             bindings if bindings is not None else self.bindings,
+                             self.update)
+
+    def _init_bindings(self):
+        init = {}
+        if self.bindings:
+            for k, v in self.bindings.items():
+                init[Variable(str(k))] = node(v)
+        for name, value in self.interps:
+            init[Variable(name)] = node(value)
+        return init
+
+    def _execute(self):
+        if self.graph is None:
+            raise RuntimeError(
+                "s{ } with no graph: declare '@graph ...' in scope, or "
+                "apply the query to a graph — s{ ... }(g)")
+        prep = _prepare_sparql(self.text, self.namespaces, self.update)
+        if self.update:
+            return self.graph.update(prep, initBindings=self._init_bindings())
+        return self.graph.query(prep, initBindings=self._init_bindings())
+
+    def execute(self):
+        """Run the query and return rdflib's result.
+
+        Iterating an island, or testing its truth value, is enough for SELECT,
+        ASK and CONSTRUCT. An UPDATE returns nothing to iterate: the form is
+        what triggers it — `s{ INSERT … }.execute()`."""
+        return self._execute()
+
+    def __iter__(self):
+        return iter(self._execute())
+
+    def __bool__(self):
+        res = self._execute()
+        if getattr(res, "type", None) == "ASK":
+            return bool(res.askAnswer)
+        return res is not None and bool(len(res))
+
+    def __repr__(self):
+        return "s{ %s }" % self.text
+
+
+def prepared(text, interps, namespaces, base, graph=None, bindings=None,
+             update=False):
+    """Build the value of an s{ ... } island (record ldpy/015)."""
+    return PreparedQuery(text, interps, namespaces, base,
+                         graph, bindings, update)
+
+
+def instantiateBGP(input, solutionMappings, initialGraph=None):
+    """Instantiate a graph template (BGP) with solution mappings.
+
+    Carried over from v1 (ldpy/ldpy.py), functionally unchanged."""
+    if initialGraph is None:
+        initialGraph = rdflib.Graph(base=input.base)
+    initialGraph.namespace_manager = input.namespace_manager
+    if solutionMappings is None:
+        return initialGraph
+    if isinstance(solutionMappings, dict):
+        solutionMappings = [solutionMappings]
+    if not isinstance(solutionMappings, list):
+        raise AssertionError(
+            "solutionMappings must be a dict or a list of dicts")
+
+    def _instantiate(t, sm, bm):
+        if isinstance(t, Variable):
+            if t in sm:
+                value = sm[t]
+                if value is None:
+                    return None
+                if not isinstance(value, Node):
+                    value = node(value, field=str(t))
+                return value
+            return None
+        if isinstance(t, BNode):
+            if t not in bm:
+                bm[t] = BNode()
+            return bm[t]
+        return t
+
+    for sm in solutionMappings:
+        bm = {}
+        for s, p, o in input:
+            s2 = _instantiate(s, sm, bm)
+            p2 = _instantiate(p, sm, bm)
+            o2 = _instantiate(o, sm, bm)
+            if s2 is not None and p2 is not None and o2 is not None:
+                initialGraph.add((s2, p2, o2))
+    return initialGraph