femic.hydrology.bundle Module

The femic.hydrology.bundle module packages a reviewed hydrology domain into a portable, versioned data bundle. It plans layers, reports gaps, copies local sources, records licences and checksums, and audits bundle completeness. It does not download public layers or run a hydrology model.

Use this page when you are assembling or auditing the public data bundle for forest hydrology and flood-risk work.

Start Here If…

Use this page first if you are trying to:

  • audit which domain layers are still missing before a build;

  • package local BCDC/WFS/DataLad layers into a reproducible bundle;

  • verify layer sizes and SHA-256 values;

  • inspect bundle completeness and gaps; or

  • hand a pinned hydrology data bundle to later P114 work.

Typical Usage

from pathlib import Path
from femic.hydrology.bundle import (
    audit_hydrology_bundle,
    build_hydrology_bundle,
    plan_hydrology_bundle,
)

plan = plan_hydrology_bundle(
    domain,
    bundle_dir=Path("data/hydrology/bundle-v1"),
    aoi_bbox_epsg3005=(1148000, 391900, 1149900, 393500),
    sources={"watersheds": Path("data/raw/watersheds.gpkg")},
)
result = build_hydrology_bundle(
    Path("metadata/hydrology/domain.json"),
    Path("data/hydrology/bundle-v1"),
    aoi_bbox_epsg3005=(1148000, 391900, 1149900, 393500),
    sources=sources,
)
audit = audit_hydrology_bundle(result.bundle_dir)

Key Entry Surfaces

  • plan_hydrology_bundle() Plan layer paths and report missing sources.

  • build_hydrology_bundle() Atomically copy sources and write bundle.json.

  • audit_hydrology_bundle() Validate the manifest and audit materialized layer files.

  • validate_hydrology_bundle_manifest() Check the structural bundle contract.

  • load_hydrology_bundle_manifest() Load a bundle manifest.

  • write_hydrology_bundle_manifest() Persist a bundle manifest.

  • HydrologyBundleManifest Versioned bundle contract with layers, gaps, checksums, and provenance.

Cross-References

Versioned public hydrology data bundles.

P114.2 packages an already-reviewed hydrology domain into a portable bundle. It does not download public layers itself; callers provide local source paths from BCDC, WFS, DataLad, or a reviewed project mirror.

class femic.hydrology.bundle.HydrologyBundleAudit(bundle_id, bundle_dir, manifest_path, is_valid, is_complete, checked_utc, layers, errors, warnings)[source]

Bases: object

Validation and local-file audit for one hydrology bundle.

Parameters:
  • bundle_id (str)

  • bundle_dir (Path)

  • manifest_path (Path)

  • is_valid (bool)

  • is_complete (bool)

  • checked_utc (str)

  • layers (tuple[HydrologyBundleLayerAudit, ...])

  • errors (tuple[str, ...])

  • warnings (tuple[str, ...])

bundle_dir: Path
bundle_id: str
checked_utc: str
errors: tuple[str, ...]
is_complete: bool
is_valid: bool
layers: tuple[HydrologyBundleLayerAudit, ...]
manifest_path: Path
to_dict()[source]

Return the audit as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...]
class femic.hydrology.bundle.HydrologyBundleBuildResult(bundle_dir, manifest_path, manifest)[source]

Bases: object

Paths and manifest returned by a successful bundle build.

Parameters:
bundle_dir: Path
manifest: HydrologyBundleManifest
manifest_path: Path
to_dict()[source]

Return the build result as a JSON-serializable mapping.

Return type:

dict[str, object]

exception femic.hydrology.bundle.HydrologyBundleError[source]

Bases: RuntimeError

Raised when a hydrology bundle plan, build, or manifest is invalid.

class femic.hydrology.bundle.HydrologyBundleGap(layer_id, role, reason)[source]

Bases: object

One missing or unresolved bundle layer.

Parameters:
  • layer_id (str)

  • role (str)

  • reason (str)

layer_id: str
reason: str
role: str
to_dict()[source]

Return the gap as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.bundle.HydrologyBundleLayer(layer_id, role, source_id, relative_path, format, crs, licence_id, status, checksum_sha256=None, size_bytes=None, source_url=None, retrieval_utc=None, notes='')[source]

Bases: object

One layer record in a hydrology data bundle.

Parameters:
  • layer_id (str)

  • role (str)

  • source_id (str | None)

  • relative_path (str)

  • format (str)

  • crs (str)

  • licence_id (str)

  • status (str)

  • checksum_sha256 (str | None)

  • size_bytes (int | None)

  • source_url (str | None)

  • retrieval_utc (str | None)

  • notes (str)

