py: remote files (clawhdf5.File(url), File.open_url) through File::storage()

The Python bindings could not open a remote file: they parsed through
File::as_bytes() in eight places (path lookups, object headers,
dataspaces, attributes, group listings, the global heap of
variable-length data), which a storage-backed file does not have.

- Every object of a File now shares one handle (src/handle.rs) that
  runs all file access, metadata included, with the GIL released and
  parses through File::storage() and the clawhdf5_format *_in functions.
  Local files take the same path (their storage is the mmap).
- clawhdf5.File(url) opens any scheme://... through
  clawhdf5_remote::storage_for_url (read-only; another mode is a
  ValueError). File.open_url(url, **options) takes the cache and HTTP
  options (block_size, cache_size, headers, retries, timeout,
  allow_full_download, max_full_download, require_validator,
  max_redirects, max_parallel); File.remote_stats gives the block
  cache's counters.
- Default build: plain HTTP only, no C. https (rustls/ring) and
  s3/gcs/azure (aws-lc-rs) are opt-in features of clawhdf5-py, and
  ci-test.sh's no-C check now covers the crate.
- A failed storage read (network error, file changed on the server) is an
  OSError, never KeyError/ValueError and never data; `key in group`
  raises it instead of answering False.

Tests: the read-vs-h5py suite runs locally and over HTTP (1 MiB and
1 KiB blocks) against a range-capable http.server in the test process
(conftest.RangeServer); test_remote.py covers request counts, cache
hits, a server without Range support, a changed file, a server that
hangs up, 16 threads, and a spinning thread that keeps running while a
read waits on 0.2 s requests.

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

docs/design/range-reads.md

@@ -7,8 +7,9 @@ change. Progress: M0 and M1 are done, and so is M2 (branch
 `File::open_storage` gives the facade's read API over any `Storage` (see
 `CHANGELOG.md`, "Range reads, milestone M2"). M3 is done on branch
 `feat/p3-m3-remote`: the `clawhdf5-remote` crate (block cache, HTTP(S),
-object stores) and URLs in `h5rs` (see the M3 status below). M4 (wasm) is
-next. Every count in §1–§2 was
+object stores) and URLs in `h5rs` (see the M3 status below); the Python
+bindings followed on branch `feat/p3-python-remote-edit` (2026-09-27),
+which completes M3. M4 (wasm) is next. Every count in §1–§2 was
 
 change. Progress: M1, first part (the `Storage` trait and the metadata
 parsers listed in `CHANGELOG.md` under "Range reads, milestone M1") is done;
@@ -475,7 +476,7 @@ fast path within benchmark noise.
   a request counter exposed for tests and users.
 - Python bindings: `clawhdf5.File("s3://…")` / `https://` through it.
 - *Status 2026-09-26:* done on branch `feat/p3-m3-remote`, except the
-  Python bindings, with these choices:
+  Python bindings (done 2026-09-27, below), with these choices:
   - A new crate, `clawhdf5-remote`, instead of a `remote` feature of
     `clawhdf5-io`: `open_url` returns a `clawhdf5::File`, and `clawhdf5-io`
     sits below the facade.
@@ -512,6 +513,17 @@ fast path within benchmark noise.
     same work without a cache: 141 936 requests. Per file: A lists in 2
     requests (§2 predicted 2 blocks of 1 MiB), B in 1, C in 7 (its whole
     6.4 MB: 35 001 object headers spread over the file).
+- *Status 2026-09-27, Python bindings:* done on branch
+  `feat/p3-python-remote-edit`. `clawhdf5.File(url)` and
+  `File.open_url(url, **options)` (cache and HTTP options) go through
+  `clawhdf5_remote::storage_for_url`; the default wheel is plain HTTP (no
+  C), `https`/`s3`/`gcs`/`azure` are build features. The bindings' own
+  parsing (path lookups, headers, attributes, listings, the global heap)
+  moved from `File::as_bytes` to `File::storage()` and the `*_in`
+  functions, and every file access, metadata included, runs with the GIL
+  released. Checked by running the whole read-vs-h5py suite over an
+  in-process range server (1 MiB and 1 KiB blocks) and by request counts
+  in `crates/clawhdf5-py/tests/test_remote.py`.
 
 **M4 — wasm lazy loading (1–2 weeks).**
 - `clawhdf5-wasm`: `openUrl(url) -> Promise<H5File>` backed by `fetch` with a

docs/known-issues.md

@@ -844,9 +844,9 @@ cache, but:
   `read_*_zerocopy`) need the file in memory and answer
   `FormatError::ContiguousStorageRequired` otherwise; `File::as_bytes()`
   panics for such a file (`File::contiguous_bytes()` is the fallible form).
-  `LazyFile`, `MmapFile` and the Python and wasm bindings still read a
-  whole file (`h5rs` reads through `File::storage`, and takes URLs with its
-  `remote` feature).
+  `LazyFile`, `MmapFile` and the wasm bindings still read a whole file
+  (`h5rs` and the Python bindings read through `File::storage`, and take
+  URLs: `h5rs` with its `remote` feature, Python with `clawhdf5.File(url)`).
 - The file's length is read once, at open: a growing file (SWMR) is not
   followed (milestone M5). A remote file is pinned at open, so one that
   grows is `RemoteError::FileChanged`.
@@ -862,9 +862,12 @@ cache, but:
 **Status:** open (added 2026-09-26, milestone M3 of
 `docs/design/range-reads.md`).
 
-- **Python and the browser cannot open URLs yet.** `clawhdf5.File` (PyO3)
-  parses through `File::as_bytes`, which a remote file does not have; the
-  wasm reader's `openUrl` is milestone M4.
+- **The browser cannot open URLs yet**: the wasm reader's `openUrl` is
+  milestone M4. Python can (`clawhdf5.File(url)`, since 2026-09-27), but
+  the default wheel reads plain `http://` only: `https://` needs a wheel
+  built with `--features https` (rustls with ring, which compiles C), and
+  `s3://`, `gs://`, `az://` the `s3`, `gcs`, `azure` features (aws-lc-rs).
+  The Python tests run against an in-process `http.server` only.
 - **The block size is fixed** (1 MiB unless `CacheConfig` says otherwise).
   The design's policy of using a paged file's page size as the block size
   is not implemented, and only the first block is read ahead.