rqw
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
Install
# pip
pip install rqw
# pipx
pipx install rqw
# mise
mise use -g github:eggplants/rqw
# docker
docker pull ghcr.io/eggplants/rqw
CLI
$ 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.
Library
Overview
# 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 |
Narrowing with expect
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 ASK
Formats and raw bodies
CONSTRUCT 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.
Terms
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 literal
t-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 token
rqw.parse gives the same Query on its own, which execute accepts directly
when you send one query many times.
Endpoint settings
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.
Errors
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 message
BadQueryError, UnauthorizedError, ForbiddenError, EndpointNotFoundError,
UriTooLongError, UnsupportedMediaTypeError and EndpointError derive from
SparqlHttpError; everything rqw raises derives from RqwError.
License
Metadata
Release files for rqw 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rqw-0.0.1.tar.gz | 23.2 kB | Without provenance | Details for rqw-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rqw-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for rqw-0.0.1-py3-none-any.whl |
Total release size: 50.9 kB
Release files / rqw-0.0.1.tar.gz
| Download URL | rqw-0.0.1.tar.gz |
|---|---|
| Size | 23.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d2b957e769c95fbd37970cedafb456b2fcb0006a46c1b8705647793f79be5ca
|
|
BLAKE2b-256 checksum How to use checksums |
3c911d03a2841a5a75c54c27293475f5269d41072f2f35368255aff0cf295f02
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rqw-0.0.1-py3-none-any.whl
| Download URL | rqw-0.0.1-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b37df86f66a7ce2b0216b9c2232f71186355b321adc83abd7fddfa46c07aa7b
|
|
BLAKE2b-256 checksum How to use checksums |
70c7967bc17476a30bb7b73c8b6a3b64a7bcdb6cb08418a838854cc17f4213fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for rqw 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.