Answer what shape a file is, without reading it

[martin-s-a]

Item 3a of the backlog, and the half of the batch source work that carries no
threads and no GIL.

Sizing the destination of a batch read means knowing the shape of one image or
volume before allocating anything. rexlib gained query_extents and
query_core_extents in gigabit-clowns/rexlib#461; this binds them.

>>> image.query_extents(path)        # slowest axis first, the whole file
(120, 4096, 4096)
>>> image.query_core_extents(path)   # the axes it stacks along left out
(4096, 4096)

The second is the one that matters: its documentation upstream calls it "the
shape of a single image or volume, which is what the destination of a batch
carries beside its leading extent", so none of that arithmetic has to be
reproduced here.

Three choices worth naming

Extents come back as tuples, built explicitly rather than let through as
lists. A shape is a tuple everywhere else in this package after #153, and a
query that answered with a list would be the odd one out for no reason.

The wrapper takes the path first. C++ has query_extents(formats, path);
the Python layer is query_extents(path, manager=None). This is the first
place the second layer reorders arguments rather than only defaulting them,
and it is the point of the layer: leaving the manager first would force every
caller to fetch one, which is exactly what defaulting exists to avoid. The
binding underneath keeps the C++ order with both arguments required.

The overloads over a reader provider are not here. They take an
image_reader_provider&, and nothing binds a provider yet — that arrives with
3b, which binds the whole chain. Worth noting for then: those take a non-const
reference where the format manager ones take a const one, since a caching
provider mutates as it opens.

The submodule moves

external/rexlib goes from 741b262 to 43bbffec. Not incidental — the code
here now needs a rexlib that has these functions, and CI overriding the pin
with git submodule update --remote would hide that from anyone cloning and
building by the README.

Checked

• Compiles clean under g++ -std=c++20 -fsyntax-only -Wall -Wextra -Wpedantic
  against the updated submodule.
• ruff check . passes; 47 tests collect under tests/em/image/.
• The tests assert only what is verifiable without knowing a format's internals:
  that a written file reports the extents it was written with, that both
  answers are tuples, that the core is the tail of the whole whatever the rank,
  and that what comes back sizes a destination. The failure case is
  RuntimeError for the same reason as the neighbouring tests — a file no
  format claims reaches invalid_operation_error, which derives from
  std::logic_error.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud