npco 0.1.0

Pcodec-compressed numpy arrays — drop-in save/load for .npc/.npcz files

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 compression. The API mirrors numpy's save/load/savez so you can start using it immediately.

Install

pip install npco

Quick start

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.

# 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).