HDF5 2.0 native complex as a first-class type on read; Python libver=

- Datatype::parse returns Datatype::Complex for class 11 (also inside
  compounds, arrays and VL types) instead of the {r, i} compound view.
- Facade: DType::Complex(Box<DType>); read_complex_f32/f64 accept it.
- h5rs dump/ls/diff print native complex as h5dump/h5ls/h5diff 2.2.0 do
  (checked against a fixture written by h5py 3.16 / libhdf5 2.0.0);
  dump --json keeps the {r, i} compound (hdf5-json has no complex class).
- clawhdf5-wasm reads native complex datasets as [re, im] pairs.
- Python: clawhdf5.File(path, 'w', libver=...) with h5py's values,
  mapped to FileBuilder::libver_bounds; 'v108' output opens in HDF5 1.8.23.
- Docs: known-issues entry moved to Fixed (history), CHANGELOG, READMEs.

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

crates/clawhdf5-py/src/file.rs

@@ -13,10 +13,13 @@ use crate::attrs::PyAttrs;
 use crate::group::{PyGroup, ReadGroup, WriteGroupState, finalize_write_group};
 use crate::handle::Handle;
 use crate::{DatasetSpec, OwnedAttrValue, apply_dataset_spec, extract_numpy_data, to_py_err};
+use clawhdf5_rs::LibVer;
 
 /// Internal state for write mode.
 struct WriteState {
     path: PathBuf,
+    /// `libver=` as (low, high); `None` keeps the writer's default.
+    libver: Option<(LibVer, LibVer)>,
     root_datasets: Vec<DatasetSpec>,
     root_attrs: Arc<Mutex<Vec<(String, OwnedAttrValue)>>>,
     groups: Vec<Arc<Mutex<WriteGroupState>>>,
@@ -80,10 +83,32 @@ impl PyFile {
     ///     `az://`; which schemes work depends on how the wheel was built)
     ///     to read the file remotely with default options (see `open_url`)
     ///   mode: 'r' for read (default), 'w' for write
+    ///   libver: library version bounds for mode 'w', as h5py's: one of
+    ///     'earliest', 'v108', 'v110', 'v112', 'v114', 'v200', 'latest' (the
+    ///     low bound; the high bound is then 'latest') or a (low, high)
+    ///     tuple of them. The low bound is the oldest HDF5 release whose
+    ///     format the file uses ('v108': HDF5 1.8 can read it); the high
+    ///     bound the newest whose features it may use. clawhdf5 cannot write
+    ///     the pre-1.8 format, so a low bound of 'earliest' writes the 1.8
+    ///     format (with a warning) and a high bound of 'earliest' is an
+    ///     error. Default (None): the HDF5 1.10 format clawhdf5 has always
+    ///     written. Ignored for reading; not supported with 'r+' / 'a'.
     #[new]
-    #[pyo3(signature = (path, mode="r"))]
-    fn new(py: Python<'_>, path: &str, mode: &str) -> PyResult<Self> {
+    #[pyo3(signature = (path, mode="r", libver=None))]
+    fn new(
+        py: Python<'_>,
+        path: &str,
+        mode: &str,
+        libver: Option<&Bound<'_, PyAny>>,
+    ) -> PyResult<Self> {
         let filename = path.to_string();
+        let libver = libver.map(|v| parse_libver(py, v)).transpose()?;
+        if libver.is_some() && matches!(mode, "r+" | "a") {
+            return Err(PyNotImplementedError::new_err(format!(
+                "libver with mode '{mode}': clawhdf5's in-place editor keeps the format \
+                 versions the file already uses"
+            )));
+        }
         if is_url(path) {
             if mode != "r" {
                 return Err(PyValueError::new_err(format!(
@@ -113,6 +138,7 @@ impl PyFile {
                     // Absolute now: the file is written at close, possibly
                     // after the working directory changed.
                     path: std::path::absolute(path).unwrap_or_else(|_| PathBuf::from(path)),
+                    libver,
                     root_datasets: Vec::new(),
                     root_attrs: Arc::new(Mutex::new(Vec::new())),
                     groups: Vec::new(),
@@ -460,10 +486,71 @@ fn parse_compression(
     }
 }
 
+/// One of h5py's `libver` names as a bound; `high` says which end it is.
+/// `Ok(None)` is 'earliest' as the low bound: the pre-1.8 format, which
+/// clawhdf5 cannot write.
+fn libver_name(name: &str, high: bool) -> PyResult<Option<LibVer>> {
+    Ok(Some(match name {
+        "earliest" if high => {
+            return Err(PyValueError::new_err(
+                "libver high bound 'earliest' (the pre-1.8 format) cannot be written by \
+                 clawhdf5; the oldest format it writes is 'v108'",
+            ));
+        }
+        "earliest" => return Ok(None),
+        "v108" => LibVer::V18,
+        "v110" => LibVer::V110,
+        "v112" => LibVer::V112,
+        "v114" => LibVer::V114,
+        "v200" => LibVer::V200,
+        "latest" => LibVer::Latest,
+        other => {
+            return Err(PyValueError::new_err(format!(
+                "unknown libver '{other}'; expected 'earliest', 'v108', 'v110', 'v112', \
+                 'v114', 'v200' or 'latest'"
+            )));
+        }
+    }))
+}
+
+/// h5py's `libver=`: a name (the low bound, high bound 'latest') or a
+/// `(low, high)` pair.
+fn parse_libver(py: Python<'_>, v: &Bound<'_, PyAny>) -> PyResult<(LibVer, LibVer)> {
+    let (low, high): (String, String) = match v.extract::<String>() {
+        Ok(name) => (name, "latest".into()),
+        Err(_) => v.extract().map_err(|_| {
+            PyValueError::new_err("libver must be a string or a (low, high) tuple of strings")
+        })?,
+    };
+    let Some(high) = libver_name(&high, true)? else {
+        unreachable!("a high bound is never None")
+    };
+    let low = match libver_name(&low, false)? {
+        Some(low) => low,
+        None => {
+            PyModule::import(py, "warnings")?.getattr("warn")?.call1((
+                "libver 'earliest': clawhdf5 cannot write the pre-1.8 format; the file \
+                 is written in the HDF5 1.8 format ('v108') instead",
+                py.get_type::<pyo3::exceptions::PyUserWarning>(),
+            ))?;
+            LibVer::V18
+        }
+    };
+    if low > high {
+        return Err(PyValueError::new_err(format!(
+            "libver low bound {low} is newer than the high bound {high}"
+        )));
+    }
+    Ok((low, high))
+}
+
 /// Build and write the HDF5 file from accumulated write state.
 fn finalize_write(state: WriteState) -> PyResult<()> {
     crate::no_panic(|| {
         let mut builder = clawhdf5_rs::FileBuilder::new();
+        if let Some((low, high)) = state.libver {
+            builder.libver_bounds(low, high);
+        }
 
         // Root attributes
         let root_attrs = state.root_attrs.lock().unwrap_or_else(|e| e.into_inner());
@@ -520,6 +607,7 @@ mod tests {
 
         let state = WriteState {
             path: path.clone(),
+            libver: None,
             root_datasets: vec![DatasetSpec {
                 name: "data".into(),
                 data: crate::DatasetData::F64(vec![1.0, 2.0, 3.0]),