Core

Core data structures and low-level utilities. (Configuration moved to Configuration.)

Grid system

GlobalGrid

Defines the standardized 3-arc-second (~90m) grid for Europe.

This class provides static methods to convert between geographic coordinates (Latitude/Longitude) and the internal pixel grid (Column/Row).

It aligns with the extent of the Flood Depth Maps dataset but uses the resolution of the EFAS Hazard Maps (1/1200 degrees).

Attributes:

Name	Type	Description
`ORIGIN_X`	`float`	Top-Left Longitude (-46.8).
`ORIGIN_Y`	`float`	Top-Left Latitude (85.1).
`RESOLUTION`	`float`	Grid cell size in degrees (1/1200.0).
`WIDTH_DEG`	`float`	Total width in degrees.
`HEIGHT_DEG`	`float`	Total height in degrees.
`WIDTH_PX`	`int`	Total width in pixels.
`HEIGHT_PX`	`int`	Total height in pixels.

Methods:

Name	Description
`latlon_to_grid`	Vectorized conversion of Lat/Lon arrays to Grid Col/Row indices.
`is_valid`	Return boolean mask of valid pixels inside the grid boundaries.

Methods:

latlon_to_grid `staticmethod`

latlon_to_grid(
    lats: NDArray[float64], lons: NDArray[float64]
) -> tuple[NDArray[int32], NDArray[int32]]

Vectorized conversion of Lat/Lon arrays to Grid Col/Row indices.

Uses the formula

col = (lon - origin_x) / resolution row = (origin_y - lat) / resolution

Parameters:

Name	Type	Description	Default
`lats`	`NDArray[float64]`	1D Array of latitude values.	required
`lons`	`NDArray[float64]`	1D Array of longitude values.	required

Returns:

Type	Description
`tuple[NDArray[int32], NDArray[int32]]`	Tuple[npt.NDArray[np.int32], npt.NDArray[np.int32]]: A tuple containing: - cols: Array of column indices (int32). - rows: Array of row indices (int32).

is_valid `staticmethod`

is_valid(
    cols: NDArray[int32], rows: NDArray[int32]
) -> NDArray[bool_]

Return boolean mask of valid pixels inside the grid boundaries.

Checks if the provided column and row indices fall within the [0, WIDTH_PX) and [0, HEIGHT_PX) ranges respectively.

Parameters:

Name	Type	Description	Default
`cols`	`NDArray[int32]`	Array of column indices.	required
`rows`	`NDArray[int32]`	Array of row indices.	required

Returns:

Type	Description
`NDArray[bool_]`	npt.NDArray[np.bool_]: Boolean array where True indicates the pixel is within bounds.

Manifest

manifest

Cache manifest: version + grid fingerprint to detect incompatible caches.

The export pipeline writes a manifest.json next to the index that records the cache schema version, the dictionary schema version, and a fingerprint of the GlobalGrid used to build it. Consumers validate it before trusting the index, so a cache produced by older/incompatible code (e.g. before the grid-rounding or dtype fixes) is rejected with a clear message rather than silently producing wrong results.

Functions:

Name	Description
`grid_fingerprint`	Return the identifying parameters of the current GlobalGrid.
`build_manifest`	Build the manifest document describing the current cache.
`write_manifest`	Write the cache manifest to `path`.
`validate_manifest`	Raise `CacheSchemaError` if the cache is missing or incompatible.
`file_record`	Return `{size_bytes, sha256}` for a file (integrity record).
`file_records`	Map `{relative_name: path}` to per-file integrity records (skips missing).
`build_publish_manifest`	Build the publish manifest: the contract 5b deploys and consumers validate.
`write_publish_manifest`	Write the publish manifest (see `build_publish_manifest`).
`stamp_manifest`	Rewrite an existing manifest's `index_version` / `source_urls` in place.
`validate_publish_manifest`	Validate a publish manifest: cache gate + index schema + optional checksums.

Classes

Functions:

grid_fingerprint

grid_fingerprint() -> dict[str, Any]

Return the identifying parameters of the current GlobalGrid.

build_manifest

build_manifest() -> dict[str, Any]

Build the manifest document describing the current cache.

write_manifest

write_manifest(path: Path) -> None

Write the cache manifest to path.

validate_manifest

validate_manifest(path: Path) -> None

Raise CacheSchemaError if the cache is missing or incompatible.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Path to the cache `manifest.json`.	required

Raises:

Type	Description
`CacheSchemaError`	If the manifest is absent, its schema version differs, or its grid fingerprint no longer matches the running code.

file_record

file_record(path: Path) -> dict[str, Any]

Return {size_bytes, sha256} for a file (integrity record).

file_records

file_records(
    files: dict[str, Path],
) -> dict[str, dict[str, Any]]

Map {relative_name: path} to per-file integrity records (skips missing).

build_publish_manifest

