Metadata-Version: 2.4
Name: wickra-xray
Version: 0.1.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Rust
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: The data-driven market-microstructure frame core: build an Xray from a spec, drive it with commands, read back frames.
Keywords: trading,microstructure,orderbook,footprint,finance
Home-Page: https://wickra.org
Author-email: kingchenc <support@wickra.org>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/wickra-lib/wickra-xray
Project-URL: Issues, https://github.com/wickra-lib/wickra-xray/issues
Project-URL: Repository, https://github.com/wickra-lib/wickra-xray

# Wickra X-Ray — Python

Python bindings for [`wickra-xray-core`](https://github.com/wickra-lib/wickra-xray),
built with [PyO3] and [maturin]. The surface mirrors every other Wickra binding:
build an `Xray` from a spec JSON, drive it with command JSONs, and read back
render frames.

## Install

```sh
pip install wickra-xray
```

## Usage

```python
import json
from wickra_xray import Xray

spec = json.dumps({
    "dataset_ref": "mini", "symbol": "AAA",
    "panels": [{"kind": "footprint", "price_bin": 1.0, "bucket_ms": 60000}],
})

xray = Xray(spec)
xray.command(json.dumps({"cmd": "load", "dataset": {
    "trades": [{"ts": 1000, "price": 100.4, "qty": 2.0, "side": "buy"}],
}}))
frame = json.loads(xray.command(json.dumps({"cmd": "frame"})))
print(frame["symbol"], frame["cursor_ts"])
```

## Surface

- **`Xray(spec_json)`** builds an xray from a spec JSON (`""` or `"{}"` for an
  empty handle whose spec is set later). Raises `ValueError` on a malformed spec.
- **`xray.command(cmd_json)`** applies a command JSON (`set_spec`, `load`,
  `frame`, `frame_at`, `bounds`, `reset`, `version`) and returns the response
  JSON. Domain errors come back in-band as `{"ok":false,"error":...}`.
- **`Xray.version()`** returns the library version.

## Build from source

```sh
maturin develop --release
pytest -q
```

[PyO3]: https://pyo3.rs
[maturin]: https://www.maturin.rs

