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 writebundle.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.HydrologyBundleManifestVersioned 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:
objectValidation 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
- warnings: tuple[str, ...]
- class femic.hydrology.bundle.HydrologyBundleBuildResult(bundle_dir, manifest_path, manifest)[source]
Bases:
objectPaths and manifest returned by a successful bundle build.
- Parameters:
bundle_dir (Path)
manifest_path (Path)
manifest (HydrologyBundleManifest)
- bundle_dir: Path
- manifest: HydrologyBundleManifest
- manifest_path: Path
- exception femic.hydrology.bundle.HydrologyBundleError[source]
Bases:
RuntimeErrorRaised when a hydrology bundle plan, build, or manifest is invalid.
- class femic.hydrology.bundle.HydrologyBundleGap(layer_id, role, reason)[source]
Bases:
objectOne missing or unresolved bundle layer.
- Parameters:
layer_id (str)
role (str)
reason (str)
- layer_id: str
- reason: str
- role: str
- 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:
objectOne 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
- class femic.hydrology.bundle.HydrologyBundleLayerAudit(layer_id, role, relative_path, status, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]
Bases:
objectLocal 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
- 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:
objectVersioned 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'
- 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:
- 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.jsonat 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:
- femic.hydrology.bundle.load_hydrology_bundle_manifest(path)[source]
Load a hydrology bundle manifest from JSON.
- Parameters:
path (Path)
- Return type:
- 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.
sourcesmaps 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:
- 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:
manifest (HydrologyBundleManifest)
path (Path)
- Return type:
Path