src/rdflib/store.py
1"""## Types of store
2
3`Context-aware`: An RDF store capable of storing statements within contexts
4is considered context-aware. Essentially, such a store is able to partition
5the RDF model it represents into individual, named, and addressable
6sub-graphs.
7
8Relevant Notation3 reference regarding formulae, quoted statements, and such:
9http://www.w3.org/DesignIssues/Notation3.html
10
11`Formula-aware`: An RDF store capable of distinguishing between statements
12that are asserted and statements that are quoted is considered formula-aware.
13
14`Transaction-capable`: capable of providing transactional integrity to the
15RDF operations performed on it.
16
17`Graph-aware`: capable of keeping track of empty graphs.
18"""
19
20from __future__ import annotations
21
22import pickle
23from io import BytesIO
24from typing import (
25 TYPE_CHECKING,
26 Any,
27 Dict,
28 Generator,
29 Iterable,
30 Iterator,
31 Mapping,
32 Optional,
33 Tuple,
34 Union,
35)
36
37from rdflib.events import Dispatcher, Event
38
39if TYPE_CHECKING:
40 from rdflib.graph import (
41 Graph,
42 _ContextType,
43 _QuadType,
44 _TripleChoiceType,
45 _TriplePatternType,
46 _TripleType,
47 )
48 from rdflib.plugins.sparql.sparql import Query, Update
49 from rdflib.query import Result
50 from rdflib.term import Identifier, Node, URIRef
51
52
53# Constants representing the state of a Store (returned by the open method)
54VALID_STORE = 1
55CORRUPTED_STORE = 0
56NO_STORE = -1
57UNKNOWN: None = None
58
59
60Pickler = pickle.Pickler
61Unpickler = pickle.Unpickler
62UnpicklingError = pickle.UnpicklingError
63
64__all__ = [
65 "StoreCreatedEvent",
66 "TripleAddedEvent",
67 "TripleRemovedEvent",
68 "NodePickler",
69 "Store",
70]
71
72
73class StoreCreatedEvent(Event):
74 """This event is fired when the Store is created.
75
76 Attributes:
77 configuration: String used to create the store
78 """
79
80
81class TripleAddedEvent(Event):
82 """This event is fired when a triple is added.
83
84 Attributes:
85 triple: The triple added to the graph.
86 context: The context of the triple, if any.
87 graph: The graph to which the triple was added.
88 """
89
90
91class TripleRemovedEvent(Event):
92 """This event is fired when a triple is removed.
93
94 Attributes:
95 triple: The triple removed from the graph.
96 context: The context of the triple, if any.
97 graph: The graph from which the triple was removed.
98 """
99
100
101class NodePickler:
102 def __init__(self) -> None:
103 self._objects: Dict[str, Any] = {}
104 self._ids: Dict[Any, str] = {}
105 self._get_object = self._objects.__getitem__
106
107 def _get_ids(self, key: Any) -> Optional[str]:
108 try:
109 return self._ids.get(key)
110 except TypeError:
111 return None
112
113 def register(self, object: Any, id: str) -> None:
114 self._objects[id] = object
115 self._ids[object] = id
116
117 def loads(self, s: bytes) -> Node:
118 up = Unpickler(BytesIO(s))
119 # NOTE on type error: https://github.com/python/mypy/issues/2427
120 # type error: Cannot assign to a method
121 up.persistent_load = self._get_object # type: ignore[assignment]
122 try:
123 return up.load()
124 except KeyError as e:
125 raise UnpicklingError("Could not find Node class for %s" % e)
126
127 def dumps(
128 self, obj: Node, protocol: Optional[Any] = None, bin: Optional[Any] = None
129 ):
130 src = BytesIO()
131 p = Pickler(src)
132 # NOTE on type error: https://github.com/python/mypy/issues/2427
133 # type error: Cannot assign to a method
134 p.persistent_id = self._get_ids # type: ignore[assignment]
135 p.dump(obj)
136 return src.getvalue()
137
138 def __getstate__(self) -> Mapping[str, Any]:
139 state = self.__dict__.copy()
140 del state["_get_object"]
141 state.update(
142 {"_ids": tuple(self._ids.items()), "_objects": tuple(self._objects.items())}
143 )
144 return state
145
146 def __setstate__(self, state: Mapping[str, Any]) -> None:
147 self.__dict__.update(state)
148 self._ids = dict(self._ids)
149 self._objects = dict(self._objects)
150 self._get_object = self._objects.__getitem__
151
152
153class Store:
154 # Properties
155 context_aware: bool = False
156 formula_aware: bool = False
157 transaction_aware: bool = False
158 graph_aware: bool = False
159
160 def __init__(
161 self,
162 configuration: Optional[str] = None,
163 identifier: Optional[Identifier] = None,
164 ):
165 """Initialize the Store.
166
167 Args:
168 identifier: URIRef of the Store. Defaults to CWD
169 configuration: String containing information open can use to
170 connect to datastore.
171 """
172 self.__node_pickler: Optional[NodePickler] = None
173 self.dispatcher = Dispatcher()
174 if configuration:
175 self.open(configuration)
176
177 @property
178 def node_pickler(self) -> NodePickler:
179 if self.__node_pickler is None:
180 from rdflib.graph import Graph, QuotedGraph
181 from rdflib.term import BNode, Literal, URIRef, Variable
182
183 self.__node_pickler = np = NodePickler()
184 np.register(self, "S")
185 np.register(URIRef, "U")
186 np.register(BNode, "B")
187 np.register(Literal, "L")
188 np.register(Graph, "G")
189 np.register(QuotedGraph, "Q")
190 np.register(Variable, "V")
191 return self.__node_pickler
192
193 # Database management methods
194 # NOTE: Can't find any stores using this, we should consider deprecating it.
195 def create(self, configuration: str) -> None:
196 self.dispatcher.dispatch(StoreCreatedEvent(configuration=configuration))
197
198 def open(
199 self, configuration: Union[str, tuple[str, str]], create: bool = False
200 ) -> Optional[int]:
201 """Opens the store specified by the configuration string.
202
203 Args:
204 configuration: Store configuration string
205 create: If True, a store will be created if it doesn't exist.
206 If False and the store doesn't exist, an exception is raised.
207
208 Returns:
209 One of: VALID_STORE, CORRUPTED_STORE, or NO_STORE
210
211 Raises:
212 Exception: If there are insufficient permissions to open the store.
213 """
214 return UNKNOWN
215
216 def close(self, commit_pending_transaction: bool = False) -> None:
217 """Closes the database connection.
218
219 Args:
220 commit_pending_transaction: Whether to commit all pending
221 transactions before closing (if the store is transactional).
222 """
223
224 def destroy(self, configuration: str) -> None:
225 """Destroys the instance of the store.
226
227 Args:
228 configuration: The configuration string identifying the store instance.
229 """
230
231 def gc(self) -> None:
232 """Allows the store to perform any needed garbage collection."""
233 pass
234
235 # RDF APIs
236 def add(
237 self,
238 triple: _TripleType,
239 context: _ContextType,
240 quoted: bool = False,
241 ) -> None:
242 """Adds the given statement to a specific context or to the model.
243
244 Args:
245 triple: The triple to add
246 context: The context to add the triple to
247 quoted: If True, indicates this statement is quoted/hypothetical
248 (for formula-aware stores)
249
250 Note:
251 It should be an error to not specify a context and have the quoted
252 argument be True. It should also be an error for the quoted argument
253 to be True when the store is not formula-aware.
254 """
255 self.dispatcher.dispatch(TripleAddedEvent(triple=triple, context=context))
256
257 def addN(self, quads: Iterable[_QuadType]) -> None: # noqa: N802
258 """Adds each item in the list of statements to a specific context.
259
260 The quoted argument is interpreted by formula-aware stores to indicate this
261 statement is quoted/hypothetical.
262
263 Note:
264 The default implementation is a redirect to add.
265
266 Args:
267 quads: An iterable of quads to add
268 """
269 for s, p, o, c in quads:
270 assert c is not None, "Context associated with %s %s %s is None!" % (
271 s,
272 p,
273 o,
274 )
275 self.add((s, p, o), c)
276
277 def remove(
278 self,
279 triple: _TriplePatternType,
280 context: Optional[_ContextType] = None,
281 ) -> None:
282 """Remove the set of triples matching the pattern from the store"""
283 self.dispatcher.dispatch(TripleRemovedEvent(triple=triple, context=context))
284
285 def triples_choices(
286 self,
287 triple: _TripleChoiceType,
288 context: Optional[_ContextType] = None,
289 ) -> Generator[
290 Tuple[
291 _TripleType,
292 Iterator[Optional[_ContextType]],
293 ],
294 None,
295 None,
296 ]:
297 """
298 A variant of triples that can take a list of terms instead of a single
299 term in any slot. Stores can implement this to optimize the response
300 time from the default 'fallback' implementation, which will iterate
301 over each term in the list and dispatch to triples
302 """
303 subject, predicate, object_ = triple
304 if isinstance(object_, list):
305 assert not isinstance(subject, list), "object_ / subject are both lists"
306 assert not isinstance(predicate, list), "object_ / predicate are both lists"
307 if object_:
308 for obj in object_:
309 for (s1, p1, o1), cg in self.triples(
310 (subject, predicate, obj), context
311 ):
312 yield (s1, p1, o1), cg
313 else:
314 for (s1, p1, o1), cg in self.triples(
315 (subject, predicate, None), context
316 ):
317 yield (s1, p1, o1), cg
318
319 elif isinstance(subject, list):
320 assert not isinstance(predicate, list), "subject / predicate are both lists"
321 if subject:
322 for subj in subject:
323 for (s1, p1, o1), cg in self.triples(
324 (subj, predicate, object_), context
325 ):
326 yield (s1, p1, o1), cg
327 else:
328 for (s1, p1, o1), cg in self.triples(
329 (None, predicate, object_), context
330 ):
331 yield (s1, p1, o1), cg
332
333 elif isinstance(predicate, list):
334 assert not isinstance(subject, list), "predicate / subject are both lists"
335 if predicate:
336 for pred in predicate:
337 for (s1, p1, o1), cg in self.triples(
338 (subject, pred, object_), context
339 ):
340 yield (s1, p1, o1), cg
341 else:
342 for (s1, p1, o1), cg in self.triples((subject, None, object_), context):
343 yield (s1, p1, o1), cg
344
345 # type error: Missing return statement
346 def triples( # type: ignore[return]
347 self,
348 triple_pattern: _TriplePatternType,
349 context: Optional[_ContextType] = None,
350 ) -> Iterator[Tuple[_TripleType, Iterator[Optional[_ContextType]]]]:
351 """
352 A generator over all the triples matching the pattern. Pattern can
353 include any objects for used for comparing against nodes in the store,
354 for example, REGEXTerm, URIRef, Literal, BNode, Variable, Graph,
355 QuotedGraph, Date? DateRange?
356
357 Args:
358 context: A conjunctive query can be indicated by either
359 providing a value of None, or a specific context can be
360 queries by passing a Graph instance (if store is context aware).
361 """
362 subject, predicate, object = triple_pattern
363
364 # variants of triples will be done if / when optimization is needed
365
366 # type error: Missing return statement
367 def __len__(self, context: Optional[_ContextType] = None) -> int: # type: ignore[empty-body]
368 """
369 Number of statements in the store. This should only account for non-
370 quoted (asserted) statements if the context is not specified,
371 otherwise it should return the number of statements in the formula or
372 context given.
373
374 Args:
375 context: a graph instance to query or None
376 """
377
378 # type error: Missing return statement
379 def contexts( # type: ignore[empty-body]
380 self, triple: Optional[_TripleType] = None
381 ) -> Generator[_ContextType, None, None]:
382 """
383 Generator over all contexts in the graph. If triple is specified,
384 a generator over all contexts the triple is in.
385
386 if store is graph_aware, may also return empty contexts
387
388 :returns: a generator over Nodes
389 """
390
391 # TODO FIXME: the result of query is inconsistent.
392 def query(
393 self,
394 query: Union[Query, str],
395 initNs: Mapping[str, Any], # noqa: N803
396 initBindings: Mapping[str, Identifier], # noqa: N803
397 queryGraph: str, # noqa: N803
398 **kwargs: Any,
399 ) -> Result:
400 """If stores provide their own SPARQL implementation, override this.
401
402 queryGraph is None, a URIRef or `__UNION__`
403 If None the graph is specified in the query-string/object
404 If URIRef it specifies the graph to query,
405 If `__UNION__` the union of all named graphs should be queried
406 (This is used by ConjunctiveGraphs
407 Values other than None obviously only makes sense for
408 context-aware stores.)
409 """
410
411 raise NotImplementedError
412
413 def update(
414 self,
415 update: Union[Update, str],
416 initNs: Mapping[str, Any], # noqa: N803
417 initBindings: Mapping[str, Identifier], # noqa: N803
418 queryGraph: str, # noqa: N803
419 **kwargs: Any,
420 ) -> None:
421 """If stores provide their own (SPARQL) Update implementation, override this.
422
423 queryGraph is None, a URIRef or `__UNION__`
424 If None the graph is specified in the query-string/object
425 If URIRef it specifies the graph to query,
426 If `__UNION__` the union of all named graphs should be queried
427 (This is used by ConjunctiveGraphs
428 Values other than None obviously only makes sense for
429 context-aware stores.)
430 """
431
432 raise NotImplementedError
433
434 # Optional Namespace methods
435
436 def bind(self, prefix: str, namespace: URIRef, override: bool = True) -> None:
437 """Bind a namespace to a prefix.
438
439 Args:
440 prefix: The prefix to bind the namespace to.
441 namespace: The URIRef of the namespace to bind.
442 override: If True, rebind even if the given namespace is already bound
443 to another prefix
444 """
445
446 def prefix(self, namespace: URIRef) -> Optional[str]:
447 """"""
448
449 def namespace(self, prefix: str) -> Optional[URIRef]:
450 """ """
451
452 def namespaces(self) -> Iterator[Tuple[str, URIRef]]:
453 """ """
454 # This is here so that the function becomes an empty generator.
455 # See https://stackoverflow.com/q/13243766 and
456 # https://www.python.org/dev/peps/pep-0255/#why-a-new-keyword-for-yield-why-not-a-builtin-function-instead
457 if False:
458 yield None # type: ignore[unreachable]
459
460 # Optional Transactional methods
461
462 def commit(self) -> None:
463 """ """
464
465 def rollback(self) -> None:
466 """ """
467
468 # Optional graph methods
469
470 def add_graph(self, graph: Graph) -> None:
471 """Add a graph to the store, no effect if the graph already
472 exists.
473
474 Args:
475 graph: a Graph instance
476 """
477 raise Exception("Graph method called on non-graph_aware store")
478
479 def remove_graph(self, graph: Graph) -> None:
480 """Remove a graph from the store, this should also remove all
481 triples in the graph
482
483 Args:
484 graphid: a Graph instance
485 """
486 raise Exception("Graph method called on non-graph_aware store")