qua

Python bindings for the Quarb query engine. Quarb reads structured text as an arbor — a tree-spanned graph — and runs one query language over all of it, generalizing what XPath does for XML and jq does for JSON to JSON, YAML, TOML, CSV/TSV, XML, HTML, and Markdown alike. Try it live in the playground.

Install

pip install quarb

This installs the quarb Python module and the qua command (the language is Quarb; qua is its CLI).

Wheels are published for Linux (x86_64, aarch64), macOS (arm64, x86_64), and Windows (x86_64). The extension is built against PyO3's stable ABI (abi3-py38); a single wheel covers CPython 3.8 and later.

The qua command

The entry point covers what the bindings cover — one query over a text document:

qua '/books/*[/price:: > 20]/title::' store.json
echo '{"users":[{"name":"ada"}]}' | qua -f json '/users/*/name::'

Beyond text, quarb.open(path) dispatches on kind over the full local fleet — SQLite, kaiv (typed units), the filesystem (descend=True grafts parseable leaves), git (git:PATH), archives, XLSX, and source code — and quarb.mount([a, b, ...]) mounts several sources under one root so a single query joins across them (a YAML file <=> a SQLite database). The networked adapters — Postgres, MySQL, BigQuery, Neo4j, object stores, mail — and DuckDB live in the Rust binary: cargo install qua.

Quick start

import quarb

doc = quarb.loads("""{
  "books": [
    {"title": "Sapiens", "price": 25},
    {"title": "Cosmos",  "price": 18}
  ]
}""", "json")

doc.values('/books/*[/price:: > 20]/title::')
# ['Sapiens']

doc.value('/books/*/price:: @| mean')
# 21.5

doc.records('/books/* | rec("t", /title::, "p", /price::)')
# [{'t': 'Sapiens', 'p': 25}, {'t': 'Cosmos', 'p': 18}]

loads(text, format) / load(path) parse once into a Document, queried many times. Results come back typed: ints, floats, strings, None for null, tz-aware datetime for instants, timedelta for durations, Quantity for unit-carrying values, dicts for records. Formats: json, yaml, toml, csv, tsv, xml, html, markdown.

The lower-level quarb.run(query, text, format) and quarb.run_file(query, path) return the result lines as strings — exactly what the qua CLI prints. All errors raise ValueError with the engine's message.

For the query language itself — steps, criteria, readings, patterns, joins — see the user guide and spec.

License

Licensed under either of Apache License, Version 2.0 or the MIT license at your option. Both texts are bundled in the package.

Jupyter

