Metadata-Version: 2.4
Name: qroissant
Version: 0.2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Implementation :: CPython
License-File: LICENSE
Summary: Minimal q/kdb+ IPC decoder and Arrow bridge implemented in Rust
Keywords: kdb,q,ipc,arrow,polars
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Qroissant

`qroissant` is a minimal q/kdb+ IPC client library with first-class support for the Apache Arrow ecosystem.

* **Lightweight**: `qroissant` is a minimal library weighing in at less than 3MiB with no required dependencies.
* **Fast**: `qroissant` is written in Rust, a safe and high-performance systems programming language. Moreover, `qroissant` uses your system resources to the best extent possible by leveraging zero-copy, multithreading and other vectorization techniques such as SIMD.
* **Modular**: `qroissant` relies heavily on the Apache Arrow PyCapsule Interface for communicating with other libraries from the Apache Arrow ecosystem with zero-copy. This includes `pyarrow`, `polars`, `duckdb`, `pandas`, `datafusion`, etc.
* **Type hints**: `qroissant` provides type annotations for all of its functionality.


## Getting started
You can install `qroissant` using `pip`:
```shell
pip install qroissant
```

## Usage
### 1. Connecting to a remote q/kdb+ process
```python
import polars as pl
import qroissant as qr

with qr.TCPStream(
    options=qr.TCPOptions(
        host="localhost",
        port=18000,
        username="myuser",
        password="mypassword",
    ),
) as stream:
    message = stream.send_sync("select date, sym, price from mytable")
    # Just call the constructor `pl.DataFrame` (or similar for any other
    # library that supports the Arrow PyCapsule Interface) for zero-copy
    # conversion.
    df = pl.DataFrame(message)
    print(df)
```

### 2. Decoding existing IPC payloads
```python
import qroissant as qr

# `payload` can be `bytes`, a read-only contiguous buffer, or a
# serializer object exposing such a buffer through `.data`.
payload = b"... q IPC bytes ..."
message = qr.deserialize(payload)
```

### 3. Tuning Arrow conversion
```python
import qroissant as qr

options = (
    qr.Options.builder()
    .with_symbol_interpretation(qr.SymbolInterpretation.DICTIONARY)
    .with_union_mode(qr.UnionMode.DENSE)
    .build()
)

message = qr.deserialize(payload, options=options)
```

`qroissant` currently focuses on deserialization and Arrow export. Direct
construction and serialization helpers for q values are not part of the
runtime API yet.

