pycrowley 0.1.0__tar.gz

pycrowley-0.1.0/.forgejo/workflows/ci.yml

@@ -0,0 +1,157 @@
+name: Build, test, and publish
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ==================================================================
+  # Test: run Rust tests and Python tests
+  # ==================================================================
+  test:
+    name: Test
+    runs-on: codeberg-medium
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          . "$HOME/.cargo/env"
+
+      - name: Set up Python
+        uses: https://code.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Rust tests
+        run: |
+          . "$HOME/.cargo/env"
+          cargo test --lib --test public_api
+
+      - name: Rust benchmarks compile check
+        run: |
+          . "$HOME/.cargo/env"
+          cargo build --bench throughput
+
+      - name: Install Python deps and build wheel
+        run: |
+          . "$HOME/.cargo/env"
+          python3 -m venv .venv
+          .venv/bin/pip install maturin pytest
+          .venv/bin/maturin develop --manifest-path python/crowley/Cargo.toml
+
+      - name: Python tests
+        run: .venv/bin/pytest python/crowley/tests/test_query.py -v
+
+  # ==================================================================
+  # Build + publish: manylinux wheels (only on tag push)
+  #
+  # Each matrix entry builds one wheel and uploads it directly to PyPI.
+  # We do NOT use upload-artifact/download-artifact because:
+  #   - The manylinux container has no Node.js, so JS-based actions fail
+  #   - Forgejo's artifact v4 support requires a patched fork and is fragile
+  # Instead each job uploads its wheel independently via twine.
+  # --skip-existing ensures no conflicts between parallel uploads.
+  #
+  # Python versions in the manylinux_2_28 image live under /opt/python/
+  # with PEP 425 tag names like cp312-cp312. We resolve the path below.
+  # ==================================================================
+  build_wheels:
+    name: Build + publish wheel (Python ${{ matrix.python-version }})
+    runs-on: codeberg-medium
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    container:
+      image: quay.io/pypa/manylinux_2_28_x86_64
+    strategy:
+      fail-fast: false
+      matrix:
+        # These must match CPython versions available in the manylinux image.
+        # As of early 2026: 3.10 through 3.14 are available.
+        # 3.15 is alpha-only and NOT in the image — add it when it ships.
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      # No actions/checkout — it needs Node.js which manylinux lacks.
+      - name: Checkout
+        run: |
+          git clone --depth 1 --branch ${{ github.ref_name }} \
+            ${{ github.server_url }}/${{ github.repository }} .
+
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          . "$HOME/.cargo/env"
+
+      - name: Resolve Python path
+        run: |
+          # manylinux stores CPythons under /opt/python/cpXYZ-cpXYZ/bin/python
+          PYVER="${{ matrix.python-version }}"
+          PYTAG="cp${PYVER//./}"
+          PYBIN="/opt/python/${PYTAG}-${PYTAG}/bin"
+          if [ ! -d "$PYBIN" ]; then
+            echo "ERROR: Python $PYVER not found at $PYBIN"
+            echo "Available versions:"
+            ls /opt/python/
+            exit 1
+          fi
+          echo "PYBIN=$PYBIN" >> "$GITHUB_ENV"
+
+      - name: Build wheel
+        run: |
+          . "$HOME/.cargo/env"
+          ${PYBIN}/python -m pip install maturin
+          ${PYBIN}/python -m maturin build --release --strip --out dist \
+            -i ${PYBIN}/python
+        working-directory: python/crowley
+
+      # Upload directly — no artifact step, no Node.js dependency.
+      - name: Upload to PyPI
+        run: |
+          ${PYBIN}/python -m pip install twine
+          ${PYBIN}/python -m twine upload dist/* --skip-existing --verbose
+        working-directory: python/crowley
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI }}
+
+  # ==================================================================
+  # Build + publish: source distribution (only on tag push)
+  #
+  # This runs on the default runner image (not manylinux), so
+  # checkout, setup-python, and other JS-based actions work fine.
+  # ==================================================================
+  build_sdist:
+    name: Build + publish sdist
+    runs-on: codeberg-small
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v4
+
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          . "$HOME/.cargo/env"
+
+      - name: Set up Python
+        uses: https://code.forgejo.org/actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build and upload sdist
+        run: |
+          . "$HOME/.cargo/env"
+          pip install maturin twine
+          maturin sdist --out dist
+          twine upload dist/* --skip-existing --verbose
+        working-directory: python/crowley
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI }}

pycrowley-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+/target
+/Cargo.lock
+/python/crowley/tests/nobel.json
+/python/crowley/Cargo.lock

pycrowley-0.1.0/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "crowley_rs"
+version = "0.1.0"
+edition = "2024"
+description = "A high-performance streaming JSON query engine with DFA-based path matching"
+license = "MIT OR Apache-2.0"
+repository = "https://codeberg.org/nrposner/crowley"
+homepage = "https://codeberg.org/nrposner/crowley"
+keywords = ["json", "query", "streaming", "dfa", "search"]
+categories = ["parser-implementations", "text-processing"]
+readme = "README.md"
+exclude = ["python/", "benches/", "tests/"]
+
+[dependencies]
+foldhash = "0.2.0"
+glob = "0.3.3"
+memchr = "2.8.0"
+pest = "2.8.6"
+pest_derive = "2.8.6"
+rayon = "1.11.0"
+regex = "1.12.3"
+serde = { version = "1.0.228", features = ["derive", "rc"] }
+serde_json = "1.0.149"
+serde_json_borrow = "0.9.0"
+thiserror = "2.0.18"
+
+[dev-dependencies]
+criterion = { version = "0.8.2", features = ["html_reports"] }
+tempfile = "3.27.0"
+
+[profile.bench]
+codegen-units = 1
+lto = "thin"

pycrowley-0.1.0/LICENSE-APACHE

@@ -0,0 +1,14 @@
+Copyright 2026 Nicolas Posner
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

pycrowley-0.1.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Posner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycrowley-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: pycrowley
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Summary: A high-performance streaming JSON query engine for out-of-memory files
+Keywords: json,query,streaming,search,big-data
+License-Expression: MIT OR Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://codeberg.org/nrposner/crowley
+Project-URL: Issues, https://codeberg.org/nrposner/crowley/issues
+Project-URL: Repository, https://codeberg.org/nrposner/crowley
+
+# crowley
+
+A high-performance JSON querying engine designed for fast starts, low flat memory usage, and out-of-memory streaming.
+
+It is primarily designed to substitute for `ijson`. If you're coming to `crowley` from `ijson`, see the IJSON Migration Guide.
+
+Written in Rust, with a SAX-style JSON event parser adapted from the [`json-event-parser`](https://crates.io/crates/json-event-parser) crate and a regular expression query language adapted from the [`jsongrep`](https://crates.io/crates/jsongrep) crate.
+
+## Use cases
+
+`crowley` is optimized for the following scenarios:
+
+- **Queries over files too large to fit comfortably in memory.** `crowley` streams through JSON files with bounded memory regardless of file size. A 37 GB file uses ~30 MB of RAM.
+- **Queries on transient data.** `crowley` quickly queries data which do not merit transformation into a more easily-queried structure such as a database or dataframe, because of time constraints or because the data is sensitive and cannot be loaded into an external application.
+- **Queries over heterogeneous, deeply-nested, and schemaless data** which tools such as `pandas`, `polars`, or `duckdb` cannot ingest and transform. `crowley`'s regular-language queries don't require schema inference.
+- **Queries over many files in parallel.** `crowley` natively supports searching over many files with the same query, using either a list of file paths or a pattern match. These files will be searched in parallel more quickly and with less memory overhead than `ijson` with a ProcessPool.
+
+## Usage
+
+### Single-file search
+```python
+from crowley import Query
+
+names = Query("data.json", "users[*].name")
+ages = Query("data.json", "users[*].age")
+
+names.count()       # 4
+names.exists()      # True
+names.values()      # ['Alice', 'Bob', "Charlie", "Diana"]
+ages.values()       # [30, 25, 35, 28]
+names.agg("sum")    # nan
+ages.agg("sum")     # 118.0
+names.types()       # ['string']
+ages.types()        # ['number']
+names.mode()        # {'values': ['Alice', 'Bob', 'Charlie', 'Diana'], 'frequency': 1}
+```
+
+### Multi-file search
+```python
+from crowley import Query
+
+repo_names = Query("tests/github_daily_jsonl/2015*", "[*].repo.name")
+
+repo_names.count() # [7702, 7427, 7234, 7387, 8273, 8971, 10307, 11351, 11749, 11961, 12229, 12314, 6743, 12442, 13111, 12473, 11601, 5971, 5869, 5887, 8322, 7105, 6139, 6371]
+repo_names.total_count() # 218939
+repo_names.total_unique() # 65703
+repo_names.mode()[0] # {'values': ['KenanSulayman/heartbeat'], 'frequency': 79}
+```
+
+## Query language
+
+The [query language](https://github.com/micahkepe/jsongrep?tab=readme-ov-file#query-syntax) uses a regular-expression-inspired syntax for navigating JSON structure:
+
+| Query | Meaning |
+|-------|---------|
+| `name` | Field `name` in the root object |
+| `address.street` | Field `street` inside `address` |
+| `users[*].name` | `name` field of every element in `users` array |
+| `*` | Any field in the root object |
+| `[*]` | Any element in the root array |
+| `users[0]` | First element of `users` |
+| `users[1:3]` | Elements at indices 1 and 2 |
+| `(name \| age)` | Either `name` or `age` |
+| `(* \| [*])*` | Any value at any depth (recursive descent) |
+| `a?` | Returns the value of `a` if it exists 
+
+## Performance
+
+Benchmarks measured on a Mac M3 Max with 32GB of RAM:
+
+```
+File: Flat GitHub log data, 34GB
+Query: [*].repo.name
+
+Count matches:
+    crowley: 71.6s
+    ijson: 128.8s
+    Difference: 1.8x
+
+Return matches:
+    crowley: 116.0s
+    ijson: 126.1s
+    Difference: 1.09x
+
+Return unique values:
+    crowley: 125.7 
+    ijson: 129.5s
+    Difference: 1.03x
+
+Return unique count:
+    crowley: 122.1
+    ijson: 129.5s
+    Difference: 1.06x
+
+File: Nested GeoJSON, 30MB
+Query: features[*].properties.name
+
+Count matches:
+    crowley: 138.44ms
+    ijson: 421.85ms
+    Difference: 3.0x
+
+Existence check (true):
+    crowley: 16µs
+    ijson: 793µs
+    Difference: 49x
+
+Query: features[*].properties.scalerank
+
+Sum matches:
+    crowley: 184.88ms
+    ijson: 425.89ms
+    Difference: 2.3x
+
+Query: features[*].properties.nonexistent
+
+Existence check (false):
+    crowley: 138.9ms
+    ijson: 409.7ms
+    Difference: 2.9x
+```
+
+On queries where the objective is to return values `crowley` outperforms `ijson` by 3-10%. In cases where a measure such as count or aggregate sum is returned, `crowley` can often outperform `ijson` by 2-3x by avoiding materializing values unnecessarily.
+
+But the real benefit comes from `crowley`'s more expressive query language, which can efficiently express what would otherwise require Python loops aroung ijson. 
+
+It can extract multiple fields through disjunctions (at one or multiple levels) in a single pass without having to materialize the parent object:
+
+```python
+# get the number of matching objects
+# 133.6ms
+crowley.Query(file_str, "features[*].properties.(name | admin)").count()
+
+# get the number of unique matches
+# 144.2ms
+crowley.Query(file_str, "features[*].properties.(name | admin)").unique_values()
+
+# get the number of matching objects
+# 851.6ms
+def ijson_two_passes():
+    with open(file_str, "rb") as f:
+        count1 = sum(1 for _ in ijson.items(f, "features.item.properties.name"))
+    with open(file_str, "rb") as f:
+        count2 = sum(1 for _ in ijson.items(f, "features.item.properties.admin"))
+    return count1 + count2
+ijson_two_passes()
+
+# get the number of unique matches
+# 430ms
+def ijson_two_fields():
+    names = set()
+    with open(file_str, "rb") as f:
+        for obj in ijson.items(f, "features.item.properties"):
+            if "name" in obj:
+                names.add(obj["name"])
+            if "admin" in obj:
+                names.add(obj["admin"])
+    return names
+ijson_two_fields()
+```
+
+It can extract all property values without internal iteration:
+
+```python
+# get the number of all matching property values by query
+# 133.9ms
+crowley.Query(file_str, "features[*].properties.*").count()
+
+# get the  number of all matching properties by internal iteration
+# 427.9ms
+def ijson_all_props():
+    count = 0
+    with open(file_str, "rb") as f:
+        for obj in ijson.items(f, "features.item.properties"):
+            count += len(obj)
+    return count
+ijson_all_props()
+```
+
+It can select ranges of array elements without manual index checking:
+
+- Note: this is one of the few places `crowley` can be slower under some conditions: if the array range is not at the root level, `ijson` + Python break logic can stop more quickly, while `crowley` must continue parsing the outer structure. For root-level array ranges, `crowley` remains faster. Attempting to use the same approach with `crowley` as with `ijson`, manually checking values and breaking out, makes crowley even slower, however.
+
+```
+Root-level array (github_array.json):
+    crowley [0:3]: 22µs (crowley terminates early more quickly)
+    ijson [0:3]+break: 234µs
+    Difference: 10.6x
+
+    crowley [97:102]: 464µs (crowley terminates early more quickly)
+    ijson [97:102]+break: 923 µs
+    Difference: 1.98x
+
+    crowley [*] (full): 49.4ms
+    crowley [*]+break: 60.9ms
+
+Nested array (ne_10m.json):
+    crowley [0:3]: 131.4ms
+    ijson [0:3]+break: 847µs (ijson is able to short-circuit faster!)
+    Difference: 0.006x
+
+    crowley [97:102]: 133.8ms
+    ijson [97:102]+break: 11.5ms (ijson is able to short-circuit faster!)
+    Difference: 0.086x
+```
+
+```python
+# start of array
+crowley.Query(file_str, "features[0:3].properties.name", no_seek=True).values()
+
+# middle of array
+crowley.Query(file_str, "features[97:102].properties.name", no_seek=True).values()
+
+def ijson_range_start():
+    result = []
+    with open(file_str, "rb") as f:
+        for i, name in enumerate(ijson.items(f, "features.item.properties.name")):
+            if i < 3:
+                result.append(name)
+            else:
+                break
+    return result
+ijson_range_start()
+
+def ijson_range_mid():
+    result = []
+    with open(file_str, "rb") as f:
+        for i, name in enumerate(ijson.items(f, "features.item.properties.name")):
+            if 97 <= i < 102:
+                result.append(name)
+            if i >= 101:
+                break
+    return result
+ijson_range_mid()
+```
+
+And can even descend recursively in a way that `ijson` simply cannot do: this would require a non-streaming solution like `json` that loads the whole file into memory.
+
+```python
+# get unique values of 'type' at any depth 
+# 221.8ms : ['FeatureCollection', 'name', 'Feature', 'Polygon']
+crowley.Query(file_str, "(* | [*])*.type", no_seek=True).unique_values()
+
+# get count of all matching objects at all depths
+# 156.7ms : 17090
+crowley.Query(file_str, "(* | [*])*.type", no_seek=True).count()
+
+# walk the entire json tree manually looking for matching keys
+# 509.8ms
+import json
+def json_recursive_search(key):
+    with open(file_str) as f:
+        data = json.load(f)
+
+    results = []
+    def walk(obj):
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if k == key:
+                    results.append(v)
+                walk(v)
+        elif isinstance(obj, list):
+            for item in obj:
+                walk(item)
+    walk(data)
+    return results
+
+values = json_recursive_search("type")
+unique = set(str(x) for x in values)
+```
+
+### Cold vs Hot Start
+
+On cold starts (first query, no prior loading), `crowley` is **2-3x faster than pandas**, **3-7x faster than DuckDB**, and handles files that make Polars fail entirely due to schema inference errors.
+
+On subsequent calls, methods such as `count()` or `exists()` return their pre-computed answer in **O(1)** with zero file I/O. Other methods like `types()` and `agg()` will determine whether reading only matched byte positions will be faster than a full sequential scan. 
+
+However, on very large files with a large volume of matches, the cached byte offsets for matches can considerably exceed the memory usage from streaming itself, and these offsets remain in the Query object until it is dropped. The query's cache can be manually cleared with `.clear_cache()`, and cache accumulation can be deactivated at query creation with the `no_seek=True` kwarg. This can be configured globally with `crowley.configure(no_seek=True)`.
+
+## Acknowledgments
+
+Built on the DFA-based query engine from [jsongrep](https://github.com/micahkepe/jsongrep) by Micah Kepe, and the SAX parser from [json-event-parser](https://github.com/oxigraph/json-event-parser) by the Oxigraph project.
+
+This project benefits not only from the work of other developers, but also from their choice to make their source code public and freely re-usable under the MIT and Apache2.0 licenses.
+

pycrowley-0.1.0/README.md

@@ -0,0 +1,121 @@
+# crowley_rs
+
+A high-performance JSON querying engine designed for fast starts, low flat memory usage, and out-of-memory streaming. It uses a custom SAX-style JSON event parser adapted from the [`json-event-parser`](https://crates.io/crates/json-event-parser) crate and a regular expression query language adapted from the [`jsongrep`](https://crates.io/crates/jsongrep) crate.
+
+## Use cases
+
+`crowley_rs` is optimized for the following scenarios:
+
+- **Queries over files too large to fit comfortably in memory.** `crowley_rs` streams through JSON files with bounded memory regardless of file size. A 37 GB file uses ~30 MB of RAM.
+- **Queries on transient data.** `crowley_rs` quickly queries data which do not merit transformation into a more easily-queried structure such as a database or dataframe, because of time constraints or because the data is sensitive and cannot be loaded into an external application.
+- **Queries over heterogeneous, deeply-nested, and schemaless data** which tools such as `pandas`, `polars`, or `duckdb` cannot ingest and transform. `crowley_rs`'s path-based queries don't require schema inference.
+- **Queries over many files in parallel.** `crowley` natively supports searching over many files with the same query, using either a list of file paths or a pattern match.
+
+## Performance
+
+Its closest streaming cousin is [`ijson`](https://pypi.org/project/ijson/), which it reliably beats in runtime performance by at least 2x on full scans, with a wider margin on deeply nested data. It is also less memory-hungry and starts up in <50 us as opposed to ~500 us.
+
+If your `ijson` queries are a drag on other parts of your data pipeline and can be translated into the jsongrep regular query language, consider switching to `crowley_rs`.
+
+On cold starts (first query, no prior loading), `crowley_rs` is **2-3x faster than pandas**, **3-7x faster than DuckDB**, and handles files that make Polars fail entirely due to schema inference errors.
+
+Accumulating methods cache byte offsets after the first scan. Subsequent calls to `count()` and `exists()` return in **O(1)** with zero file I/O. Seek-based methods like `types()` and `agg()` read only the matched byte positions rather than re-scanning the entire file.
+
+## Usage
+
+```rust
+use crowley_rs::{
+    Query, CrowleyError, Value,
+    AggMode, ModeResult, StreamMatch, PathType, JsonType,
+    format_path,
+};
+
+let mut q = Query::from_file("data.json", "users[*].name")?;
+
+// Streaming modes — return iterators
+let values: Vec<Value> = q.values()?.collect::<Result<_, _>>()?;
+let paths: Vec<Vec<PathType>> = q.paths()?.collect::<Result<_, _>>()?;
+let offsets: Vec<usize> = q.offsets()?.collect::<Result<_, _>>()?;
+for m in q.contents()? {
+    let m: StreamMatch = m?;
+    println!("{} = {}", format_path(&m.path), m.value);
+}
+
+// Accumulating modes — return single results
+let count: usize = q.count()?;
+let exists: bool = q.exists()?;
+let types: std::collections::HashSet<JsonType, _> = q.types()?;
+let unique: Vec<Value> = q.unique_values()?;
+
+// Numeric aggregations
+let sum: f64 = q.agg(AggMode::Sum)?;
+let min: f64 = q.agg(AggMode::Min)?;
+let max: f64 = q.agg(AggMode::Max)?;
+let mean: f64 = q.agg(AggMode::Mean)?;
+
+// Most frequent value(s) — handles ties
+let mode: ModeResult = q.mode()?;
+// mode.values: Vec<Value>, mode.frequency: usize
+
+// Disable seek-based caching (e.g. for dense matches or slow-seek storage)
+let mut q = Query::from_file("data.json", "*")?.no_seek();
+```
+
+`crowley` also supports searching over multiple files in parallel using the MultiQuery struct.
+
+## Query language
+
+The [query language](https://github.com/micahkepe/jsongrep?tab=readme-ov-file#query-syntax) uses a regular-expression-inspired syntax for navigating JSON structure:
+
+| Query | Meaning |
+|-------|---------|
+| `name` | Field `name` in the root object |
+| `address.street` | Field `street` inside `address` |
+| `users[*].name` | `name` field of every element in `users` array |
+| `*` | Any field in the root object |
+| `[*]` | Any element in the root array |
+| `users[0]` | First element of `users` |
+| `users[1:3]` | Elements at indices 1 and 2 |
+| `(name \| age)` | Either `name` or `age` |
+| `(* \| [*])*` | Any value at any depth (recursive descent) |
+| `a?` | Returns the value of `a` if it exists 
+
+## Python bindings
+
+Python bindings are available as the `crowley` package (separate PyPI distribution):
+
+### Single-file search
+```python
+from crowley import Query
+
+names = Query("data.json", "users[*].name")
+ages = Query("data.json", "users[*].age")
+
+names.count()       # 4
+names.exists()      # True
+names.values()      # ['Alice', 'Bob', "Charlie", "Diana"]
+ages.values()       # [30, 25, 35, 28]
+names.agg("sum")    # nan
+ages.agg("sum")     # 118.0
+names.types()       # ['string']
+ages.types()        # ['number']
+names.mode()        # {'values': ['Alice', 'Bob', 'Charlie', 'Diana'], 'frequency': 1}
+```
+
+### Multi-file search
+
+```python
+from crowley import Query
+
+repo_names = Query("tests/github_daily_jsonl/2015*", "[*].repo.name")
+
+repo_names.count() # [7702, 7427, 7234, 7387, 8273, 8971, 10307, 11351, 11749, 11961, 12229, 12314, 6743, 12442, 13111, 12473, 11601, 5971, 5869, 5887, 8322, 7105, 6139, 6371]
+repo_names.total_count() # 218939
+repo_names.total_unique() # 65703
+repo_names.mode()[0] # {'values': ['KenanSulayman/heartbeat'], 'frequency': 79}
+```
+## Acknowledgments
+
+Built on the DFA-based query engine from [jsongrep](https://github.com/micahkepe/jsongrep) by Micah Kepe, and the SAX parser from [json-event-parser](https://github.com/oxigraph/json-event-parser) by the Oxigraph project.
+
+This project benefits not only from the work of other developers, but also from their choice to make their source code public and freely re-usable under the MIT and Apache2.0 licenses.