src/rdflib/plugins/sparql/sparql.py
1from __future__ import annotations
2
3import collections
4import datetime
5import itertools
6import typing as t
7from collections.abc import Mapping, MutableMapping
8from typing import (
9 TYPE_CHECKING,
10 Any,
11 Container,
12 Dict,
13 Generator,
14 Iterable,
15 List,
16 Optional,
17 Tuple,
18 TypeVar,
19 Union,
20)
21
22import rdflib.plugins.sparql
23from rdflib.graph import ConjunctiveGraph, Dataset, Graph
24from rdflib.namespace import NamespaceManager
25from rdflib.plugins.sparql.parserutils import CompValue
26from rdflib.term import BNode, Identifier, Literal, Node, URIRef, Variable
27
28if TYPE_CHECKING:
29 from rdflib.paths import Path
30
31
32_AnyT = TypeVar("_AnyT")
33
34
35class SPARQLError(Exception):
36 def __init__(self, msg: Optional[str] = None):
37 Exception.__init__(self, msg)
38
39
40class NotBoundError(SPARQLError):
41 def __init__(self, msg: Optional[str] = None):
42 SPARQLError.__init__(self, msg)
43
44
45class AlreadyBound(SPARQLError): # noqa: N818
46 """Raised when trying to bind a variable that is already bound!"""
47
48 def __init__(self):
49 SPARQLError.__init__(self)
50
51
52class SPARQLTypeError(SPARQLError):
53 def __init__(self, msg: Optional[str]):
54 SPARQLError.__init__(self, msg)
55
56
57class Bindings(MutableMapping):
58 """
59
60 A single level of a stack of variable-value bindings.
61 Each dict keeps a reference to the dict below it,
62 any failed lookup is propegated back
63
64 In python 3.3 this could be a collections.ChainMap
65 """
66
67 def __init__(self, outer: Optional[Bindings] = None, d=[]):
68 self._d: Dict[str, str] = dict(d)
69 self.outer = outer
70
71 def __getitem__(self, key: str) -> str:
72 if key in self._d:
73 return self._d[key]
74
75 if not self.outer:
76 raise KeyError()
77 return self.outer[key]
78
79 def __contains__(self, key: Any) -> bool:
80 try:
81 self[key]
82 return True
83 except KeyError:
84 return False
85
86 def __setitem__(self, key: str, value: Any) -> None:
87 self._d[key] = value
88
89 def __delitem__(self, key: str) -> None:
90 raise Exception("DelItem is not implemented!")
91
92 def __len__(self) -> int:
93 i = 0
94 d: Optional[Bindings] = self
95 while d is not None:
96 i += len(d._d)
97 d = d.outer
98 return i
99
100 def __iter__(self) -> Generator[str, None, None]:
101 d: Optional[Bindings] = self
102 while d is not None:
103 yield from d._d
104 d = d.outer
105
106 def __str__(self) -> str:
107 # type error: Generator has incompatible item type "Tuple[Any, str]"; expected "str"
108 return "Bindings({" + ", ".join((k, self[k]) for k in self) + "})" # type: ignore[misc]
109
110 def __repr__(self) -> str:
111 return str(self)
112
113
114class FrozenDict(Mapping):
115 """
116 An immutable hashable dict
117
118 Taken from http://stackoverflow.com/a/2704866/81121
119
120 """
121
122 def __init__(self, *args: Any, **kwargs: Any):
123 self._d: Dict[Identifier, Identifier] = dict(*args, **kwargs)
124 self._hash: Optional[int] = None
125
126 def __iter__(self):
127 return iter(self._d)
128
129 def __len__(self) -> int:
130 return len(self._d)
131
132 def __getitem__(self, key: Identifier) -> Identifier:
133 return self._d[key]
134
135 def __hash__(self) -> int:
136 # It would have been simpler and maybe more obvious to
137 # use hash(tuple(sorted(self._d.items()))) from this discussion
138 # so far, but this solution is O(n). I don't know what kind of
139 # n we are going to run into, but sometimes it's hard to resist the
140 # urge to optimize when it will gain improved algorithmic performance.
141 if self._hash is None:
142 self._hash = 0
143 for key, value in self.items():
144 self._hash ^= hash(key)
145 self._hash ^= hash(value)
146 return self._hash
147
148 def project(self, vars: Container[Variable]) -> FrozenDict:
149 return FrozenDict(x for x in self.items() if x[0] in vars)
150
151 def disjointDomain(self, other: t.Mapping[Identifier, Identifier]) -> bool:
152 return not bool(set(self).intersection(other))
153
154 def compatible(self, other: t.Mapping[Identifier, Identifier]) -> bool:
155 for k in self:
156 try:
157 if self[k] != other[k]:
158 return False
159 except KeyError:
160 pass
161
162 return True
163
164 def merge(self, other: t.Mapping[Identifier, Identifier]) -> FrozenDict:
165 res = FrozenDict(itertools.chain(self.items(), other.items()))
166
167 return res
168
169 def __str__(self) -> str:
170 return str(self._d)
171
172 def __repr__(self) -> str:
173 return repr(self._d)
174
175
176class FrozenBindings(FrozenDict):
177 def __init__(self, ctx: QueryContext, *args, **kwargs):
178 FrozenDict.__init__(self, *args, **kwargs)
179 self.ctx = ctx
180
181 def __getitem__(self, key: Union[Identifier, str]) -> Identifier:
182 if not isinstance(key, Node):
183 key = Variable(key)
184
185 if not isinstance(key, (BNode, Variable)):
186 return key
187
188 if key not in self._d:
189 # type error: Value of type "Optional[Dict[Variable, Identifier]]" is not indexable
190 # type error: Invalid index type "Union[BNode, Variable]" for "Optional[Dict[Variable, Identifier]]"; expected type "Variable"
191 return self.ctx.initBindings[key] # type: ignore[index]
192 else:
193 return self._d[key]
194
195 def project(self, vars: Container[Variable]) -> FrozenBindings:
196 return FrozenBindings(self.ctx, (x for x in self.items() if x[0] in vars))
197
198 def merge(self, other: t.Mapping[Identifier, Identifier]) -> FrozenBindings:
199 res = FrozenBindings(self.ctx, itertools.chain(self.items(), other.items()))
200 return res
201
202 @property
203 def now(self) -> datetime.datetime:
204 return self.ctx.now
205
206 @property
207 def bnodes(self) -> t.Mapping[Identifier, BNode]:
208 return self.ctx.bnodes
209
210 @property
211 def prologue(self) -> Optional[Prologue]:
212 return self.ctx.prologue
213
214 def forget(
215 self, before: QueryContext, _except: Optional[Container[Variable]] = None
216 ) -> FrozenBindings:
217 """
218 return a frozen dict only of bindings made in self
219 since before
220 """
221 if not _except:
222 _except = []
223
224 # bindings from initBindings are newer forgotten
225 return FrozenBindings(
226 self.ctx,
227 (
228 x
229 for x in self.items()
230 if (
231 x[0] in _except
232 # type error: Unsupported right operand type for in ("Optional[Dict[Variable, Identifier]]")
233 or x[0] in self.ctx.initBindings # type: ignore[operator]
234 or before[x[0]] is None
235 )
236 ),
237 )
238
239 def remember(self, these) -> FrozenBindings:
240 """
241 return a frozen dict only of bindings in these
242 """
243 return FrozenBindings(self.ctx, (x for x in self.items() if x[0] in these))
244
245
246class QueryContext:
247 """
248 Query context - passed along when evaluating the query
249 """
250
251 def __init__(
252 self,
253 graph: Optional[Graph] = None,
254 bindings: Optional[Union[Bindings, FrozenBindings, List[Any]]] = None,
255 initBindings: Optional[Mapping[str, Identifier]] = None,
256 datasetClause=None,
257 ):
258 self.initBindings = initBindings
259 self.bindings = Bindings(d=bindings or [])
260 if initBindings:
261 self.bindings.update(initBindings)
262
263 self.graph: Optional[Graph]
264 self._dataset: Optional[Union[Dataset, ConjunctiveGraph]]
265 if isinstance(graph, (Dataset, ConjunctiveGraph)):
266 if datasetClause:
267 self._dataset = Dataset()
268 self.graph = Graph()
269 for d in datasetClause:
270 if d.default:
271 from_graph = graph.get_context(d.default)
272 self.graph += from_graph
273 if not from_graph:
274 self.load(d.default, default=True)
275 elif d.named:
276 namedGraphs = Graph(
277 store=self.dataset.store, identifier=d.named
278 )
279 from_named_graphs = graph.get_context(d.named)
280 namedGraphs += from_named_graphs
281 if not from_named_graphs:
282 self.load(d.named, default=False)
283 else:
284 self._dataset = graph
285 if rdflib.plugins.sparql.SPARQL_DEFAULT_GRAPH_UNION:
286 self.graph = self.dataset
287 else:
288 self.graph = self.dataset.default_context
289 else:
290 self._dataset = None
291 self.graph = graph
292
293 self.prologue: Optional[Prologue] = None
294 self._now: Optional[datetime.datetime] = None
295
296 self.bnodes: t.MutableMapping[Identifier, BNode] = collections.defaultdict(
297 BNode
298 )
299
300 @property
301 def now(self) -> datetime.datetime:
302 if self._now is None:
303 self._now = datetime.datetime.now(datetime.timezone.utc)
304 return self._now
305
306 def clone(
307 self, bindings: Optional[Union[FrozenBindings, Bindings, List[Any]]] = None
308 ) -> QueryContext:
309 r = QueryContext(
310 self._dataset if self._dataset is not None else self.graph,
311 bindings or self.bindings,
312 initBindings=self.initBindings,
313 )
314 r.prologue = self.prologue
315 r.graph = self.graph
316 r.bnodes = self.bnodes
317 return r
318
319 @property
320 def dataset(self) -> ConjunctiveGraph:
321 """ "current dataset"""
322 if self._dataset is None:
323 raise Exception(
324 "You performed a query operation requiring "
325 + "a dataset (i.e. ConjunctiveGraph), but "
326 + "operating currently on a single graph."
327 )
328 return self._dataset
329
330 def load(
331 self,
332 source: URIRef,
333 default: bool = False,
334 into: Optional[Identifier] = None,
335 **kwargs: Any,
336 ) -> None:
337 """
338 Load data from the source into the query context's.
339
340 Args:
341 source: The source to load from.
342 default: If `True`, triples from the source will be added
343 to the default graph, otherwise it will be loaded into a
344 graph with `source` URI as its name.
345 into: The name of the graph to load the data into. If
346 `None`, the source URI will be used as as the name of the
347 graph.
348 **kwargs: Keyword arguments to pass to
349 [`parse`][rdflib.graph.Graph.parse].
350 """
351
352 def _load(graph, source):
353 try:
354 return graph.parse(source, format="turtle", **kwargs)
355 except Exception:
356 pass
357 try:
358 return graph.parse(source, format="xml", **kwargs)
359 except Exception:
360 pass
361 try:
362 return graph.parse(source, format="n3", **kwargs)
363 except Exception:
364 pass
365 try:
366 return graph.parse(source, format="nt", **kwargs)
367 except Exception:
368 raise Exception(
369 "Could not load %s as either RDF/XML, N3 or NTriples" % source
370 )
371
372 if not rdflib.plugins.sparql.SPARQL_LOAD_GRAPHS:
373 # we are not loading - if we already know the graph
374 # being "loaded", just add it to the default-graph
375 if default:
376 # Unsupported left operand type for + ("None")
377 self.graph += self.dataset.get_context(source) # type: ignore[operator]
378 else:
379 if default:
380 _load(self.graph, source)
381 else:
382 if into is None:
383 into = source
384 _load(self.dataset.get_context(into), source)
385
386 def __getitem__(self, key: Union[str, Path]) -> Optional[Union[str, Path]]:
387 # in SPARQL BNodes are just labels
388 if not isinstance(key, (BNode, Variable)):
389 return key
390 try:
391 return self.bindings[key]
392 except KeyError:
393 return None
394
395 def get(self, key: str, default: Optional[Any] = None) -> Any:
396 try:
397 return self[key]
398 except KeyError:
399 return default
400
401 def solution(self, vars: Optional[Iterable[Variable]] = None) -> FrozenBindings:
402 """
403 Return a static copy of the current variable bindings as dict
404 """
405 if vars:
406 return FrozenBindings(
407 self, ((k, v) for k, v in self.bindings.items() if k in vars)
408 )
409 else:
410 return FrozenBindings(self, self.bindings.items())
411
412 def __setitem__(self, key: str, value: str) -> None:
413 if key in self.bindings and self.bindings[key] != value:
414 raise AlreadyBound()
415
416 self.bindings[key] = value
417
418 def pushGraph(self, graph: Optional[Graph]) -> QueryContext:
419 r = self.clone()
420 r.graph = graph
421 return r
422
423 def push(self) -> QueryContext:
424 r = self.clone(Bindings(self.bindings))
425 return r
426
427 def clean(self) -> QueryContext:
428 return self.clone([])
429
430 def thaw(self, frozenbindings: FrozenBindings) -> QueryContext:
431 """
432 Create a new read/write query context from the given solution
433 """
434 c = self.clone(frozenbindings)
435
436 return c
437
438
439class Prologue:
440 """
441 A class for holding prefixing bindings and base URI information
442 """
443
444 def __init__(self) -> None:
445 self.base: Optional[str] = None
446 self.namespace_manager = NamespaceManager(Graph()) # ns man needs a store
447
448 def resolvePName(self, prefix: Optional[str], localname: Optional[str]) -> URIRef:
449 ns = self.namespace_manager.store.namespace(prefix or "")
450 if ns is None:
451 raise Exception("Unknown namespace prefix : %s" % prefix)
452 return URIRef(ns + (localname or ""))
453
454 def bind(self, prefix: Optional[str], uri: Any) -> None:
455 self.namespace_manager.bind(prefix, uri, replace=True)
456
457 def absolutize(
458 self, iri: Optional[Union[CompValue, str]]
459 ) -> Optional[Union[CompValue, str]]:
460 """
461 Apply BASE / PREFIXes to URIs
462 (and to datatypes in Literals)
463
464 TODO: Move resolving URIs to pre-processing
465 """
466
467 if isinstance(iri, CompValue):
468 if iri.name == "pname":
469 return self.resolvePName(iri.prefix, iri.localname)
470 if iri.name == "literal":
471 # type error: Argument "datatype" to "Literal" has incompatible type "Union[CompValue, Identifier, None]"; expected "Optional[str]"
472 return Literal(
473 iri.string, lang=iri.lang, datatype=self.absolutize(iri.datatype) # type: ignore[arg-type]
474 )
475 elif isinstance(iri, URIRef) and not ":" in iri: # noqa: E713
476 return URIRef(iri, base=self.base)
477
478 return iri
479
480
481class Query:
482 """
483 A parsed and translated query
484 """
485
486 def __init__(self, prologue: Prologue, algebra: CompValue):
487 self.prologue = prologue
488 self.algebra = algebra
489 self._original_args: Tuple[str, Mapping[str, str], Optional[str]]
490
491
492class Update:
493 """
494 A parsed and translated update
495 """
496
497 def __init__(self, prologue: Prologue, algebra: List[CompValue]):
498 self.prologue = prologue
499 self.algebra = algebra
500 self._original_args: Tuple[str, Mapping[str, str], Optional[str]]