How to migrate rdflib code to ldpy¶
Adoption is file by file: .ldpy is a superset of Python, so renaming a
.py to .ldpy changes nothing until you write your first island. This guide
gives the mechanical rewrites, then the traps that silently change meaning.
Rename, then rewrite what pays¶
Nothing else. The file transpiles to itself, byte for byte, and imports the same way once the hook is installed:
The mechanical rewrites¶
| rdflib | ldpy |
|---|---|
EX = Namespace("http://e/") then EX.Thing |
@prefix ex: <http://e/> . then ex:Thing |
URIRef("http://e/a") |
<http://e/a> |
URIRef(BASE + path) |
f<{path}> with @base <…> . — see the trap below |
Literal("x", lang="en") |
"x"@en |
Literal("1", datatype=XSD.integer) |
"1"^^xsd:integer |
Variable("v") |
?v |
g.add((s, RDF.type, EX.C)) |
+{ {s} a ex:C } with @graph g |
a run of g.add(...) on one subject |
one +{ … ; … ; … } |
g += other |
unchanged |
for o in g.objects(s, EX.p) |
for o in m{ {s} ex:p ?o } |
g.value(s, EX.p) |
m{ {s} ex:p ?v }.first() |
g.value(s, EX.p, default=x) |
m{ {s} ex:p ?v }.first(default=x) |
next(g.objects(s, EX.p)) (raises on none) |
next(iter(m{ {s} ex:p ?o })) |
Literal(v, lang=k) |
{v}@{k} |
next(g.subjects(RDF.type, EX.C)) |
m{ ?s a ex:C }.first() |
set(g.subjects()) |
{s for s, p in m{ ?s ?p [] }} |
(s, p, o) in g |
bool(m{ … }) |
g.remove((s, p, None)) |
-{ {s} {p} ?any } |
a pattern (s, p, None) received as data |
None → ldpy.ANY, then -{ {s} {p} {o} } |
g.query(TEXT) |
s{ … } — checked at transpile time |
g.query(q, initBindings={"s": t}) |
s{ … ?s … } with {t} in term position |
from .namespaces import BRICK |
from .namespaces import brick: |
set(g.subjects()) is worth spelling out, because the obvious reading of the
table row above is wrong. [] is a non-distinguished
variable — matched but never projected
— but that only works as an object: RDF predicates are IRIs, so [] in
predicate position is refused (predicate expected), and ?p has to stand
there as an ordinary variable instead. An ordinary variable is projected,
so the pattern's arity is two, not one, and the result is pairs, not
subjects — unpack the pair:
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:a ex:p 1 ; ex:q 2 . ex:b ex:p 3 }
subjects = {s for s, p in m{ ?s ?p [] }}
assert subjects == {ex:a, ex:b}
Here is the shape most code takes, before and after:
from rdflib import Graph, Literal, Namespace, RDF, URIRef
EX = Namespace("http://example.org/")
g = Graph()
for row in [{"id": "a", "v": 1}, {"id": "b", "v": 2}]:
s = URIRef("http://example.org/" + row["id"])
g.add((s, RDF.type, EX.Thing))
g.add((s, EX.value, Literal(row["v"])))
assert len(g) == 4
@prefix ex: <http://example.org/> .
@graph as g
for @bindings in [{"id": "a", "v": 1}, {"id": "b", "v": 2}]:
+{ e<http://example.org/{?id}> a ex:Thing ; ex:value ?v }
assert len(g) == 4
Trap 1: Literal(n, datatype=…) is not "n"^^dt¶
rdflib normalises the lexical form of a typed literal built from a Python
value. Literal(40, datatype=XSD.double) has lexical form "40.0", while
"40"^^xsd:double has lexical form "40". They are different RDF terms, and
== says so.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
from rdflib import Literal
from rdflib.namespace import XSD
written = "40"^^xsd:double
built = Literal(40, datatype=XSD.double)
assert written != built # same value, different term
assert float(written) == float(built)
So a mechanical rule Literal(n, dt) → "n"^^dt is wrong. Rewrite it as
{n}^^dt, which goes through the same conversion rdflib does:
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
from rdflib import Literal
from rdflib.namespace import XSD
n = 40
assert f{Literal(n, datatype=XSD.double)} == Literal(40, datatype=XSD.double)
Trap 2: URIRef(x) is not f<{x}> when a base is in scope¶
f<...> resolves against the @base in scope; URIRef(x) does not resolve
anything. The two agree only when there is no base, or when x is already
absolute.
@base <http://example.org/data/> .
from rdflib import URIRef
x = "sensor/1"
assert str(f<{x}>) == "http://example.org/data/sensor/1"
assert str(URIRef(x)) == "sensor/1" # not the same term
Trap 3: a string that looks like an IRI is still a literal¶
Translating is a human job: it is the translator, not the transpiler, who
knows that a given Python constant denotes an IRI rather than a literal.
The transpiler never guesses a term's kind from what a string contains —
that is deliberate, and documented as the default
— so a Python string in term position becomes a Literal, even one that
reads like an IRI:
@prefix ex: <http://example.org/> .
@graph as g
looks_like_an_iri = "http://example.org/a"
+{ ex:s ex:p {looks_like_an_iri} }
term = m{ ex:s ex:p ?v }.one()
assert type(term).__name__ == "Literal"
The fix is not a conversion, it is writing the constant with its island
notation instead of a Python string: <http://example.org/a> reads exactly
the same as the string above, minus the quotes, and it is an IRI because
that is what the notation means, not because of what it contains.
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:s ex:p <http://example.org/a> }
term = m{ ex:s ex:p ?v }.one()
assert type(term).__name__ == "URIRef"
Trap 4: interpolating into s{ } coerces, and coerces silently¶
An assembled query wraps its IRI in angle brackets, because at that point it
is only text: g.query(f"SELECT ?s WHERE {{ ?s a <{cls}> }}"). The island's
{expr} is not text substitution — it becomes an initial binding, and the
value goes through the ordinary coercion.
A bare str therefore becomes a literal, and the query matches nothing:
@prefix ex: <http://example.org/> .
from rdflib import URIRef
@graph as g
+{ ex:a a ex:Thing }
cls = "http://example.org/Thing"
assert len(list(s{ SELECT ?s WHERE { ?s a {cls} } }.execute())) == 0
assert len(list(s{ SELECT ?s WHERE { ?s a {URIRef(cls)} } }.execute())) == 1
Nothing raises. The result is simply empty, which is indistinguishable from
"no match" — so a test whose fixture happens to be thin passes anyway. This is
trap 2 in another position: wherever the original spelled an IRI by wrapping
text in <...>, the translation has to say so.
Trap 5: None is not a wildcard¶
rdflib reads None in a pattern as "any term", and code that passes
patterns around as data relies on it: delete((s, p, None)). Interpolated
into an island, None raises TypeError — a wildcard written as a missing
value is too easy to write by accident. Map it to ldpy.ANY where the
pattern arrives, or write a variable where the wildcard is part of the
pattern (-{ {s} {p} ?any }, m{ {s} ex:p [] }). See
the table of -{ }.
Trap 6: "{x}" in a literal does not interpolate — f"{x}" does¶
In term position {expr} interpolates: ex:{name}, a bare {value}, the
{dt} after ^^. Inside the quoted part of a literal it does not,
exactly as in Python:
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
x = "42"
assert str("{x}"^^xsd:string) == "{x}" # three characters, as written
assert str(f"{x}"^^xsd:string) == "42" # the value
This is consistent — a quoted string is a Python string, and Python needs the
f too — but the two braces sit one character apart and only one of them
interpolates. Nothing warns: the graph simply carries the wrong literal.
What not to rewrite¶
Some rdflib code has no better form in ldpy, and the notation is honest about it:
- A plain literal:
Literal("x")has no island spelling outside a graph. Inside one, position makes it a literal; outside, keepLiteral. - A variable language tag:
Literal(x, lang=code)has no form at all. - A
Namespaceas an object:@prefixis a lexical declaration, not a value. If you need to pass a namespace around, keep theNamespaceconstant — and note that ldpy binds your declared prefixes on the graphs it creates, so serialisation already looks right. - A
Datasetor aConjunctiveGraph:@graphdesignates one graph, and named-graph spaces stay rdflib's API. - A full, unfiltered traversal:
list(g)stayslist(g).m{ }does have a form for it —list(m{ ?s ?p ?o }(g))— but that names three variables the original code never had to, for the identical rows; see keeplist(g)for a full scan. Reservem{ }for a pattern that actually selects. - String-embedded RDF: a CURIE inside a data string
(
method="qb:CodedProperty"), a query in a config file — these are strings, and ldpy never looks inside strings. That is a guarantee, not a gap.
Check the translation¶
The corpus study translated 140 programs and proved each pair equivalent by RDF isomorphism, using rdflib as the oracle. Do the same for anything non-trivial:
from rdflib import Graph
from rdflib.compare import isomorphic
before = Graph().parse(data="<http://e/a> <http://e/p> 1 .", format="turtle")
after = Graph().parse(data="<http://e/a> <http://e/p> 1 .", format="turtle")
assert isomorphic(before, after)
What that study found about the limits of the notation, at scale, is in what real RDF code does.