src/rdflib/query.py
1from __future__ import annotations
2
3import itertools
4import types
5import warnings
6from io import BytesIO
7from typing import (
8 IO,
9 TYPE_CHECKING,
10 Any,
11 BinaryIO,
12 Dict,
13 Iterator,
14 List,
15 Mapping,
16 MutableSequence,
17 Optional,
18 Tuple,
19 Union,
20 cast,
21 overload,
22)
23from urllib.parse import urlparse
24from urllib.request import url2pathname
25
26__all__ = [
27 "Processor",
28 "UpdateProcessor",
29 "Result",
30 "ResultRow",
31 "ResultParser",
32 "ResultSerializer",
33 "ResultException",
34 "EncodeOnlyUnicode",
35]
36
37import rdflib.term
38
39if TYPE_CHECKING:
40 from rdflib.graph import Graph, _TripleType
41 from rdflib.plugins.sparql.sparql import Query, Update
42 from rdflib.term import Identifier, Variable
43
44
45class Processor:
46 """
47 Query plugin interface.
48
49 This module is useful for those wanting to write a query processor
50 that can plugin to rdf. If you are wanting to execute a query you
51 likely want to do so through the Graph class query method.
52 """
53
54 def __init__(self, graph: Graph):
55 pass
56
57 # type error: Missing return statement
58 def query( # type: ignore[empty-body]
59 self,
60 strOrQuery: Union[str, Query], # noqa: N803
61 initBindings: Mapping[str, Identifier] = {}, # noqa: N803
62 initNs: Mapping[str, Any] = {}, # noqa: N803
63 DEBUG: bool = False, # noqa: N803
64 ) -> Mapping[str, Any]:
65 pass
66
67
68class UpdateProcessor:
69 """Update plugin interface.
70
71 This module is useful for those wanting to write an update
72 processor that can plugin to rdflib. If you are wanting to execute
73 an update statement you likely want to do so through the Graph
74 class update method.
75
76 !!! example "New in version 4.0"
77 """
78
79 def __init__(self, graph: Graph):
80 pass
81
82 def update(
83 self,
84 strOrQuery: Union[str, Update], # noqa: N803
85 initBindings: Mapping[str, Identifier] = {}, # noqa: N803
86 initNs: Mapping[str, Any] = {}, # noqa: N803
87 ) -> None:
88 pass
89
90
91class ResultException(Exception): # noqa: N818
92 pass
93
94
95class EncodeOnlyUnicode:
96 """This is a crappy work-around for http://bugs.python.org/issue11649"""
97
98 def __init__(self, stream: BinaryIO):
99 self.__stream = stream
100
101 def write(self, arg):
102 if isinstance(arg, str):
103 self.__stream.write(arg.encode("utf-8"))
104 else:
105 self.__stream.write(arg)
106
107 def __getattr__(self, name: str) -> Any:
108 return getattr(self.__stream, name)
109
110
111class ResultRow(Tuple[rdflib.term.Identifier, ...]):
112 """A single result row allows accessing bindings as attributes or with []
113
114 ```python
115 >>> from rdflib import URIRef, Variable
116 >>> rr=ResultRow({ Variable('a'): URIRef('urn:cake') }, [Variable('a')])
117
118 >>> rr[0]
119 rdflib.term.URIRef('urn:cake')
120 >>> rr[1]
121 Traceback (most recent call last):
122 ...
123 IndexError: tuple index out of range
124
125 >>> rr.a
126 rdflib.term.URIRef('urn:cake')
127 >>> rr.b
128 Traceback (most recent call last):
129 ...
130 AttributeError: b
131
132 >>> rr['a']
133 rdflib.term.URIRef('urn:cake')
134 >>> rr['b']
135 Traceback (most recent call last):
136 ...
137 KeyError: 'b'
138
139 >>> rr[Variable('a')]
140 rdflib.term.URIRef('urn:cake')
141
142 ```
143
144 !!! example "New in version 4.0"
145 """
146
147 labels: Mapping[str, int]
148
149 def __new__(cls, values: Mapping[Variable, Identifier], labels: List[Variable]):
150 # type error: Value of type variable "Self" of "__new__" of "tuple" cannot be "ResultRow" [type-var]
151 # type error: Generator has incompatible item type "Optional[Identifier]"; expected "_T_co" [misc]
152 instance = super(ResultRow, cls).__new__(cls, (values.get(v) for v in labels)) # type: ignore[type-var, misc, unused-ignore]
153 instance.labels = dict((str(x[1]), x[0]) for x in enumerate(labels))
154 return instance
155
156 def __getattr__(self, name: str) -> Identifier:
157 if name not in self.labels:
158 raise AttributeError(name)
159 return tuple.__getitem__(self, self.labels[name])
160
161 # type error: Signature of "__getitem__" incompatible with supertype "tuple"
162 # type error: Signature of "__getitem__" incompatible with supertype "Sequence"
163 def __getitem__(self, name: Union[str, int, Any]) -> Identifier: # type: ignore[override]
164 try:
165 # type error: Invalid index type "Union[str, int, Any]" for "tuple"; expected type "int"
166 return tuple.__getitem__(self, name) # type: ignore[index]
167 except TypeError:
168 if name in self.labels:
169 # type error: Invalid index type "Union[str, int, slice, Any]" for "Mapping[str, int]"; expected type "str"
170 return tuple.__getitem__(self, self.labels[name]) # type: ignore[index]
171 if str(name) in self.labels: # passing in variable object
172 return tuple.__getitem__(self, self.labels[str(name)])
173 raise KeyError(name)
174
175 @overload
176 def get(self, name: str, default: Identifier) -> Identifier: ...
177
178 @overload
179 def get(
180 self, name: str, default: Optional[Identifier] = ...
181 ) -> Optional[Identifier]: ...
182
183 def get(
184 self, name: str, default: Optional[Identifier] = None
185 ) -> Optional[Identifier]:
186 try:
187 return self[name]
188 except KeyError:
189 return default
190
191 def asdict(self) -> Dict[str, Identifier]:
192 return dict((v, self[v]) for v in self.labels if self[v] is not None)
193
194
195class Result:
196 """
197 A common class for representing query result.
198
199 There is a bit of magic here that makes this appear like different
200 Python objects, depending on the type of result.
201
202 If the type is "SELECT", iterating will yield lists of ResultRow objects
203
204 If the type is "ASK", iterating will yield a single bool (or
205 bool(result) will return the same bool)
206
207 If the type is "CONSTRUCT" or "DESCRIBE" iterating will yield the
208 triples.
209
210 `len(result)` also works.
211 """
212
213 def __init__(self, type_: str):
214 if type_ not in ("CONSTRUCT", "DESCRIBE", "SELECT", "ASK"):
215 raise ResultException("Unknown Result type: %s" % type_)
216
217 self.type = type_
218 #: variables contained in the result.
219 self.vars: Optional[List[Variable]] = None
220 """a list of variables contained in the result"""
221 self._bindings: MutableSequence[Mapping[Variable, Identifier]] = None # type: ignore[assignment]
222 self._genbindings: Optional[Iterator[Mapping[Variable, Identifier]]] = None
223 self.askAnswer: Optional[bool] = None
224 self.graph: Optional[Graph] = None
225
226 @property
227 def bindings(self) -> MutableSequence[Mapping[Variable, Identifier]]:
228 """
229 a list of variable bindings as dicts
230 """
231 if self._genbindings:
232 self._bindings += list(self._genbindings)
233 self._genbindings = None
234
235 return self._bindings
236
237 @bindings.setter
238 def bindings(
239 self,
240 b: Union[
241 MutableSequence[Mapping[Variable, Identifier]],
242 Iterator[Mapping[Variable, Identifier]],
243 ],
244 ) -> None:
245 if isinstance(b, (types.GeneratorType, itertools.islice)):
246 self._genbindings = b
247 self._bindings = []
248 else:
249 # type error: Incompatible types in assignment (expression has type "Union[MutableSequence[Mapping[Variable, Identifier]], Iterator[Mapping[Variable, Identifier]]]", variable has type "MutableSequence[Mapping[Variable, Identifier]]")
250 self._bindings = b # type: ignore[assignment]
251
252 @staticmethod
253 def parse(
254 source: Optional[IO] = None,
255 format: Optional[str] = None,
256 content_type: Optional[str] = None,
257 **kwargs: Any,
258 ) -> Result:
259 """Parse a query result from a source."""
260 from rdflib import plugin
261
262 if format:
263 plugin_key = format
264 elif content_type:
265 plugin_key = content_type.split(";", 1)[0]
266 else:
267 plugin_key = "xml"
268
269 parser = plugin.get(plugin_key, ResultParser)()
270
271 # type error: Argument 1 to "parse" of "ResultParser" has incompatible type "Optional[IO[Any]]"; expected "IO[Any]"
272 return parser.parse(
273 source, content_type=content_type, **kwargs # type:ignore[arg-type]
274 )
275
276 def serialize(
277 self,
278 destination: Optional[Union[str, IO]] = None,
279 encoding: str = "utf-8",
280 format: str = "xml",
281 **args: Any,
282 ) -> Optional[bytes]:
283 """
284 Serialize the query result.
285
286
287 Args:
288 destination: Path of file output or BufferedIOBase object
289 to write the output to. If `None` this function
290 will return the output as `bytes`
291 encoding: Encoding of output.
292 format: The format used for serialization.
293 See [sparql.results module][rdflib.plugins.sparql.results]
294 for all builtin SPARQL result serialization.
295 Further serializer can be loaded [as plugin][rdflib.plugin].
296 Some example formats are
297 [csv][rdflib.plugins.sparql.results.csvresults.CSVResultSerializer],
298 [json][rdflib.plugins.sparql.results.jsonresults.JSONResultSerializer],
299 [txt][rdflib.plugins.sparql.results.txtresults.TXTResultSerializer]
300 or
301 [xml][rdflib.plugins.sparql.results.xmlresults.XMLResultSerializer]
302
303 Returns:
304 Serialized result, when destination is not given.
305 """
306 if self.type in ("CONSTRUCT", "DESCRIBE"):
307 # type error: Item "None" of "Optional[Graph]" has no attribute "serialize"
308 # type error: Incompatible return value type (got "Union[bytes, str, Graph, Any]", expected "Optional[bytes]")
309 return self.graph.serialize( # type: ignore[union-attr,return-value]
310 destination, encoding=encoding, format=format, **args
311 )
312
313 """stolen wholesale from graph.serialize"""
314 from rdflib import plugin
315
316 serializer = plugin.get(format, ResultSerializer)(self)
317 if destination is None:
318 streamb: BytesIO = BytesIO()
319 stream2 = EncodeOnlyUnicode(streamb) # TODO: Remove the need for this
320 # TODO: All QueryResult serializers should write to a Bytes Stream.
321 # type error: Argument 1 to "serialize" of "ResultSerializer" has incompatible type "EncodeOnlyUnicode"; expected "IO[Any]"
322 serializer.serialize(stream2, encoding=encoding, **args) # type: ignore[arg-type]
323 return streamb.getvalue()
324 if hasattr(destination, "write"):
325 stream = cast(IO[bytes], destination)
326 serializer.serialize(stream, encoding=encoding, **args)
327 else:
328 location = cast(str, destination)
329 scheme, netloc, path, params, query, fragment = urlparse(location)
330 if scheme == "file":
331 if netloc != "":
332 raise ValueError(
333 f"the file URI {location!r} has an authority component which is not supported"
334 )
335 os_path = url2pathname(path)
336 else:
337 os_path = location
338 with open(os_path, "wb") as stream:
339 serializer.serialize(stream, encoding=encoding, **args)
340 return None
341
342 def __len__(self) -> int:
343 if self.type == "ASK":
344 return 1
345 elif self.type == "SELECT":
346 return len(self.bindings)
347 else:
348 # type error: Argument 1 to "len" has incompatible type "Optional[Graph]"; expected "Sized"
349 return len(self.graph) # type: ignore[arg-type]
350
351 def __bool__(self) -> bool:
352 if self.type == "ASK":
353 # type error: Incompatible return value type (got "Optional[bool]", expected "bool")
354 return self.askAnswer # type: ignore[return-value]
355 else:
356 return len(self) > 0
357
358 def __iter__(
359 self,
360 ) -> Iterator[Union[_TripleType, bool, ResultRow]]:
361 if self.type in ("CONSTRUCT", "DESCRIBE"):
362 # type error: Item "None" of "Optional[Graph]" has no attribute "__iter__" (not iterable)
363 for t in self.graph: # type: ignore[union-attr]
364 yield t
365 elif self.type == "ASK":
366 # type error: Incompatible types in "yield" (actual type "Optional[bool]", expected type "Union[Tuple[Identifier, Identifier, Identifier], bool, ResultRow]") [misc]
367 yield self.askAnswer # type: ignore[misc]
368 elif self.type == "SELECT":
369 # this iterates over ResultRows of variable bindings
370
371 if self._genbindings:
372 for b in self._genbindings:
373 if b: # don't add a result row in case of empty binding {}
374 self._bindings.append(b)
375 # type error: Argument 2 to "ResultRow" has incompatible type "Optional[List[Variable]]"; expected "List[Variable]"
376 yield ResultRow(b, self.vars) # type: ignore[arg-type]
377 self._genbindings = None
378 else:
379 for b in self._bindings:
380 if b: # don't add a result row in case of empty binding {}
381 # type error: Argument 2 to "ResultRow" has incompatible type "Optional[List[Variable]]"; expected "List[Variable]"
382 yield ResultRow(b, self.vars) # type: ignore[arg-type]
383
384 def __getattr__(self, name: str) -> Any:
385 if self.type in ("CONSTRUCT", "DESCRIBE") and self.graph is not None:
386 # type error: "Graph" has no attribute "__getattr__"
387 return self.graph.__getattr__(self, name) # type: ignore[attr-defined]
388 elif self.type == "SELECT" and name == "result":
389 warnings.warn(
390 "accessing the 'result' attribute is deprecated."
391 " Iterate over the object instead.",
392 DeprecationWarning,
393 stacklevel=2,
394 )
395 # copied from __iter__, above
396 # type error: Item "None" of "Optional[List[Variable]]" has no attribute "__iter__" (not iterable)
397 return [(tuple(b[v] for v in self.vars)) for b in self.bindings] # type: ignore[union-attr]
398 else:
399 raise AttributeError("'%s' object has no attribute '%s'" % (self, name))
400
401 def __eq__(self, other: Any) -> bool:
402 try:
403 if self.type != other.type:
404 return False
405 if self.type == "ASK":
406 return self.askAnswer == other.askAnswer
407 elif self.type == "SELECT":
408 return self.vars == other.vars and self.bindings == other.bindings
409 else:
410 return self.graph == other.graph
411 except Exception:
412 return False
413
414
415class ResultParser:
416 def __init__(self):
417 pass
418
419 # type error: Missing return statement
420 def parse(self, source: IO, **kwargs: Any) -> Result: # type: ignore[empty-body]
421 """return a Result object"""
422 pass # abstract
423
424
425class ResultSerializer:
426 def __init__(self, result: Result):
427 self.result = result
428
429 def serialize(self, stream: IO, encoding: str = "utf-8", **kwargs: Any) -> None:
430 """return a string properly serialized"""
431 pass # abstract