Source code

Download source archive ↓

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")