checksum_sha256: str | None = None
crs: str
format: str
layer_id: str
licence_id: str
notes: str = ''
relative_path: str
retrieval_utc: str | None = None
role: str
size_bytes: int | None = None
source_id: str | None
source_url: str | None = None
status: str
to_dict()[source]

Return the layer record as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.bundle.HydrologyBundleLayerAudit(layer_id, role, relative_path, status, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]

Bases: object

Local file audit for one bundle layer.

Parameters:
  • layer_id (str)

  • role (str)

  • relative_path (str)

  • status (str)

  • exists (bool)

  • size_bytes (int | None)

  • expected_size_bytes (int | None)

  • checksum_ok (bool | None)

  • issues (tuple[str, ...])

checksum_ok: bool | None
exists: bool
expected_size_bytes: int | None
issues: tuple[str, ...] = ()
layer_id: str
relative_path: str
role: str
size_bytes: int | None
status: str
to_dict()[source]

Return the layer audit as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.bundle.HydrologyBundleManifest(bundle_id, bundle_version, generated_utc, domain_id, domain_sha256, aoi_bbox_epsg3005, layers, gaps=(), caveats=(), provenance=<factory>, schema_version='femic.hydrology.bundle.v1')[source]

Bases: object

Versioned public hydrology data bundle manifest.

Parameters:
  • bundle_id (str)

  • bundle_version (str)

  • generated_utc (str)

  • domain_id (str)

  • domain_sha256 (str)

  • aoi_bbox_epsg3005 (tuple[float, float, float, float])

  • layers (tuple[HydrologyBundleLayer, ...])

  • gaps (tuple[HydrologyBundleGap, ...])

  • caveats (tuple[str, ...])

  • provenance (dict[str, object])

  • schema_version (str)

aoi_bbox_epsg3005: tuple[float, float, float, float]
bundle_id: str
bundle_version: str
caveats: tuple[str, ...] = ()
domain_id: str
domain_sha256: str
gaps: tuple[HydrologyBundleGap, ...] = ()
generated_utc: str
property is_complete: bool

Return whether every layer is materialized and no gaps remain.

property layer_count: int

Return the number of layer records.

layers: tuple[HydrologyBundleLayer, ...]
property materialized_count: int

Return the number of materialized layers.

provenance: dict[str, object]
schema_version: str = 'femic.hydrology.bundle.v1'
to_dict()[source]

Return the bundle manifest as a JSON-serializable mapping.

Return type:

dict[str, object]

femic.hydrology.bundle.audit_hydrology_bundle(path, *, data_root=None, checked_utc=None)[source]

Validate a bundle manifest and audit its local layer files.

Parameters:
  • path (Path)

  • data_root (Path | None)

  • checked_utc (str | None)

Return type:

HydrologyBundleAudit

femic.hydrology.bundle.build_hydrology_bundle(domain_manifest_path, bundle_dir, *, aoi_bbox_epsg3005, sources, bundle_version='0.1.0', generated_utc=None, overwrite=False)[source]

Copy local source layers into a versioned hydrology bundle.

All domain layers must have a local source file. The build is atomic and writes bundle.json at the bundle root.

Parameters:
  • domain_manifest_path (Path)

  • bundle_dir (Path)

  • aoi_bbox_epsg3005 (Sequence[object])

  • sources (Mapping[str, Path])

  • bundle_version (str)

  • generated_utc (str | None)

  • overwrite (bool)

Return type:

HydrologyBundleBuildResult

femic.hydrology.bundle.load_hydrology_bundle_manifest(path)[source]

Load a hydrology bundle manifest from JSON.

Parameters:

path (Path)

Return type:

HydrologyBundleManifest

femic.hydrology.bundle.plan_hydrology_bundle(domain, *, bundle_dir, aoi_bbox_epsg3005, sources=None, bundle_version='0.1.0', generated_utc=None)[source]

Plan a hydrology bundle and report missing source layers.

sources maps domain layer IDs to local files. Planning never copies files; it records planned paths, checksums, sizes, and gaps.

Parameters:
  • domain (HydrologyDomainManifest)

  • bundle_dir (Path)

  • aoi_bbox_epsg3005 (Sequence[object])

  • sources (Mapping[str, Path] | None)

  • bundle_version (str)

  • generated_utc (str | None)

Return type:

HydrologyBundleManifest

femic.hydrology.bundle.validate_hydrology_bundle_manifest(manifest)[source]

Validate the structural contract of a hydrology bundle manifest.

Parameters:

manifest (HydrologyBundleManifest)

Return type:

tuple[str, …]

femic.hydrology.bundle.write_hydrology_bundle_manifest(manifest, path)[source]

Write a hydrology bundle manifest as pretty-printed JSON.

Parameters:
Return type:

Path