Metadata-Version: 2.4
Name: quarb
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Text Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: ipython ; extra == 'jupyter'
Requires-Dist: pandas ; extra == 'jupyter'
Provides-Extra: jupyter
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: One query language for every tree — Python bindings for the Quarb engine: JSON, YAML, TOML, CSV, XML, HTML, Markdown, SQLite, kaiv (typed units), filesystem, git, archives, XLSX, and source code (Rust/Python/JS/C), plus jq/XPath/SQL translators
Keywords: query,quarb,json,yaml,csv,xpath,jq
Home-Page: https://quarb.org
Author: Bojan Đuričković
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://quarb.org/
Project-URL: Repository, https://gitlab.com/quarb/engine

# qua

Python bindings for the [Quarb][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][playground].

[quarb]: https://quarb.org/
[playground]: https://demo.quarb.org/

## Install

```bash
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:

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

The full `qua` CLI — file systems, git, databases, mail,
adapter composition — is the Rust binary: `cargo install qua`.

## Quick start

```python
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][quarb].

## 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()`. `pip install quarb[jupyter]` pulls IPython
and pandas.

