The current graph — @graph, +{ }, -{ }¶
Almost all RDF code works on one graph at a time: in a corpus of 376 real
repositories, 88 % of functions that touch a graph touch exactly one,
and its name is repeated at every operation. @graph names that graph once,
for a block; +{ } and -{ } write to it.
@graph — designate or create¶
@prefix ex: <http://example.org/> .
@graph as g # create: g = a fresh Graph
+{ ex:s ex:p 1 }
assert len(g) == 1
Three forms, all with the same block scope as
@prefix:
| Form | Effect |
|---|---|
@graph g |
designate the existing Python variable g as current |
@graph as g |
create a fresh graph, bind it to g, make it current |
@graph <iri> as g |
same, with Graph(identifier=<iri>) |
@prefix ex: <http://example.org/> .
from rdflib import Graph
mine = Graph()
@graph mine # designate: no new graph
+{ ex:s ex:p 1 }
assert len(mine) == 1
@graph <http://example.org/g1> as named
assert str(named.identifier) == "http://example.org/g1"
Either form gives the graph the prefixes in scope, so it serialises with
them and you never have to bind() them by hand:
@prefix ex: <http://example.org/ns#> .
from rdflib import Graph
mine = Graph()
@graph mine
+{ ex:a ex:p 1 }
assert "@prefix ex:" in mine.serialize(format="turtle")
For a designated graph the prefixes are added to the bindings it already
carries — it belongs to its caller, and nothing it had is discarded, nor
overwritten: a namespace the graph already binds under another prefix keeps
that prefix, and a prefix it already gives another namespace keeps that
namespace. @prefix names terms in your source; how somebody else's graph
serialises stays theirs. To impose a binding, call g.bind(…) yourself.
from rdflib import Graph
theirs = Graph()
theirs.bind("xs", "http://www.w3.org/2001/XMLSchema#")
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@graph theirs
+{ <http://example.org/a> <http://example.org/v> "1"^^xsd:integer }
assert str(dict(theirs.namespaces())["xs"]) == "http://www.w3.org/2001/XMLSchema#"
The identifier is nothing more than rdflib's Graph(identifier=…)
constructor parameter. @graph designates a graph, possibly named — never
a dataset or a space of graphs; that usage was measured at 6.8 % of graph
constructions and is left to rdflib's own API.
+{ ... } and -{ ... } — write to it¶
Both take a Turtle-notation pattern, exactly like g{ }, and are
statements: they produce no value.
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:s ex:p 1 ; ex:q 2 } # add two triples
-{ ex:s ex:q 2 } # remove one
for i in range(3):
+{ ex:s ex:n {i} } # one triple per iteration
assert len(g) == 4
They are accepted in statement position at bracket depth zero: at the
start of a logical line, after a ;, and as the suite of a compound
statement (if cond: +{ … } on one line). Everywhere else + and - keep
their Python meaning — keys - {'a'} stays a set difference. In statement
position, +{…} is legal Python but always dead (unary plus on a set or
dict raises TypeError), so capturing it costs no real code. The full rule is
in the lexical reference.
The emitted code calls add_to / remove_from, never +=. That is what
makes a read-only property or a module global writable with no global
declaration and no __iadd__ dance — a limitation the corpus study ran into
repeatedly.
Variables in +{ } and -{ }¶
Both accept variables, both instantiate them against the current bindings, and the direction decides what an unbound variable means:
| Island | Unbound variable |
|---|---|
+{ } |
the triple is dropped — an unknown term cannot be written |
-{ } |
a wildcard — as in rdflib's remove((s, p, None)) |
An interpolated None is neither: -{ {s} ex:p {o} } with o = None
raises TypeError. It used to remove nothing — the term looked for was the
literal "None" — without a word. When the wildcard arrives as data, a
pattern (s, p, None) handed to a helper, interpolate ldpy.ANY, which
-{ } reads as rdflib reads None, and which +{ } refuses to write:
import ldpy
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:s ex:p 1 ; ex:q 2 }
def delete(pattern):
s, p, o = (ldpy.ANY if t is None else t for t in pattern)
-{ {s} {p} {o} }
delete((ex:s, ex:p, None))
assert len(g) == 1
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:s ex:p 1 ; ex:q 2 ; ex:r 3 }
-{ ex:s ?p ?o } # wildcards: removes everything
assert len(g) == 0
A multi-pattern -{ } whose patterns share variables removes by matching,
like SPARQL's DELETE WHERE:
@prefix ex: <http://example.org/> .
@graph as g
+{ ex:a a ex:Draft ; ex:body "x" . ex:b a ex:Final ; ex:body "y" }
-{ ?s a ex:Draft ; ex:body ?b } # only the draft and its body
assert len(g) == 2
A block is evaluated, then written¶
A +{ } or -{ } block is one statement, not a sequence of calls: every
term is evaluated, left to right, before the first triple is written or
removed. If one raises, the graph is left as it was.
@prefix ex: <http://example.org/> .
@graph as g
def unknown():
raise ValueError("no value")
try:
+{ ex:s ex:p 1 ; ex:q {unknown()} }
except ValueError:
pass
assert len(g) == 0 # not even `ex:s ex:p 1`
A sequence of g.add(…) calls behaves differently: the triples added before
the failing one stay. Code that relies on that partial graph — rare, since
the exception usually discards it — must keep the earlier triples in a block
of their own.
Which graph does an island use?¶
+{ }, -{ }, m{ } and s{ } all read the current graph. If none is
declared in scope, they raise at run time — unless the graph is given by the
call suffix:
@prefix ex: <http://example.org/> .
from rdflib import Graph
other = Graph()
+{ ex:s ex:p 1 }(other) # explicit receiver, no @graph needed
assert len(other) == 1
The receiver is not limited to a bare name: the parenthesis takes any Python
expression that evaluates to a graph — an attribute, a subscript, a method
call. That is what lets the island work unmodified inside object-oriented
code, including against a read-only property, where g += g{ } cannot:
+= needs to assign the result back through the property, and a
property with no setter refuses it, while +{ }(...) never assigns to its
receiver at all — it calls add_to on whatever the expression returns.
@prefix ex: <http://example.org/> .
from rdflib import Graph
class Store:
def __init__(self):
self._graph = Graph()
@property
def graph(self): # read-only: no setter
return self._graph
def get_graph(self):
return self._graph
store = Store()
graphs = [Graph(), Graph()]
+{ ex:s ex:p 1 }(store.graph) # attribute
+{ ex:s ex:p 2 }(graphs[1]) # subscript
+{ ex:s ex:p 3 }(store.get_graph()) # method call
assert len(store.graph) == 2 and len(graphs[1]) == 1
Scope, and escaping it¶
@graph follows the block-scope rule, so a graph created inside an if or a
for disappears with it. global and nonlocal
work as in Python and
are how you keep it: