Source code

Download source archive ↓

src/rdflib/plugins/stores/sparqlconnector.py

1from __future__ import annotations
2
3import base64
4import copy
5import logging
6from io import BytesIO
7from typing import TYPE_CHECKING, Optional, Tuple
8from urllib.error import HTTPError
9from urllib.parse import urlencode
10from urllib.request import Request, urlopen
11
12from rdflib.plugin import plugins
13from rdflib.query import Result, ResultParser
14from rdflib.term import BNode
15from rdflib.util import FORMAT_MIMETYPE_MAP, RESPONSE_TABLE_FORMAT_MIMETYPE_MAP
16
17log = logging.getLogger(__name__)
18
19if TYPE_CHECKING:
20    import typing_extensions as te
21
22
23class SPARQLConnectorException(Exception):  # noqa: N818
24    pass
25
26
27class SPARQLConnector:
28    """
29    this class deals with nitty gritty details of talking to a SPARQL server
30    """
31
32    def __init__(
33        self,
34        query_endpoint: Optional[str] = None,
35        update_endpoint: Optional[str] = None,
36        returnFormat: Optional[str] = "xml",  # noqa: N803
37        method: te.Literal["GET", "POST", "POST_FORM"] = "GET",
38        auth: Optional[Tuple[str, str]] = None,
39        **kwargs,
40    ):
41        """
42        auth, if present, must be a tuple of (username, password) used for Basic Authentication
43
44        Any additional keyword arguments will be passed to to the request, and can be used to setup timeouts etc.
45        """
46        self._method: str
47        self.returnFormat = returnFormat
48        self.query_endpoint = query_endpoint
49        self.update_endpoint = update_endpoint
50        self.kwargs = kwargs
51        self.method = method
52        if auth is not None:
53            if type(auth) is not tuple:
54                raise SPARQLConnectorException("auth must be a tuple")
55            if len(auth) != 2:
56                raise SPARQLConnectorException("auth must be a tuple (user, password)")
57            base64string = base64.b64encode(bytes("%s:%s" % auth, "ascii"))
58            self.kwargs.setdefault("headers", {})
59            self.kwargs["headers"].update(
60                {"Authorization": "Basic %s" % base64string.decode("utf-8")}
61            )
62
63    @property
64    def method(self) -> str:
65        return self._method
66
67    @method.setter
68    def method(self, method: str) -> None:
69        if method not in ("GET", "POST", "POST_FORM"):
70            raise SPARQLConnectorException(
71                'Method must be "GET", "POST", or "POST_FORM"'
72            )
73
74        self._method = method
75
76    def query(
77        self,
78        query: str,
79        default_graph: Optional[str] = None,
80        named_graph: Optional[str] = None,
81    ) -> Result:
82        if not self.query_endpoint:
83            raise SPARQLConnectorException("Query endpoint not set!")
84
85        params = {}
86        # this test ensures we don't have a useless (BNode) default graph URI, which calls to Graph().query() will add
87        if default_graph is not None and type(default_graph) is not BNode:
88            params["default-graph-uri"] = default_graph
89
90        headers = {"Accept": self.response_mime_types()}
91
92        args = copy.deepcopy(self.kwargs)
93
94        # merge params/headers dicts
95        args.setdefault("params", {})
96
97        args.setdefault("headers", {})
98        args["headers"].update(headers)
99
100        if self.method == "GET":
101            params["query"] = query
102            args["params"].update(params)
103            qsa = "?" + urlencode(args["params"])
104            try:
105                res = urlopen(
106                    Request(self.query_endpoint + qsa, headers=args["headers"])
107                )
108            except Exception as e:  # noqa: F841
109                raise ValueError(
110                    "You did something wrong formulating either the URI or your SPARQL query"
111                )
112        elif self.method == "POST":
113            args["headers"].update({"Content-Type": "application/sparql-query"})
114            args["params"].update(params)
115            qsa = "?" + urlencode(args["params"])
116            try:
117                res = urlopen(
118                    Request(
119                        self.query_endpoint + qsa,
120                        data=query.encode(),
121                        headers=args["headers"],
122                    )
123                )
124            except HTTPError as e:
125                # type error: Incompatible return value type (got "Tuple[int, str, None]", expected "Result")
126                return e.code, str(e), None  # type: ignore[return-value]
127        elif self.method == "POST_FORM":
128            params["query"] = query
129            args["params"].update(params)
130            try:
131                res = urlopen(
132                    Request(
133                        self.query_endpoint,
134                        data=urlencode(args["params"]).encode(),
135                        headers=args["headers"],
136                    )
137                )
138            except HTTPError as e:
139                # type error: Incompatible return value type (got "Tuple[int, str, None]", expected "Result")
140                return e.code, str(e), None  # type: ignore[return-value]
141        else:
142            raise SPARQLConnectorException("Unknown method %s" % self.method)
143        return Result.parse(
144            BytesIO(res.read()), content_type=res.headers["Content-Type"].split(";")[0]
145        )
146
147    def update(
148        self,
149        query: str,
150        default_graph: Optional[str] = None,
151        named_graph: Optional[str] = None,
152    ) -> None:
153        if not self.update_endpoint:
154            raise SPARQLConnectorException("Query endpoint not set!")
155
156        params = {}
157
158        if default_graph is not None:
159            params["using-graph-uri"] = default_graph
160
161        if named_graph is not None:
162            params["using-named-graph-uri"] = named_graph
163
164        headers = {
165            "Accept": self.response_mime_types(),
166            "Content-Type": "application/sparql-update; charset=UTF-8",
167        }
168
169        args = copy.deepcopy(self.kwargs)  # other QSAs
170
171        args.setdefault("params", {})
172        args["params"].update(params)
173        args.setdefault("headers", {})
174        args["headers"].update(headers)
175
176        qsa = "?" + urlencode(args["params"])
177        res = urlopen(  # noqa: F841
178            Request(
179                self.update_endpoint + qsa, data=query.encode(), headers=args["headers"]
180            )
181        )
182
183    def response_mime_types(self) -> str:
184        """Construct a HTTP-Header Accept field to reflect the supported mime types.
185
186        If the return_format parameter is set, the mime types are restricted to these accordingly.
187        """
188        sparql_format_mimetype_map = {
189            k: FORMAT_MIMETYPE_MAP.get(k, [])
190            + RESPONSE_TABLE_FORMAT_MIMETYPE_MAP.get(k, [])
191            for k in list(FORMAT_MIMETYPE_MAP.keys())
192            + list(RESPONSE_TABLE_FORMAT_MIMETYPE_MAP.keys())
193        }
194
195        supported_formats = set()
196        for plugin in plugins(name=self.returnFormat, kind=ResultParser):
197            if "/" not in plugin.name:
198                supported_formats.update(
199                    sparql_format_mimetype_map.get(plugin.name, [])
200                )
201            else:
202                supported_formats.add(plugin.name)
203        return ", ".join(supported_formats)
204
205
206__all__ = ["SPARQLConnector", "SPARQLConnectorException"]