Source code

Download source archive ↓

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