build_publish_manifest(
    *,
    index_version: str,
    files: dict[str, Path],
    provenance: dict[str, Any] | None = None,
    cog: dict[str, Any] | None = None,
    source_urls: dict[str, Any] | None = None,
    published_at: str | None = None,
    git_commit: str | None = None
) -> dict[str, Any]

Build the publish manifest: the contract 5b deploys and consumers validate.

Extends the cache manifest (schema versions + grid fingerprint, so an incompatible grid is still rejected) with the publishing metadata: an index_version, provenance, a COG attestation, per-file checksums/sizes, and templated source_urls (filled by Phase 5b).

write_publish_manifest

write_publish_manifest(path: Path, **kwargs: Any) -> None

Write the publish manifest (see build_publish_manifest).

stamp_manifest

stamp_manifest(
    path: Path,
    *,
    index_version: str | None = None,
    source_urls: dict[str, Any] | None = None
) -> dict[str, Any]

Rewrite an existing manifest's index_version / source_urls in place.

The published URLs and DOI are only known after upload, so the publish step builds the bundle with placeholder source_urls (null) and calls this to stamp the real values into manifest.json before re-uploading it. Only the given fields are touched; checksums, provenance, and the grid fingerprint are preserved.

Returns the updated manifest document.

validate_publish_manifest

validate_publish_manifest(
    path: Path,
    *,
    base_dir: Path | None = None,
    verify_checksums: bool = False
) -> None

Validate a publish manifest: cache gate + index schema + optional checksums.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Path to the manifest JSON.	required
`base_dir`	`Path \| None`	Directory the manifest's `files` are relative to (defaults to the manifest's own directory).	`None`
`verify_checksums`	`bool`	If True, re-hash each listed file and compare.	`False`

Raises:

Type	Description
`CacheSchemaError`	On a missing/incompatible manifest, an index-schema mismatch, a missing file, or a checksum mismatch.

Data schemas

FloodRecord

Bases: BaseModel

Represents a single flood event file found on the remote server.

Exceptions

exceptions

The EuroFlood exception hierarchy.

All library errors derive from EuroFloodError, so callers can catch the whole family with one except. The CLI maps each subclass to a distinct exit code and renders it as a clean one-line message (see the Output & Logging guide); library/notebook users get the exception object with an actionable message.

Classes:

Name	Description
`EuroFloodError`	Base exception for all EuroFlood errors.
`ConfigurationError`	Raised when configuration or paths are invalid.
`NetworkError`	Raised when remote resources cannot be accessed after retries.
`ScrapingError`	Raised when parsing the JRC website fails.
`ProcessingError`	Raised when processing a raster fails.
`GeocodingError`	Raised when a place name cannot be resolved.
`CacheSchemaError`	Raised when the on-disk cache is missing or incompatible with the code.
`HazardError`	Raised when GLOFAS hazard tiles can't be located, fetched, or mosaicked.
`PublishError`	Raised when publishing the index bundle to a remote host fails.
`SourceCoopError`	Raised when uploading the index bundle to Source Cooperative fails.
`VerificationError`	Raised when a published index fails end-to-end verification.
`VisualizationError`	Raised when a catalogue/raster cannot be visualized (e.g. empty, unsupported).

Classes

EuroFloodError

Bases: Exception

Base exception for all EuroFlood errors.

ConfigurationError

Bases: EuroFloodError

Raised when configuration or paths are invalid.

NetworkError

Bases: EuroFloodError

Raised when remote resources cannot be accessed after retries.

ScrapingError

Bases: NetworkError

Raised when parsing the JRC website fails.

ProcessingError

Bases: EuroFloodError

Raised when processing a raster fails.

GeocodingError

Bases: EuroFloodError

Raised when a place name cannot be resolved.

CacheSchemaError

Bases: EuroFloodError

Raised when the on-disk cache is missing or incompatible with the code.

HazardError

Bases: EuroFloodError

Raised when GLOFAS hazard tiles can't be located, fetched, or mosaicked.

PublishError

Bases: EuroFloodError

Raised when publishing the index bundle to a remote host fails.

SourceCoopError

Bases: PublishError

Raised when uploading the index bundle to Source Cooperative fails.

VerificationError

Bases: EuroFloodError

Raised when a published index fails end-to-end verification.

VisualizationError

Bases: EuroFloodError

Raised when a catalogue/raster cannot be visualized (e.g. empty, unsupported).

Core

Grid system

GlobalGrid

Methods:

latlon_to_grid staticmethod

is_valid staticmethod

Manifest

manifest

Classes

Functions:

grid_fingerprint

build_manifest

write_manifest

validate_manifest

file_record

file_records

build_publish_manifest

write_publish_manifest

stamp_manifest

validate_publish_manifest

Data schemas

FloodRecord

Exceptions

exceptions

Classes

EuroFloodError

ConfigurationError

NetworkError

ScrapingError

ProcessingError

GeocodingError

CacheSchemaError

HazardError

PublishError

SourceCoopError

VerificationError

VisualizationError

latlon_to_grid `staticmethod`

is_valid `staticmethod`