%load_ext quarb.ipython
%quarb_mount fleet.daiv
%quarb /@hosts/*[::power > 0.2kW]::name

%%quarb [NAME] runs a cell-sized query against a named mount; results render as HTML tables, iterate as typed values (quantities keep magnitude + unit), and convert with .df / .df_magnitudes().

For a notebook where every cell is a query, install the dedicated kernel and pick Quarb in the launcher:

python -m quarb.kernel install
python -m quarb.kernel demo      # writes quarb-demo.ipynb to try

Cells are queries; %mount, %connect, %use, %docs, %translate, and %python (an escape hatch — the rest of the cell is Python, with the live session and the last result _ in scope) are the directives. Tab-completion offers the mounted arbor's real child names, and the bundled JupyterLab extension highlights Quarb syntax in cells automatically. %connect NAME PATH... (magic: %quarb_connect) attaches to a qua --resident daemon — for arbors too large to rebuild per notebook, queried from a standing session. pip install quarb[jupyter] pulls IPython, pandas, and the kernel runtime.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.29.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for deyanovich from gravatar.com deyanovich

Credits

Author: Bojan Đuričković

License expression

MIT OR Apache-2.0
View SPDX License List

Requires

Python >=3.8

Provides Extra

jupyter

Tags

query quarb json yaml csv xpath jq

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quarb-0.5.0.tar.gz (537.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

quarb-0.5.0-cp38-abi3-win_amd64.whl (5.4 MB view details)

Uploaded CPython 3.8+Windows x86-64

quarb-0.5.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ x86-64

quarb-0.5.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.2 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

quarb-0.5.0-cp38-abi3-macosx_11_0_arm64.whl (4.9 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

quarb-0.5.0-cp38-abi3-macosx_10_12_x86_64.whl (5.1 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file quarb-0.5.0.tar.gz.

File metadata

  • Download URL: quarb-0.5.0.tar.gz
  • Upload date:
  • Size: 537.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for quarb-0.5.0.tar.gz
Algorithm Hash digest
SHA256 3d2ca809951a6f25dd7c96f9fc899452ac9c99da209e303c069ed57259b38d28
MD5 be6bf5be1408a30025c507ae9823a40e
BLAKE2b-256 abdeec07d45ce6d8c419867c926b6d139dfc597dcd013e2f517bdd46729d1ffc

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0.tar.gz:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quarb-0.5.0-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: quarb-0.5.0-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 5.4 MB
  • Tags: CPython 3.8+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for quarb-0.5.0-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0675ffee5f1345ede06a518f76a84aa95193acdd847837c272b935d645621312
MD5 a28e6d7bcad2b578664f988550e96c35
BLAKE2b-256 88885aa37f8b13321316815b72f06ab4c2608f2d6adfedca8261dacbb519ed2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0-cp38-abi3-win_amd64.whl:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quarb-0.5.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for quarb-0.5.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a985c394d4881c301618a8508386147018d8d3654d8da9c8a0b033b48f7a760b
MD5 dd665da50ec6bb5192d0028b4866422f
BLAKE2b-256 f723b81261389620efe5401db6200302b683e7e0273663bbe31951a766f907ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quarb-0.5.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for quarb-0.5.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 df0c71f18781959bb0c06fb14f8e7aca29960b3f2b5ecf26c50110fa1aeb2389
MD5 fec049b9e3b7ce749666663b80ea08e1
BLAKE2b-256 51e69f9471662c74393e64521c9b12010d25cefc66f59355ac944037f2ab7c6e

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quarb-0.5.0-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: quarb-0.5.0-cp38-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 4.9 MB
  • Tags: CPython 3.8+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for quarb-0.5.0-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 846385bfb8d63897e52029a0395c7f384b9e46971152ab8073adbead2df7d1be
MD5 68a6c9ce3033c1a16af357af1277919d
BLAKE2b-256 36259f15778138f00c5cd4a5e63b363a246bed008db51931dc98f5db63e7ae49

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quarb-0.5.0-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for quarb-0.5.0-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4284a939db109b518c40e63d06430e7439a9f1e7a12c2aee259025e9e7cec856
MD5 95490c0d7001a2deaf20355979b438b6
BLAKE2b-256 47f88ba2339e25d4e0c776dc6eb71345a43a1ddd86684dbf5b90e04928cedb25

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.5.0-cp38-abi3-macosx_10_12_x86_64.whl:

Publisher: publish-pypi.yml on deyanovich/quarb-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.29.0

6 files

0.28.0

6 files

0.27.0

6 files

0.26.0

6 files

0.25.0

6 files

0.24.0

6 files

0.23.0

6 files

0.22.0

6 files

0.21.0

6 files

0.20.0

6 files

0.19.0

6 files

0.18.0

6 files

0.17.0

6 files

0.16.0

6 files

0.15.0

6 files

0.14.0

6 files

0.13.0

6 files

0.12.0

6 files

0.11.0

6 files

0.10.0

6 files

0.9.0

6 files

0.6.0

6 files

This release

0.5.0 This release

6 files

0.4.0

6 files

0.3.6

6 files

0.3.5

6 files

0.3.4

6 files

0.3.3

6 files

0.3.2

6 files

0.3.1

6 files

0.3.0

6 files

0.2.0

6 files

0.1.1

6 files

0.1.0

6 files

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