Metadata-Version: 2.4
Name: refkv
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Dist: google-crc32c>=1.9.0
Requires-Dist: numpy>=2.5.3
Requires-Dist: obstore>=0.11.1
Requires-Dist: refkv[zarr] ; extra == 'images'
Requires-Dist: imagecodecs>=2026.8.16 ; extra == 'images'
Requires-Dist: refkv[zarr] ; extra == 'virtualizarr'
Requires-Dist: virtualizarr>=2.7.3 ; extra == 'virtualizarr'
Requires-Dist: zarr>=3.4.0 ; extra == 'zarr'
Provides-Extra: images
Provides-Extra: virtualizarr
Provides-Extra: zarr
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: refkv: a reference value type for key-value stores, its ZIP binding (vzip archives), and virtualization of image files and stores
Author-email: Davis Vann Bennett <davis.v.bennett@gmail.com>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/d-v-b/refkv/tree/main/docs
Project-URL: Repository, https://github.com/d-v-b/refkv

# refkv: reference-aware key-value storage

refkv defines reference semantics for key-value storage. This allows an object
in one key-value store to refer to a byte range, or sequence of byte ranges,
in other storage backends ([spec](https://github.com/d-v-b/refkv/blob/main/spec/refkv.md)). refkv is used to define
vzip, a single-file reference-aware storage solution: a `.vzip` archive keeps
a reference store in one ordinary ZIP file
([its binding](https://github.com/d-v-b/refkv/blob/main/spec/bindings/vzip.md)).

This package holds reference stores in memory, reads and writes vzip archives,
and virtualizes TIFF, NDPI, ND2, CZI, DICOM, NIfTI and Imaris files, N5,
Zarr v2 and OME-Zarr stores, and Sentinel-2 SAFE products through its Rust
core, without copying their pixels ([docs](https://github.com/d-v-b/refkv/blob/main/docs/README.md)).

```python
from refkv.virtualize import virtualize

store = virtualize("https://example.org/slide.ndpi")  # a refkv.ReferenceStore
store.save("slide.vzip")                               # one vzip archive
```

For netCDF, HDF5 and the other files
[VirtualiZarr](https://virtualizarr.readthedocs.io/) reads,
`refkv.ReferenceStore.from_virtualizarr(vds)` turns a virtual dataset into a
store that xarray opens ([example](https://github.com/d-v-b/refkv/blob/main/docs/virtual-datasets.md)).

```bash
pip install refkv                  # read, write, virtualize
pip install "refkv[zarr]"          # refkv.zarr: open a store with zarr-python and xarray
pip install "refkv[images]"        # and the JPEG, JPEG 2000 and JPEG XR codecs
pip install "refkv[virtualizarr]"  # virtual datasets from VirtualiZarr
```

Wheels are built for Linux and macOS (Python 3.12 and later); Windows is not
supported yet.

Status: experimental, anything can change. Source, spec and issues:
<https://github.com/d-v-b/refkv>.

