Skip to main content

rqw

PyPI CI ghcr size

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
  • httpx only: one connection pool per client, asyncio support, 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

MIT 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)

Source distribution for rqw 0.0.1
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)

Table of built distributions (wheels) for rqw 0.0.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page