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"]