Source code

Download source archive ↓

src/rdflib/plugins/stores/sparqlstore.py

1"""
2This is an RDFLib store around Ivan Herman et al.'s SPARQL service wrapper.
3This was first done in layer-cake, and then ported to RDFLib
4"""
5
6from __future__ import annotations
7
8import collections
9import re
10from typing import (
11    TYPE_CHECKING,
12    Any,
13    Callable,
14    Dict,
15    Generator,
16    Iterable,
17    Iterator,
18    List,
19    Mapping,
20    Optional,
21    Tuple,
22    Union,
23    overload,
24)
25
26from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, Graph
27from rdflib.plugins.stores.regexmatching import NATIVE_REGEX
28from rdflib.store import Store
29from rdflib.term import BNode, Identifier, Node, URIRef, Variable
30
31if TYPE_CHECKING:
32    import typing_extensions as te  # noqa: I001
33    from rdflib.graph import (
34        _TripleType,
35        _ContextType,
36        _QuadType,
37        _TripleChoiceType,
38        _TriplePatternType,
39        _SubjectType,
40        _PredicateType,
41        _ObjectType,
42        _ContextIdentifierType,
43    )
44    from rdflib.plugins.sparql.sparql import Query, Update
45    from rdflib.query import Result, ResultRow
46
47from .sparqlconnector import SPARQLConnector
48
49# Defines some SPARQL keywords
50LIMIT = "LIMIT"
51OFFSET = "OFFSET"
52ORDERBY = "ORDER BY"
53
54BNODE_IDENT_PATTERN = re.compile(r"(?P<label>_\:[^\s]+)")
55
56_NodeToSparql = Callable[["Node"], str]
57
58
59def _node_to_sparql(node: Node) -> str:
60    if isinstance(node, BNode):
61        raise Exception(
62            "SPARQLStore does not support BNodes! "
63            "See http://www.w3.org/TR/sparql11-query/#BGPsparqlBNodes"
64        )
65    return node.n3()
66
67
68class SPARQLStore(SPARQLConnector, Store):
69    """An RDFLib store around a SPARQL endpoint
70
71    This is context-aware and should work as expected
72    when a context is specified.
73
74    For ConjunctiveGraphs, reading is done from the "default graph". Exactly
75    what this means depends on your endpoint, because SPARQL does not offer a
76    simple way to query the union of all graphs as it would be expected for a
77    ConjuntiveGraph. This is why we recommend using Dataset instead, which is
78    motivated by the SPARQL 1.1.
79
80    Fuseki/TDB has a flag for specifying that the default graph
81    is the union of all graphs (`tdb:unionDefaultGraph` in the Fuseki config).
82
83    !!! warning "Blank nodes
84
85        By default the SPARQL Store does not support blank-nodes!
86
87        As blank-nodes act as variables in SPARQL queries,
88        there is no way to query for a particular blank node without
89        using non-standard SPARQL extensions.
90
91        See http://www.w3.org/TR/sparql11-query/#BGPsparqlBNodes
92
93    You can make use of such extensions through the `node_to_sparql`
94    argument. For example if you want to transform BNode('0001') into
95    "<bnode:b0001>", you can use a function like this:
96
97    ```python
98    >>> def my_bnode_ext(node):
99    ...    if isinstance(node, BNode):
100    ...        return '<bnode:b%s>' % node
101    ...    return _node_to_sparql(node)
102    >>> store = SPARQLStore('http://dbpedia.org/sparql',
103    ...                     node_to_sparql=my_bnode_ext)
104
105    ```
106
107    You can request a particular result serialization with the
108    `returnFormat` parameter. This is a string that must have a
109    matching plugin registered. Built in is support for `xml`,
110    `json`, `csv`, `tsv` and `application/rdf+xml`.
111
112    The underlying SPARQLConnector uses the urllib library.
113    Any extra kwargs passed to the SPARQLStore connector are passed to
114    urllib when doing HTTP calls. I.e. you have full control of
115    cookies/auth/headers.
116
117    Form example:
118
119    ```python
120    >>> store = SPARQLStore('...my endpoint ...', auth=('user','pass'))
121
122    ```
123
124    will use HTTP basic auth.
125    """
126
127    formula_aware = False
128    transaction_aware = False
129    graph_aware = True
130    regex_matching = NATIVE_REGEX
131
132    def __init__(
133        self,
134        query_endpoint: Optional[str] = None,
135        sparql11: bool = True,
136        context_aware: bool = True,
137        node_to_sparql: _NodeToSparql = _node_to_sparql,
138        returnFormat: Optional[str] = "xml",  # noqa: N803
139        auth: Optional[Tuple[str, str]] = None,
140        **sparqlconnector_kwargs,
141    ):
142        super(SPARQLStore, self).__init__(
143            query_endpoint=query_endpoint,
144            returnFormat=returnFormat,
145            auth=auth,
146            **sparqlconnector_kwargs,
147        )
148
149        self.node_to_sparql = node_to_sparql
150        self.nsBindings: Dict[str, Any] = {}
151        self.sparql11 = sparql11
152        self.context_aware = context_aware
153        self.graph_aware = context_aware
154        self._queries = 0
155
156    # type error: Missing return statement
157    def open(self, configuration: Union[str, tuple[str, str]], create: bool = False) -> Optional[int]:  # type: ignore[return]
158        """This method is included so that calls to this Store via Graph, e.g. Graph("SPARQLStore"),
159        can set the required parameters
160        """
161        if type(configuration) is str:
162            self.query_endpoint = configuration
163        else:
164            raise Exception(
165                "configuration must be a string (a single query endpoint URI)"
166            )
167
168    # Database Management Methods
169    def create(self, configuration: str) -> None:
170        raise TypeError(
171            "The SPARQL Store is read only. Try SPARQLUpdateStore for read/write."
172        )
173
174    def destroy(self, configuration: str) -> None:
175        raise TypeError("The SPARQL store is read only")
176
177    # Transactional interfaces
178    def commit(self) -> None:
179        raise TypeError("The SPARQL store is read only")
180
181    def rollback(self) -> None:
182        raise TypeError("The SPARQL store is read only")
183
184    def add(
185        self, _: _TripleType, context: _ContextType = None, quoted: bool = False
186    ) -> None:
187        raise TypeError("The SPARQL store is read only")
188
189    def addN(self, quads: Iterable[_QuadType]) -> None:  # noqa: N802
190        raise TypeError("The SPARQL store is read only")
191
192    # type error: Signature of "remove" incompatible with supertype "Store"
193    def remove(  # type: ignore[override]
194        self, _: _TriplePatternType, context: Optional[_ContextType]
195    ) -> None:
196        raise TypeError("The SPARQL store is read only")
197
198    # type error: Signature of "update" incompatible with supertype "SPARQLConnector"
199    def update(  # type: ignore[override]
200        self,
201        query: Union[Update, str],
202        initNs: Dict[str, Any] = {},  # noqa: N803
203        initBindings: Dict[str, Identifier] = {},  # noqa: N803
204        queryGraph: Identifier = None,  # noqa: N803
205        DEBUG: bool = False,  # noqa: N803
206    ) -> None:
207        raise TypeError("The SPARQL store is read only")
208
209    def _query(self, *args: Any, **kwargs: Any) -> Result:
210        self._queries += 1
211
212        return super(SPARQLStore, self).query(*args, **kwargs)
213
214    def _inject_prefixes(self, query: str, extra_bindings: Mapping[str, Any]) -> str:
215        bindings = set(list(self.nsBindings.items()) + list(extra_bindings.items()))
216        if not bindings:
217            return query
218        return "\n".join(
219            [
220                "\n".join(["PREFIX %s: <%s>" % (k, v) for k, v in bindings]),
221                "",  # separate ns_bindings from query with an empty line
222                query,
223            ]
224        )
225
226    # type error: Signature of "query" incompatible with supertype "SPARQLConnector"
227    # type error: Signature of "query" incompatible with supertype "Store"
228    def query(  # type: ignore[override]
229        self,
230        query: Union[Query, str],
231        initNs: Optional[Mapping[str, Any]] = None,  # noqa: N803
232        initBindings: Optional[Mapping[str, Identifier]] = None,  # noqa: N803
233        queryGraph: Optional[str] = None,  # noqa: N803
234        DEBUG: bool = False,  # noqa: N803
235    ) -> Result:
236        self.debug = DEBUG
237        assert isinstance(query, str)
238
239        if initNs is not None and len(initNs) > 0:
240            query = self._inject_prefixes(query, initNs)
241
242        if initBindings:
243            if not self.sparql11:
244                raise Exception("initBindings not supported for SPARQL 1.0 Endpoints.")
245            v = list(initBindings)
246
247            # VALUES was added to SPARQL 1.1 on 2012/07/24
248            query += "\nVALUES ( %s )\n{ ( %s ) }\n" % (
249                " ".join("?" + str(x) for x in v),
250                " ".join(self.node_to_sparql(initBindings[x]) for x in v),
251            )
252
253        return self._query(
254            query, default_graph=queryGraph if self._is_contextual(queryGraph) else None
255        )
256
257    # type error: Return type "Iterator[Tuple[Tuple[Node, Node, Node], None]]" of "triples" incompatible with return type "Iterator[Tuple[Tuple[Node, Node, Node], Iterator[Optional[Graph]]]]"
258    def triples(  # type: ignore[override]
259        self, spo: _TriplePatternType, context: Optional[_ContextType] = None
260    ) -> Iterator[Tuple[_TripleType, None]]:
261        """
262        - tuple **(s, o, p)**
263          the triple used as filter for the SPARQL select.
264          (None, None, None) means anything.
265        - context **context**
266          the graph effectively calling this method.
267
268        Returns a tuple of triples executing essentially a SPARQL like
269        SELECT ?subj ?pred ?obj WHERE { ?subj ?pred ?obj }
270
271        **context** may include three parameter
272        to refine the underlying query:
273
274        * LIMIT: an integer to limit the number of results
275        * OFFSET: an integer to enable paging of results
276        * ORDERBY: an instance of Variable('s'), Variable('o') or Variable('p') or, by default, the first 'None' from the given triple
277
278        !!! warning "Limit and offset
279
280            - Using LIMIT or OFFSET automatically include ORDERBY otherwise this is
281              because the results are retrieved in a not deterministic way (depends on
282              the walking path on the graph)
283            - Using OFFSET without defining LIMIT will discard the first OFFSET - 1 results
284
285        ```python
286        a_graph.LIMIT = limit
287        a_graph.OFFSET = offset
288        triple_generator = a_graph.triples(mytriple):
289        # do something
290        # Removes LIMIT and OFFSET if not required for the next triple() calls
291        del a_graph.LIMIT
292        del a_graph.OFFSET
293        ```
294        """
295
296        s, p, o = spo
297
298        vars = []
299        if not s:
300            s = Variable("s")
301            vars.append(s)
302
303        if not p:
304            p = Variable("p")
305            vars.append(p)
306        if not o:
307            o = Variable("o")
308            vars.append(o)
309
310        if vars:
311            v = " ".join([term.n3() for term in vars])
312            verb = "SELECT %s " % v
313        else:
314            verb = "ASK"
315
316        nts = self.node_to_sparql
317        query = "%s { %s %s %s }" % (verb, nts(s), nts(p), nts(o))
318
319        # The ORDER BY is necessary
320        if (
321            hasattr(context, LIMIT)
322            or hasattr(context, OFFSET)
323            or hasattr(context, ORDERBY)
324        ):
325            var = None
326            if isinstance(s, Variable):
327                var = s
328            elif isinstance(p, Variable):
329                var = p
330            elif isinstance(o, Variable):
331                var = o
332            elif hasattr(context, ORDERBY) and isinstance(
333                getattr(context, ORDERBY), Variable
334            ):
335                var = getattr(context, ORDERBY)
336            # type error: Item "None" of "Optional[Variable]" has no attribute "n3"
337            query = query + " %s %s" % (ORDERBY, var.n3())  # type: ignore[union-attr]
338
339        try:
340            query = query + " LIMIT %s" % int(getattr(context, LIMIT))
341        except (ValueError, TypeError, AttributeError):
342            pass
343        try:
344            query = query + " OFFSET %s" % int(getattr(context, OFFSET))
345        except (ValueError, TypeError, AttributeError):
346            pass
347
348        result = self._query(
349            query,
350            # type error: Item "None" of "Optional[Graph]" has no attribute "identifier"
351            default_graph=context.identifier if self._is_contextual(context) else None,  # type: ignore[union-attr]
352        )
353
354        if vars:
355            if type(result) is tuple:
356                if result[0] == 401:
357                    raise ValueError(
358                        "It looks like you need to authenticate with this SPARQL Store. HTTP unauthorized"
359                    )
360            for row in result:
361                if TYPE_CHECKING:
362                    # This will be a ResultRow because if vars is truthish then
363                    # the query will be a SELECT query.
364                    assert isinstance(row, ResultRow)
365                yield (
366                    # type error: No overload variant of "get" of "ResultRow" matches argument types "Node", "Node"
367                    row.get(s, s),  # type: ignore[call-overload]
368                    row.get(p, p),  # type: ignore[call-overload]
369                    row.get(o, o),  # type: ignore[call-overload]
370                ), None  # why is the context here not the passed in graph 'context'?
371        else:
372            if result.askAnswer:
373                yield (s, p, o), None
374
375    def triples_choices(
376        self,
377        _: _TripleChoiceType,
378        context: Optional[_ContextType] = None,
379    ) -> Generator[
380        Tuple[
381            Tuple[_SubjectType, _PredicateType, _ObjectType],
382            Iterator[Optional[_ContextType]],
383        ],
384        None,
385        None,
386    ]:
387        """
388        A variant of triples that can take a list of terms instead of a
389        single term in any slot.  Stores can implement this to optimize
390        the response time from the import default 'fallback' implementation,
391        which will iterate over each term in the list and dispatch to
392        triples.
393        """
394        raise NotImplementedError("Triples choices currently not supported")
395
396    def __len__(self, context: Optional[_ContextType] = None) -> int:
397        if not self.sparql11:
398            raise NotImplementedError(
399                "For performance reasons, this is not"
400                + "supported for sparql1.0 endpoints"
401            )
402        else:
403            q = "SELECT (count(*) as ?c) WHERE {?s ?p ?o .}"
404
405            result = self._query(
406                q,
407                # type error: Item "None" of "Optional[Graph]" has no attribute "identifier"
408                default_graph=(
409                    context.identifier  # type: ignore[union-attr]
410                    if self._is_contextual(context)
411                    else None
412                ),
413            )
414            # type error: Item "Tuple[Node, ...]" of "Union[Tuple[Node, Node, Node], bool, ResultRow]" has no attribute "c"
415            return int(next(iter(result)).c)  # type: ignore[union-attr]
416
417    # type error: Return type "Generator[Identifier, None, None]" of "contexts" incompatible with return type "Generator[Graph, None, None]" in supertype "Store"
418    def contexts(  # type: ignore[override]
419        self, triple: Optional[_TripleType] = None
420    ) -> Generator[_ContextIdentifierType, None, None]:
421        """
422        Iterates over results to `SELECT ?NAME { GRAPH ?NAME { ?s ?p ?o } }`
423        or `SELECT ?NAME { GRAPH ?NAME {} }` if triple is `None`.
424
425        Returns instances of this store with the SPARQL wrapper
426        object updated via addNamedGraph(?NAME).
427
428        This causes a named-graph-uri key / value  pair to be sent over
429        the protocol.
430
431        Please note that some SPARQL endpoints are not able to find empty named
432        graphs.
433        """
434
435        if triple:
436            nts = self.node_to_sparql
437            s, p, o = triple
438            params = (
439                nts(s if s else Variable("s")),
440                nts(p if p else Variable("p")),
441                nts(o if o else Variable("o")),
442            )
443            q = "SELECT ?name WHERE { GRAPH ?name { %s %s %s }}" % params
444        else:
445            q = "SELECT ?name WHERE { GRAPH ?name {} }"
446
447        result = self._query(q)
448        # type error: Item "bool" of "Union[Tuple[Node, Node, Node], bool, ResultRow]" has no attribute "name"
449        # error: Generator has incompatible item type "Union[Any, Identifier]"; expected "IdentifiedNode"
450        return (row.name for row in result)  # type: ignore[union-attr,misc]
451
452    # Namespace persistence interface implementation
453    def bind(self, prefix: str, namespace: URIRef, override: bool = True) -> None:
454        bound_prefix = self.prefix(namespace)
455        if override and bound_prefix:
456            del self.nsBindings[bound_prefix]
457        self.nsBindings[prefix] = namespace
458
459    def prefix(self, namespace: URIRef) -> Optional[str]:
460        """ """
461        return dict([(v, k) for k, v in self.nsBindings.items()]).get(namespace)
462
463    def namespace(self, prefix: str) -> Optional[URIRef]:
464        return self.nsBindings.get(prefix)
465
466    def namespaces(self) -> Iterator[Tuple[str, URIRef]]:
467        for prefix, ns in self.nsBindings.items():
468            yield prefix, ns
469
470    def add_graph(self, graph: Graph) -> None:
471        raise TypeError("The SPARQL store is read only")
472
473    def remove_graph(self, graph: Graph) -> None:
474        raise TypeError("The SPARQL store is read only")
475
476    @overload
477    def _is_contextual(self, graph: None) -> te.Literal[False]: ...
478
479    @overload
480    def _is_contextual(self, graph: Optional[Union[Graph, str]]) -> bool: ...
481
482    def _is_contextual(self, graph: Optional[Union[Graph, str]]) -> bool:
483        """Returns `True` if the "GRAPH" keyword must appear
484        in the final SPARQL query sent to the endpoint.
485        """
486        if (not self.context_aware) or (graph is None):
487            return False
488        if isinstance(graph, str):
489            return graph != "__UNION__"
490        else:
491            return graph.identifier != DATASET_DEFAULT_GRAPH_ID
492
493    def subjects(
494        self,
495        predicate: Optional[_PredicateType] = None,
496        object: Optional[_ObjectType] = None,
497    ) -> Generator[_SubjectType, None, None]:
498        """A generator of subjects with the given predicate and object"""
499        for t, c in self.triples((None, predicate, object)):
500            yield t[0]
501
502    def predicates(
503        self,
504        subject: Optional[_SubjectType] = None,
505        object: Optional[_ObjectType] = None,
506    ) -> Generator[_PredicateType, None, None]:
507        """A generator of predicates with the given subject and object"""
508        for t, c in self.triples((subject, None, object)):
509            yield t[1]
510
511    def objects(
512        self,
513        subject: Optional[_SubjectType] = None,
514        predicate: Optional[_PredicateType] = None,
515    ) -> Generator[_ObjectType, None, None]:
516        """A generator of objects with the given subject and predicate"""
517        for t, c in self.triples((subject, predicate, None)):
518            yield t[2]
519
520    def subject_predicates(
521        self, object: Optional[_ObjectType] = None
522    ) -> Generator[Tuple[_SubjectType, _PredicateType], None, None]:
523        """A generator of (subject, predicate) tuples for the given object"""
524        for t, c in self.triples((None, None, object)):
525            yield t[0], t[1]
526
527    def subject_objects(
528        self, predicate: Optional[_PredicateType] = None
529    ) -> Generator[Tuple[_SubjectType, _ObjectType], None, None]:
530        """A generator of (subject, object) tuples for the given predicate"""
531        for t, c in self.triples((None, predicate, None)):
532            yield t[0], t[2]
533
534    def predicate_objects(
535        self, subject: Optional[_SubjectType] = None
536    ) -> Generator[Tuple[_PredicateType, _ObjectType], None, None]:
537        """A generator of (predicate, object) tuples for the given subject"""
538        for t, c in self.triples((subject, None, None)):
539            yield t[1], t[2]
540
541
542class SPARQLUpdateStore(SPARQLStore):
543    """A store using SPARQL queries for reading and SPARQL Update for changes.
544
545    This can be context-aware, if so, any changes will be to the given named
546    graph only.
547
548    In favor of the SPARQL 1.1 motivated Dataset, we advise against using this
549    with ConjunctiveGraphs, as it reads and writes from and to the
550    "default graph". Exactly what this means depends on the endpoint and can
551    result in confusion.
552
553    For Graph objects, everything works as expected.
554
555    See the [`SPARQLStore`][rdflib.plugins.stores.sparqlstore.SPARQLStore] base class for more information.
556    """
557
558    where_pattern = re.compile(r"""(?P<where>WHERE\s*\{)""", re.IGNORECASE)
559
560    ##############################################################
561    # Regex for injecting GRAPH blocks into updates on a context #
562    ##############################################################
563
564    # Observations on the SPARQL grammar (http://www.w3.org/TR/2013/REC-sparql11-query-20130321/):
565    # 1. Only the terminals STRING_LITERAL1, STRING_LITERAL2,
566    #    STRING_LITERAL_LONG1, STRING_LITERAL_LONG2, and comments can contain
567    #    curly braces.
568    # 2. The non-terminals introduce curly braces in pairs only.
569    # 3. Unescaped " can occur only in strings and comments.
570    # 3. Unescaped ' can occur only in strings, comments, and IRIRefs.
571    # 4. \ always escapes the following character, especially \", \', and
572    #    \\ denote literal ", ', and \ respectively.
573    # 5. # always starts a comment outside of string and IRI
574    # 6. A comment ends at the next newline
575    # 7. IRIREFs need to be detected, as they may contain # without starting a comment
576    # 8. PrefixedNames do not contain a #
577    # As a consequence, it should be rather easy to detect strings and comments
578    # in order to avoid unbalanced curly braces.
579
580    # From the SPARQL grammar
581    STRING_LITERAL1 = "'([^'\\\\]|\\\\.)*'"
582    STRING_LITERAL2 = '"([^"\\\\]|\\\\.)*"'
583    STRING_LITERAL_LONG1 = "'''(('|'')?([^'\\\\]|\\\\.))*'''"
584    STRING_LITERAL_LONG2 = '"""(("|"")?([^"\\\\]|\\\\.))*"""'
585    String = "(%s)|(%s)|(%s)|(%s)" % (
586        STRING_LITERAL1,
587        STRING_LITERAL2,
588        STRING_LITERAL_LONG1,
589        STRING_LITERAL_LONG2,
590    )
591    IRIREF = '<([^<>"{}|^`\\]\\\\[\\x00-\\x20])*>'
592    COMMENT = "#[^\\x0D\\x0A]*([\\x0D\\x0A]|\\Z)"
593
594    # Simplified grammar to find { at beginning and } at end of blocks
595    BLOCK_START = "{"
596    BLOCK_END = "}"
597    ESCAPED = "\\\\."
598
599    # Match anything that doesn't start or end a block:
600    BlockContent = "(%s)|(%s)|(%s)|(%s)" % (String, IRIREF, COMMENT, ESCAPED)
601    BlockFinding = "(?P<block_start>%s)|(?P<block_end>%s)|(?P<block_content>%s)" % (
602        BLOCK_START,
603        BLOCK_END,
604        BlockContent,
605    )
606    BLOCK_FINDING_PATTERN = re.compile(BlockFinding)
607
608    # Note that BLOCK_FINDING_PATTERN.finditer() will not cover the whole
609    # string with matches. Everything that is not matched will have to be
610    # part of the modified query as is.
611
612    ##################################################################
613
614    def __init__(
615        self,
616        query_endpoint: Optional[str] = None,
617        update_endpoint: Optional[str] = None,
618        sparql11: bool = True,
619        context_aware: bool = True,
620        postAsEncoded: bool = True,  # noqa: N803
621        autocommit: bool = True,
622        dirty_reads: bool = False,
623        **kwds,
624    ):
625        """
626        Args:
627            autocommit: if set, the store will commit after every
628                writing operations. If False, we only make queries on the
629                server once commit is called.
630            dirty_reads if set, we do not commit before reading. So you
631                cannot read what you wrote before manually calling commit.
632        """
633
634        SPARQLStore.__init__(
635            self,
636            query_endpoint,
637            sparql11,
638            context_aware,
639            update_endpoint=update_endpoint,
640            **kwds,
641        )
642
643        self.postAsEncoded = postAsEncoded
644        self.autocommit = autocommit
645        self.dirty_reads = dirty_reads
646        self._edits: Optional[List[str]] = None
647        self._updates = 0
648
649    def query(self, *args: Any, **kwargs: Any) -> Result:
650        if not self.autocommit and not self.dirty_reads:
651            self.commit()
652        return SPARQLStore.query(self, *args, **kwargs)
653
654    # type error: Signature of "triples" incompatible with supertype "Store"
655    def triples(  # type: ignore[override]
656        self, *args: Any, **kwargs: Any
657    ) -> Iterator[Tuple[_TripleType, None]]:
658        if not self.autocommit and not self.dirty_reads:
659            self.commit()
660        return SPARQLStore.triples(self, *args, **kwargs)
661
662    # type error: Signature of "contexts" incompatible with supertype "Store"
663    def contexts(  # type: ignore[override]
664        self, *args: Any, **kwargs: Any
665    ) -> Generator[_ContextIdentifierType, None, None]:
666        if not self.autocommit and not self.dirty_reads:
667            self.commit()
668        return SPARQLStore.contexts(self, *args, **kwargs)
669
670    def __len__(self, *args: Any, **kwargs: Any) -> int:
671        if not self.autocommit and not self.dirty_reads:
672            self.commit()
673        return SPARQLStore.__len__(self, *args, **kwargs)
674
675    def open(
676        self, configuration: Union[str, Tuple[str, str]], create: bool = False
677    ) -> None:
678        """Sets the endpoint URLs for this `SPARQLStore`
679
680        Args:
681            configuration: either a tuple of (query_endpoint, update_endpoint),
682                or a string with the endpoint which is configured as query and update endpoint
683            create: if True an exception is thrown.
684        """
685
686        if create:
687            raise Exception("Cannot create a SPARQL Endpoint")
688
689        if isinstance(configuration, tuple):
690            self.query_endpoint = configuration[0]
691            if len(configuration) > 1:
692                self.update_endpoint = configuration[1]
693        else:
694            self.query_endpoint = configuration
695            self.update_endpoint = configuration
696
697    def _transaction(self) -> List[str]:
698        if self._edits is None:
699            self._edits = []
700        return self._edits
701
702    # Transactional interfaces
703    def commit(self) -> None:
704        """`add()`, `addN()`, and `remove()` are transactional to reduce overhead of many small edits.
705        Read and update() calls will automatically commit any outstanding edits.
706        This should behave as expected most of the time, except that alternating writes
707        and reads can degenerate to the original call-per-triple situation that originally existed.
708        """
709        if self._edits and len(self._edits) > 0:
710            self._update("\n;\n".join(self._edits))
711            self._edits = None
712
713    def rollback(self) -> None:
714        self._edits = None
715
716    def add(
717        self,
718        spo: _TripleType,
719        context: Optional[_ContextType] = None,
720        quoted: bool = False,
721    ) -> None:
722        """Add a triple to the store of triples."""
723
724        if not self.update_endpoint:
725            raise Exception("UpdateEndpoint is not set")
726
727        assert not quoted
728        (subject, predicate, obj) = spo
729
730        nts = self.node_to_sparql
731        triple = "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
732        if self._is_contextual(context):
733            if TYPE_CHECKING:
734                # _is_contextual will never return true if context is None
735                assert context is not None
736            q = "INSERT DATA { GRAPH %s { %s } }" % (nts(context.identifier), triple)
737        else:
738            q = "INSERT DATA { %s }" % triple
739        self._transaction().append(q)
740        if self.autocommit:
741            self.commit()
742
743    def addN(self, quads: Iterable[_QuadType]) -> None:  # noqa: N802
744        """Add a list of quads to the store."""
745        if not self.update_endpoint:
746            raise Exception("UpdateEndpoint is not set - call 'open'")
747
748        contexts = collections.defaultdict(list)
749        for subject, predicate, obj, context in quads:
750            contexts[context].append((subject, predicate, obj))
751        data: List[str] = []
752        nts = self.node_to_sparql
753        for context in contexts:
754            triples = [
755                "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
756                for subject, predicate, obj in contexts[context]
757            ]
758            data.append(
759                "INSERT DATA { GRAPH %s { %s } }\n"
760                % (nts(context.identifier), "\n".join(triples))
761            )
762        self._transaction().extend(data)
763        if self.autocommit:
764            self.commit()
765
766    # type error: Signature of "remove" incompatible with supertype "Store"
767    def remove(  # type: ignore[override]
768        self, spo: _TriplePatternType, context: Optional[_ContextType]
769    ) -> None:
770        """Remove a triple from the store"""
771        if not self.update_endpoint:
772            raise Exception("UpdateEndpoint is not set - call 'open'")
773
774        (subject, predicate, obj) = spo
775        if not subject:
776            subject = Variable("S")
777        if not predicate:
778            predicate = Variable("P")
779        if not obj:
780            obj = Variable("O")
781
782        nts = self.node_to_sparql
783        triple = "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
784        if self._is_contextual(context):
785            if TYPE_CHECKING:
786                # _is_contextual will never return true if context is None
787                assert context is not None
788            cid = nts(context.identifier)
789            q = "WITH %(graph)s DELETE { %(triple)s } WHERE { %(triple)s }" % {
790                "graph": cid,
791                "triple": triple,
792            }
793        else:
794            q = "DELETE { %s } WHERE { %s } " % (triple, triple)
795        self._transaction().append(q)
796        if self.autocommit:
797            self.commit()
798
799    def setTimeout(self, timeout) -> None:  # noqa: N802
800        self._timeout = int(timeout)
801
802    def _update(self, update):
803        self._updates += 1
804
805        SPARQLConnector.update(self, update)
806
807    # type error: Signature of "update" incompatible with supertype "SPARQLConnector"
808    # type error: Signature of "update" incompatible with supertype "Store"
809    def update(  # type: ignore[override]
810        self,
811        query: Union[Update, str],
812        initNs: Dict[str, Any] = {},  # noqa: N803
813        initBindings: Dict[str, Identifier] = {},  # noqa: N803
814        queryGraph: Optional[str] = None,  # noqa: N803
815        DEBUG: bool = False,  # noqa: N803
816    ):
817        """Perform a SPARQL Update Query against the endpoint, INSERT, LOAD, DELETE etc.
818
819        Setting initNs adds PREFIX declarations to the beginning of
820        the update. Setting initBindings adds inline VALUEs to the
821        beginning of every WHERE clause. By the SPARQL grammar, all
822        operations that support variables (namely INSERT and DELETE)
823        require a WHERE clause.
824        Important: initBindings fails if the update contains the
825        substring 'WHERE {' which does not denote a WHERE clause, e.g.
826        if it is part of a literal.
827
828        !!! info "Context-aware query rewriting"
829
830            - **When:**  If context-awareness is enabled and the graph is not the default graph of the store.
831            - **Why:** To ensure consistency with the [`Memory`][rdflib.plugins.stores.memory.Memory] store.
832                The graph must accept "local" SPARQL requests (requests with no GRAPH keyword)
833                as if it was the default graph.
834            - **What is done:** These "local" queries are rewritten by this store.
835                The content of each block of a SPARQL Update operation is wrapped in a GRAPH block
836                except if the block is empty.
837                This basically causes INSERT, INSERT DATA, DELETE, DELETE DATA and WHERE to operate
838                only on the context.
839            - **Example:** `"INSERT DATA { <urn:michel> <urn:likes> <urn:pizza> }"` is converted into
840                `"INSERT DATA { GRAPH <urn:graph> { <urn:michel> <urn:likes> <urn:pizza> } }"`.
841            - **Warning:** Queries are presumed to be "local" but this assumption is **not checked**.
842                For instance, if the query already contains GRAPH blocks, the latter will be wrapped in new GRAPH blocks.
843            - **Warning:** A simplified grammar is used that should tolerate
844                extensions of the SPARQL grammar. Still, the process may fail in
845                uncommon situations and produce invalid output.
846        """
847        if not self.update_endpoint:
848            raise Exception("Update endpoint is not set!")
849
850        self.debug = DEBUG
851        assert isinstance(query, str)
852        query = self._inject_prefixes(query, initNs)
853
854        if self._is_contextual(queryGraph):
855            if TYPE_CHECKING:
856                # _is_contextual will never return true if context is None
857                assert queryGraph is not None
858            query = self._insert_named_graph(query, queryGraph)
859
860        if initBindings:
861            # For INSERT and DELETE the WHERE clause is obligatory
862            # (http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rModify)
863            # Other query types do not allow variables and don't
864            # have a WHERE clause.  This also works for updates with
865            # more than one INSERT/DELETE.
866            v = list(initBindings)
867            values = "\nVALUES ( %s )\n{ ( %s ) }\n" % (
868                " ".join("?" + str(x) for x in v),
869                " ".join(self.node_to_sparql(initBindings[x]) for x in v),
870            )
871
872            query = self.where_pattern.sub("WHERE { " + values, query)
873
874        self._transaction().append(query)
875        if self.autocommit:
876            self.commit()
877
878    def _insert_named_graph(self, query: str, query_graph: str) -> str:
879        """Inserts GRAPH <query_graph> {} into blocks of SPARQL Update operations
880
881        For instance,  `INSERT DATA { <urn:michel> <urn:likes> <urn:pizza> }`
882        is converted into
883        `INSERT DATA { GRAPH <urn:graph> { <urn:michel> <urn:likes> <urn:pizza> } }`
884        """
885        if isinstance(query_graph, Node):
886            query_graph = self.node_to_sparql(query_graph)
887        else:
888            query_graph = "<%s>" % query_graph
889        graph_block_open = " GRAPH %s {" % query_graph
890        graph_block_close = "} "
891
892        # SPARQL Update supports the following operations:
893        # LOAD, CLEAR, DROP, ADD, MOVE, COPY, CREATE, INSERT DATA, DELETE DATA, DELETE/INSERT, DELETE WHERE
894        # LOAD, CLEAR, DROP, ADD, MOVE, COPY, CREATE do not make much sense in a context.
895        # INSERT DATA, DELETE DATA, and DELETE WHERE require the contents of their block to be wrapped in a GRAPH <?> { }.
896        # DELETE/INSERT supports the WITH keyword, which sets the graph to be
897        # used for all following DELETE/INSERT instruction including the
898        # non-optional WHERE block. Equivalently, a GRAPH block can be added to
899        # all blocks.
900        #
901        # Strategy employed here: Wrap the contents of every top-level block into a `GRAPH <?> { }`.
902
903        level = 0
904        modified_query = []
905        pos = 0
906        for match in self.BLOCK_FINDING_PATTERN.finditer(query):
907            if match.group("block_start") is not None:
908                level += 1
909                if level == 1:
910                    modified_query.append(query[pos : match.end()])
911                    modified_query.append(graph_block_open)
912                    pos = match.end()
913            elif match.group("block_end") is not None:
914                if level == 1:
915                    since_previous_pos = query[pos : match.start()]
916                    if modified_query[-1] is graph_block_open and (
917                        since_previous_pos == "" or since_previous_pos.isspace()
918                    ):
919                        # In this case, adding graph_block_start and
920                        # graph_block_end results in an empty GRAPH block. Some
921                        # endpoints (e.g. TDB) can not handle this. Therefore
922                        # remove the previously added block_start.
923                        modified_query.pop()
924                        modified_query.append(since_previous_pos)
925                    else:
926                        modified_query.append(since_previous_pos)
927                        modified_query.append(graph_block_close)
928                    pos = match.start()
929                level -= 1
930        modified_query.append(query[pos:])
931
932        return "".join(modified_query)
933
934    def add_graph(self, graph: Graph) -> None:
935        if not self.graph_aware:
936            Store.add_graph(self, graph)
937        elif graph.identifier != DATASET_DEFAULT_GRAPH_ID:
938            self.update("CREATE GRAPH %s" % self.node_to_sparql(graph.identifier))
939
940    def remove_graph(self, graph: Graph) -> None:
941        if not self.graph_aware:
942            Store.remove_graph(self, graph)
943        elif graph.identifier == DATASET_DEFAULT_GRAPH_ID:
944            self.update("DROP DEFAULT")
945        else:
946            self.update("DROP GRAPH %s" % self.node_to_sparql(graph.identifier))
947
948    def subjects(
949        self,
950        predicate: Optional[_PredicateType] = None,
951        object: Optional[_ObjectType] = None,
952    ) -> Generator[_SubjectType, None, None]:
953        """A generator of subjects with the given predicate and object"""
954        for t, c in self.triples((None, predicate, object)):
955            yield t[0]
956
957    def predicates(
958        self,
959        subject: Optional[_SubjectType] = None,
960        object: Optional[_ObjectType] = None,
961    ) -> Generator[_PredicateType, None, None]:
962        """A generator of predicates with the given subject and object"""
963        for t, c in self.triples((subject, None, object)):
964            yield t[1]
965
966    def objects(
967        self,
968        subject: Optional[_SubjectType] = None,
969        predicate: Optional[_PredicateType] = None,
970    ) -> Generator[_ObjectType, None, None]:
971        """A generator of objects with the given subject and predicate"""
972        for t, c in self.triples((subject, predicate, None)):
973            yield t[2]
974
975    def subject_predicates(
976        self, object: Optional[_ObjectType] = None
977    ) -> Generator[Tuple[_SubjectType, _PredicateType], None, None]:
978        """A generator of (subject, predicate) tuples for the given object"""
979        for t, c in self.triples((None, None, object)):
980            yield t[0], t[1]
981
982    def subject_objects(
983        self, predicate: Optional[_PredicateType] = None
984    ) -> Generator[Tuple[_SubjectType, _ObjectType], None, None]:
985        """A generator of (subject, object) tuples for the given predicate"""
986        for t, c in self.triples((None, predicate, None)):
987            yield t[0], t[2]
988
989    def predicate_objects(
990        self, subject: Optional[_SubjectType] = None
991    ) -> Generator[Tuple[_PredicateType, _ObjectType], None, None]:
992        """A generator of (predicate, object) tuples for the given subject"""
993        for t, c in self.triples((subject, None, None)):
994            yield t[1], t[2]
995
996
997__all__ = ["SPARQLUpdateStore", "SPARQLStore"]