SPARQL Endpoint interface, inspired by SPARQLWrapper
- A typed result per query form, and a typed error per SPARQL HTTP status
- t-string queries, checked against the SPARQL 1.1 grammar
httpxonly: one connection pool per client,asynciosupport, no RDF parsing
# pip
pip install rqw
# pipx
pipx install rqw
# mise
mise use -g github:eggplants/rqw
# docker
docker pull ghcr.io/eggplants/rqw$ rqw -Q 'SELECT ?s WHERE { ?s a <http://dbpedia.org/ontology/Fish> } LIMIT 3' --table
s
--------------------------------------
http://dbpedia.org/resource/Actinopoda
http://dbpedia.org/resource/Alfonsino
http://dbpedia.org/resource/Amberjack
$ rqw -e https://query.wikidata.org/sparql -f query.rq -F csv
$ echo 'ASK { ?s ?p ?o }' | rqw -f -
{
"head": {},
"boolean": true
}Use rqw --help for more information.
# sync
from rqw import SelectResult, SparqlClient
with SparqlClient("https://dbpedia.org/sparql") as sparql:
match sparql.execute("SELECT ?s ?p WHERE { ?s ?p ?o } LIMIT 5"):
case SelectResult() as rows:
for row in rows:
print(row["s"], row["p"])
# async
from rqw import AsyncSparqlClient
async def main() -> None:
async with AsyncSparqlClient("https://dbpedia.org/sparql") as sparql:
a, b = await asyncio.gather(
sparql.execute("SELECT * WHERE { ?s ?p ?o } LIMIT 10"),
sparql.execute("ASK { ?s ?p ?o }"),
)
asyncio.run(main())execute() is the only entry point. It reads the query form off the query and
returns the matching member of QueryResult:
| query form | result | |
|---|---|---|
SELECT |
SelectResult |
a sequence of rows |
ASK |
AskResult |
.value, and truthy on its own |
CONSTRUCT, DESCRIBE |
GraphResult |
the serialized graph, .text or .data |
INSERT, DELETE, DROP, ... |
UpdateResult |
.status, POSTed to the update endpoint |
expect names the form the query must take. The return type follows, and any
other form is refused before the request goes out:
rows = sparql.execute(query, expect=QueryForm.SELECT) # -> SelectResult
answer = sparql.execute(query, expect=QueryForm.ASK) # -> AskResult
sparql.execute("ASK { ?s ?p ?o }", expect=QueryForm.SELECT)
# QueryFormError: expected a SELECT query, got ASKCONSTRUCT and DESCRIBE are the only forms that leave the serialization open;
the rest are read out of the SPARQL JSON results format. raw=True skips
parsing and hands back a RawResult in whatever format you ask for:
sparql.execute("DESCRIBE <http://dbpedia.org/resource/Tuna>", result_format=GraphFormat.NTRIPLES)
csv = sparql.execute(query, result_format=SolutionFormat.CSV, raw=True)
csv.text # 's,n\r\n...'Asking for a format a form cannot answer in is a QueryFormError, raised before
the request goes out.
from rqw import Literal, Uri
match row["name"]:
case Literal(value=value, language="en"):
...
case Uri(value=uri):
...
row["count"].as_python() # 42, from an xsd:integer literalt-strings support
from rqw import Uri
subject, name = Uri("http://example.org/a"), 'O"Brien'
sparql.execute(t"SELECT ?s WHERE {{ {subject} <http://e/name> {name} }}")
# sent as: SELECT ?s WHERE { <http://example.org/a> <http://e/name> "O\"Brien" }| Python | SPARQL |
|---|---|
Uri, BlankNode, Literal, QuotedTriple |
the term itself |
str |
a quoted literal, "..." |
bool |
true / false |
int, float, Decimal |
a numeric literal |
date, time, datetime |
"..."^^xsd:... |
| a list or tuple | its items, space separated -- what VALUES wants |
a nested t"..." |
spliced in, values and all |
A str becomes a literal, never an IRI. Ask for another reading with a format
spec: {value:iri}, {value:var}.
After rendering, the whole query is tokenized and every spliced value is checked to still line up with a token boundary, so a value that tried to break out of a literal is refused rather than sent:
evil = '" } INSERT DATA { <a> <b> "pwned'
sparql.execute(t"SELECT ?s WHERE {{ ?s ?p {evil} }}")
# one literal, no second operation:
# SELECT ?s WHERE { ?s ?p "\" } INSERT DATA { <a> <b> \"pwned" }
sparql.execute(t'SELECT ?s WHERE {{ ?s ?p "{evil}" }}')
# QuerySyntaxError: an interpolated value cannot appear inside a tokenrqw.parse gives the same Query on its own, which execute accepts directly
when you send one query many times.
SparqlClient(
"https://example.org/sparql",
update_endpoint="https://example.org/update",
default_graph=["http://example.org/g1"],
method=HttpMethod.POST, # default: GET while the URL is short enough
encoding=RequestEncoding.DIRECT, # application/sparql-query, skips form encoding
params={"timeout": "5000"}, # endpoint-specific knobs
headers={"X-Trace": "1"},
auth=("user", "password"),
timeout=30.0,
)Passing client=httpx.Client(...) swaps in your own transport; closing it then
stays your job.
from rqw import BadQueryError
try:
sparql.execute("SELECT ?s WHERE {")
except BadQueryError as error:
print(error.status, error.body) # 400, the endpoint's own parser messageBadQueryError, UnauthorizedError, ForbiddenError, EndpointNotFoundError,
UriTooLongError, UnsupportedMediaTypeError and EndpointError derive from
SparqlHttpError; everything rqw raises derives from RqwError.