Metadata-Version: 2.4
Name: npco
Version: 0.1.0
Summary: Pcodec-compressed numpy arrays — drop-in save/load for .npc/.npcz files
Author-email: Niels Jeppesen <niels@jeppesen.dk>
License-Expression: MIT
Keywords: numpy,compression,pcodec,ndarray,scientific
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2
Requires-Dist: pcodec>=1
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# npco

Pcodec-compressed numpy arrays — a drop-in replacement for `numpy.save`/`numpy.load`.

**npco** stores ndarrays in `.npc` files (single array) and `.npcz` files (multiple arrays) using [pcodec](https://github.com/pcodec/pcodec) compression. The API mirrors numpy's `save`/`load`/`savez` so you can start using it immediately.

## Install

```bash
pip install npco
```

## Quick start

```python
import numpy as np
import npco

# Save a single array
arr = np.random.default_rng(0).standard_normal((1000, 100))
npco.save("data.npc", arr)

# Load it back
arr = npco.load("data.npc")

# Save multiple arrays
npco.savez("data.npcz", x=arr, labels=np.arange(1000))

# Load them back (lazy, dict-like)
with npco.load("data.npcz") as data:
    print(data.files)  # ['x', 'labels']
    x = data["x"]
```

## Compression options

**Note: Compression levels greater than 8 often have limited effect on the compressed size but are significantly slower.**

```python
# Set compression level (0–12, higher = smaller + slower)
npco.save("data.npc", arr, compression_level=8)

# Or pass a full ChunkConfig for advanced control
from pcodec import ChunkConfig, DeltaSpec

npco.save(
    "data.npc",
    arr,
    chunk_config=ChunkConfig(
        compression_level=8,
        delta_spec=DeltaSpec.try_consecutive(2),
    ),
)
```

## Supported dtypes

float16, float32, float64, int8, int16, int32, int64, uint8, uint16, uint32, uint64.

Unsupported dtypes (complex, object, strings, …) raise `TypeError`.

## API

| Function | Description |
|---|---|
| `npco.save(file, arr, *, compression_level=None, chunk_config=None)` | Save one array to `.npc` |
| `npco.load(file)` | Load from `.npc` → ndarray, or `.npcz` → NpczFile |
| `npco.savez(file, *args, compression_level=None, chunk_config=None, **kwds)` | Save multiple arrays to `.npcz` |

## File format

`.npc` uses a numpy-style binary header (magic `\x93NPCO\x00`, dtype, shape, memory order) followed by pcodec standalone compressed data.

`.npcz` is a ZIP archive of `.npc` entries (no zip-level compression since pcodec already compresses the data).

## Limitations

- **No memory-mapping** — pcodec requires full decompression
- **No pickle / object arrays** — only numeric dtypes above are supported

## Acknowledgements

Made with the assistance of Claude Opus 4.6.

## License

MIT License (see LICENSE file).
