Protocols and public contracts#

HydroModPy V1 makes its public surface explicit through three layers:

  • the public facade hydromodpy (re-exports open, read, run, calibrate, index, viz, ml stubs);

  • a small set of Protocols that pin the structural contract for storage backends and field readers;

  • a field registry that maps logical names to physical readers.

This page documents what users and integrators can rely on.

The hmp public facade#

The single supported import path is import hydromodpy as hmp. The package exposes a flat set of verbs and helpers re-exported from hydromodpy._api:

Symbol

Role

hmp.open(project_path)

Open a project catalog. Returns a SimulationCatalog backed by catalog.duckdb at the project root. Calls ensure_schema() on the underlying backend.

hmp.read(run, field, **selectors)

Read a logical field from a Run. Dispatches to a Zarr reader or a Parquet reader through the field registry.

hmp.run(toml_path, **overrides)

Execute a workflow declared in the project TOML.

hmp.calibrate(toml_path, **overrides)

Drive a calibration session.

hmp.index(db_path=None)

Open the machine-wide GlobalIndex.

hmp.viz.show(run, figure, **kwargs)

Render one figure for a run. Scalable defaults via datashader / LTTB.

Storage Protocol: CatalogBackend#

Source: hydromodpy/results/catalog/ports.py.

The catalog facade interacts with the SQL store only through this Protocol. The in-tree adapter is DuckDBBackend.

Required surface:

class CatalogBackend(Protocol):
    def ensure_schema(self) -> None: ...
    def query(self, sql: str, params: ...) -> pandas.DataFrame: ...
    def execute(self, sql: str, params: ...) -> None: ...
    def fetch_one(self, sql: str, params: ...) -> tuple | None: ...
    def fetch_all(self, sql: str, params: ...) -> list[tuple]: ...
    def insert(self, table: str, row: dict[str, Any]) -> None: ...
    # ... plus transaction context manager and close()

Conformance is structural (@runtime_checkable). No base class to inherit. ensure_schema() runs the Alembic-like migration runner so the catalog is always at the version pinned by the library.

Simulation store Protocol#

Source: hydromodpy/results/storage_contract.py (SimulationStore Protocol).

Covers the minimal write/read surface that workflow steps, solver adapters, and post-run extractors actually call:

  • registration: register_simulation;

  • per-simulation writes: write_parameters, write_timeseries, write_field, write_time, write_crs, write_mesh, write_provenance, write_metric, write_run_environment, register_tracked_files;

  • reads: query_timeseries, list_simulations, __getitem__, open_zarr;

  • lifecycle: finalize, close and the context-manager protocol.

The default implementation is SimulationCatalog. Conforming alternative backends (PostgreSQL, Parquet-only, in-memory, remote object storage) can plug in without touching workflow code.

Field registry#

Source: hydromodpy/results/field_registry.py.

Maps a logical field name ("head", "watertable_depth", "accumulation_flux", …) to:

  • the physical store kind ("zarr" or "parquet");

  • the canonical path inside that store (field/head, timeseries.parquet?variable=head);

  • the CF standard_name and the unit.

hmp.read reads the registry first and dispatches to the matching reader. Adding a new field is a registry entry plus a writer; readers keep working unchanged.

Versioned schema constants#

Constant

Definition

schema_migrations.version (project catalog)

one row per applied migration; latest is the active version.

schema_migrations.version (workspace cache)

separate ledger row scoped to the cache component.

schema_migrations.version (machine index)

separate ledger row scoped to the index component.

ZARR_SCHEMA_VERSION

Pinned to "2" in hydromodpy/results/zarr_store/constants.py.

PARQUET_SCHEMA_VERSION

Pinned to "v2" in hydromodpy/results/parquet_schemas.py.

GEOPARQUET_SCHEMA_VERSION

Pinned to "1.1.0" in hydromodpy/results/geoparquet_io.py.

For the migration runner mechanics, see Schema Evolution.

Stability promise#

The public facade hmp.* and the two Protocols above are the V1 stable surface. Backwards-compatibility shims, aliases, and re-exports outside the facade are forbidden (see CLAUDE.md under “What this codebase forbids”).

A change to any of the four areas above is a breaking change that requires:

  • a migration entry under the relevant hydromodpy/.../migrations/ directory;

  • a version bump of the matching constant (ZARR_SCHEMA_VERSION, PARQUET_SCHEMA_VERSION, GEOPARQUET_SCHEMA_VERSION);

  • a docs update on this page and on Storage Layout.

See also#

On this page