quarb

Python bindings for the Quarb query engine — import quarb, plus qua, its command-line face. 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.26.0.tar.gz (930.2 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.26.0-cp38-abi3-win_amd64.whl (10.5 MB view details)

Uploaded CPython 3.8+Windows x86-64

quarb-0.26.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.9 MB view details)

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

quarb-0.26.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (10.3 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

quarb-0.26.0-cp38-abi3-macosx_11_0_arm64.whl (9.7 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

quarb-0.26.0-cp38-abi3-macosx_10_12_x86_64.whl (10.2 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for quarb-0.26.0.tar.gz
Algorithm Hash digest
SHA256 fa4e042b54d75574f869c543b59c86343843ebb52629478a8a60413fea429d6e
MD5 4e9d509e659e4897e96f2dd832588e0f
BLAKE2b-256 ec77821af29a8be5dfecace3445995303871b498fe65fefee938abb6993fc61e

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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.26.0-cp38-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for quarb-0.26.0-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3057f314e0a87a89dfe26cc614d6b007c5249e0c224efa66c10f347fe3fccb2b
MD5 847995a763151052695e981486998178
BLAKE2b-256 cf6811c0e4df6ef0c787f067a67fee8a20b3eaa70428f957ff7293dd16eb5749

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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.26.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for quarb-0.26.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 71fa8fce5e17325524da07bdf722924f8e5cc383a446108909efa706a6d6270a
MD5 284715405d3a94a4b1789314e666bb7b
BLAKE2b-256 8dc61bd57c44e77940c20032a6c1a79c77a4d398e0e346de019cd93fb57488c8

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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.26.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for quarb-0.26.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c6d1ab28ada6ed459a0612ceb1aa855a4ac6c53ecce67ed123942045fb183251
MD5 69397bc0e36ff803e4682ae489a43f08
BLAKE2b-256 b1f7af28154275aa91704a5089cc42153fbe339131e2c54a0eb2e86d59be29c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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.26.0-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for quarb-0.26.0-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 afdb19aad8868abf7bb24c2a3d9b7d5399f52d5513b53a99789dbcca7b9b3660
MD5 0650bbb9a6b6155825cb3b7a724bb800
BLAKE2b-256 a56aa417b994e853b15b26e85eafe7b49989df0ce1fce8163e4fd743ea03ab3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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.26.0-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for quarb-0.26.0-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 d7e8be133697f1faf3e9140eeb8c0b92d84b5bb73824713885caffd43373fe75
MD5 39c630d014e76128ad3ec562cc7871b4
BLAKE2b-256 0bb8a6b0d6557a663fe4aa586af914ce4ffbeb9b1ce3d8e0cbe7462c296d6ca8

See more details on using hashes here.

Provenance

The following attestation bundles were made for quarb-0.26.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

This release

0.26.0 This release

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

0.5.0

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