py: in-place editing (clawhdf5.File(path, 'r+')) through FileEditor

clawhdf5.File(path, 'r+') (and 'a' on an existing file) holds a
FileEditor, and with it the file's exclusive lock, until close():

- ds[key] = value: h5py's keys and broadcasting (numpy's rules for
  slices and integers with extra leading 1-axes allowed; the exact shape
  for an index list, a scalar only where h5py expands it). Arrays are
  converted as libhdf5 converts them in native byte order (integers
  saturate, floats truncate toward zero and clip, integers go into h5py's
  bool enum by value); other values through
  numpy.asarray(value, dtype=ds.dtype), as h5py does. NaN into an integer
  dataset is a ValueError instead of libhdf5's arbitrary value. The value
  preparation is a small Python module compiled into the extension
  (src/edit_helpers.py).
- ds.resize(shape) / ds.resize(n, axis=k) with h5py's argument rules.
- attrs[name] = value, attrs.create(name, data, shape, dtype),
  attrs.modify: numeric, bool, complex, bytes and str data of any shape,
  with h5py's HDF5 types; str is stored as fixed-length UTF-8 (the editor
  cannot write variable-length strings).
- File.mode, File.flush(), Dataset.chunks.

Each edit runs with the GIL released under the file handle's write lock
(no read sees a half-written edit), then the file is reopened;
datasets and attrs objects re-read their shape and attributes when the
handle's edit generation moved. What the editor cannot do is
NotImplementedError before anything is written: deleting attributes or
objects, creating datasets or groups, compound fields by name,
variable-length data, and FileEditor's own limits.

Where libhdf5 2.0 (h5py 3.16) converts inconsistently -- its soft
conversions in non-native byte order (a float in (-1, 0) becomes the
integer minimum, same-size unsigned->signed wraps) and native casts that
are undefined in C (half floats into unsigned, float(max) rounded up) --
clawhdf5 saturates as libhdf5's native path does; listed in
docs/known-issues.md.

Tests (tests/test_edit.py): every edit applied by h5py and by clawhdf5 to
copies of the same file and both read back through h5py after each edit,
on h5py files (libver earliest, v114, latest) and a clawhdf5 file: a fixed
sequence over every chunk index kind, compact/contiguous/gzip layouts and
numeric, bool, enum, complex, string and compound types, 16 random
sequences of 40 edits, and a numeric conversion matrix; a refused edit
must be refused by both and leave the file unchanged. Also dense
attributes, locking, objects seeing edits, readers racing a writer, and
h5dump (plus h5rs check in ci-test.sh) on every edited file. The
read-vs-h5py suite also runs on a file opened 'r+'.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-py/src/file.rs

@@ -5,7 +5,7 @@ use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
-use pyo3::exceptions::PyValueError;
+use pyo3::exceptions::{PyNotImplementedError, PyValueError};
 use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyList};
 
@@ -95,6 +95,18 @@ impl PyFile {
         }
         match mode {
             "r" => Ok(Self::from_handle(Handle::open_local(py, path)?, filename)),
+            "r+" => Ok(Self::from_handle(
+                Handle::open_editable(py, path)?,
+                filename,
+            )),
+            "a" if std::path::Path::new(path).exists() => Ok(Self::from_handle(
+                Handle::open_editable(py, path)?,
+                filename,
+            )),
+            "a" => Err(PyNotImplementedError::new_err(format!(
+                "mode 'a' on {path}, which does not exist: clawhdf5 can only edit an existing \
+                 file in place; create a new one with mode 'w'"
+            ))),
             "w" => Ok(Self {
                 filename,
                 inner: Some(FileInner::Write(WriteState {
@@ -105,7 +117,7 @@ impl PyFile {
                 })),
             }),
             other => Err(PyValueError::new_err(format!(
-                "unsupported mode '{other}'; expected 'r' or 'w'"
+                "unsupported mode '{other}'; expected 'r', 'r+', 'a' or 'w'"
             ))),
         }
     }
@@ -226,7 +238,10 @@ impl PyFile {
             PyErr::new::<pyo3::exceptions::PyIOError, _>("file is already closed")
         })?;
         match inner {
-            FileInner::Read(_) => Ok(()),
+            FileInner::Read(root) => {
+                root.handle.close();
+                Ok(())
+            }
             FileInner::Write(state) => finalize_write(state),
         }
     }
@@ -289,6 +304,30 @@ impl PyFile {
         "/"
     }
 
+    /// `'r'` for a file opened read-only (a local file or a URL), `'r+'`
+    /// for one open for editing or writing, as h5py reports it.
+    #[getter]
+    fn mode(&self) -> PyResult<&'static str> {
+        match &self.inner {
+            Some(FileInner::Read(root)) if !root.handle.is_writable() => Ok("r"),
+            Some(_) => Ok("r+"),
+            None => Err(PyErr::new::<pyo3::exceptions::PyIOError, _>(
+                "file is closed",
+            )),
+        }
+    }
+
+    /// Nothing to do: every edit is written and synced when it is made, and
+    /// a file opened with 'w' is written on `close()`.
+    fn flush(&self) {}
+
+    /// Deleting objects is not supported (h5py's `del f[name]`).
+    fn __delitem__(&self, key: &str) -> PyResult<()> {
+        Err(PyNotImplementedError::new_err(format!(
+            "cannot delete '{key}': deleting objects is not supported by clawhdf5"
+        )))
+    }
+
     /// The path (or URL) the file was opened with.
     #[getter]
     fn filename(&self) -> &str {
@@ -389,6 +428,13 @@ impl PyFile {
     fn write_state_mut(&mut self) -> PyResult<&mut WriteState> {
         match &mut self.inner {
             Some(FileInner::Write(s)) => Ok(s),
+            Some(FileInner::Read(root)) if root.handle.is_writable() => {
+                Err(PyNotImplementedError::new_err(
+                    "creating datasets or groups in an existing file is not supported by \
+                     clawhdf5's in-place editor (mode 'r+' changes values, shapes and \
+                     attributes)",
+                ))
+            }
             Some(FileInner::Read(_)) => Err(PyErr::new::<pyo3::exceptions::PyIOError, _>(
                 "cannot write to a file opened for reading",
             )),