docs: the Python package — install with maturin, h5py-style reading

README gains a Python section (maturin develop into a venv, a reading example that was run against an h5py-written file, the supported types and keys, what writing covers). The crate README says the same in more detail. QUICKSTART showed clawhdf5.open()/read_f64(), which never existed; it now shows File(...)[...]. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-09-26 08:21:48 -05:00
parent f7d88bb4fb
commit c3850a0b66
3 changed files with 107 additions and 14 deletions
@@ -407,6 +407,48 @@ let values = ds.read_f64()?;
 assert_eq!(values, vec![22.5, 23.1, 21.8]);
 ```

+### Python
+
+`crates/clawhdf5-py` is a Python package (PyO3 + numpy) that reads HDF5 with
+an h5py-shaped API and no libhdf5. It is not on PyPI; build it with
+[maturin](https://www.maturin.rs) into a virtualenv:
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install maturin numpy
+maturin develop --release -m crates/clawhdf5-py/Cargo.toml
+python -c "import clawhdf5; print(clawhdf5.__version__)"
+```
+
+```python
+import numpy as np
+import clawhdf5
+
+with clawhdf5.File("data.h5", "r") as f:
+    print(list(f.keys()))              # sorted member names, like h5py
+    ds = f["group/temperatures"]       # relative or absolute ("/group/...") paths
+    print(ds.shape, ds.dtype)          # dtype is the numpy dtype h5py reports
+    block = ds[100:200, ::4]           # reads only the selected elements
+    row = ds[-1]                       # integers drop the axis
+    picked = ds[[1, 5, 9], :]          # one increasing index list per key
+    units = ds.attrs["units"]          # attributes come back as h5py returns them
+    everything = np.asarray(ds)
+
+    records = f["table"]               # compound -> numpy structured array
+    ids = records["id"]                # one field
+```
+
+Reads cover integers and IEEE floats of every width in either byte order,
+`bool`, enums, complex, fixed and variable-length strings, variable-length
+sequences, opaque, HDF5 array types and compounds; other types (references,
+bitfields, ...) raise `TypeError` instead of returning guessed data. Keys
+follow h5py (negative steps, `None` and boolean masks are refused). The
+read itself runs with the GIL released, so Python threads read in parallel.
+Writing (`File(path, "w")`, `create_dataset`, `create_group`, `attrs[...] =`)
+covers `float64`, `float32`, `int64`, `int32` and `uint8` arrays. The tests
+in `crates/clawhdf5-py/tests` compare every read with h5py; run them with
+`pip install pytest h5py && pytest crates/clawhdf5-py/tests`.
+
 ### Agent Memory

 ```rust