python

cozip

Python bindings for libcozip. Read a Cloud-Optimized ZIP archive's manifest over HTTP range requests, or write one from a pyarrow Table.

The native libcozip binary ships inside the wheel, no C toolchain required.

Install

pip install cozip

Usage

Write

import cozip
import pyarrow as pa

table = pa.table({
    "name": ["a.txt", "b.bin"],
    "path": ["/path/to/a.txt", "/path/to/b.bin"],
})

cozip.write("out.zip", table)

name is how each file appears inside the archive. path is where it lives on disk, used at write time and dropped from the manifest. Any extra columns ride along into __metadata__ and become queryable on read.

Names stored in the archive must be ASCII. Local source and output paths may contain Unicode. Empty files are not valid cozip entries; the writer rejects them before replacing the output.

table = pa.table({
    "name":      ["a.tif", "b.tif"],
    "path":      ["/path/to/a.tif", "/path/to/b.tif"],
    "cloud_pct": [12.3, 45.1],
})

cozip.write("out.zip", table)

Read

import cozip

manifest = cozip.read("https://example.com/dataset.zip")
train = manifest[manifest["split"] == "train"]

manifest is a pandas DataFrame: name, offset, size, cozip:location, and the writer's extras. Local path or URL, same call. It fetches the byte-0 index and __metadata__, never the payloads.

columns=[...] picks extras. location=False drops cozip:location.

cozip.read() supports only Flat-profile archives (profile = 1). TACO archives (profile = 2) and all other profiles are rejected.

Versioning

The package version is the repo-root VERSION, copied at build time. The bundled .so / .dylib / .dll carries the same version as the wheel.

import cozip
cozip.__version__                  # "2026.9.4"
cozip.lib.cozip_version_string()   # full C library version

Spec

See SPEC.md for the on-disk format.

License

MIT. See LICENSE.