femic.bcdc_catalog Module

The femic.bcdc_catalog module owns FEMIC’s first BC Data Catalogue resolver slice. It translates explicit layer names or keywords into ranked catalogue package matches, classifies the discovered resource surfaces, and can optionally download only the stable direct-access data resources from the top-ranked package. It also exposes the WFS/OpenMaps service hints that the separate femic.bcdc_fetch module uses for AOI-scoped acquisition.

Use this page when you are debugging the BCDC resolution logic itself rather than the higher-level CLI surface.

Start Here If…

Use this page first if you are trying to:

  • understand how FEMIC queries the public BC Data Catalogue API;

  • inspect the exact-vs-keyword fallback lookup logic;

  • debug why a resource was classified as direct download, service, indirect custom download, or supporting document; or

  • inspect how the v1 direct-download helper chooses what to save; or

  • inspect the WFS/OpenMaps service hints FEMIC now derives for later AOI-scoped fetch automation.

Typical Usage

The common operator-facing entrypoint is:

femic data bcdc-resolve WHSE_FOREST_VEGETATION.F_OWN

The matching Python entrypoints are:

from pathlib import Path
from femic.bcdc_catalog import (
    download_direct_bcdc_resources,
    resolve_bcdc_candidates,
    write_bcdc_manifest,
)

result = resolve_bcdc_candidates("WHSE_FOREST_VEGETATION.F_OWN")
download_direct_bcdc_resources(result, destination_root=Path("downloads/bcdc"))
write_bcdc_manifest(result, Path("runtime/logs/f_own_manifest.json"))

Key Entry Surfaces

  • resolve_bcdc_candidates() Query the public catalogue, probe service-backed resources, and build a normalized ranked result.

  • download_direct_bcdc_resources() Download only direct-access data resources from the chosen top match.

  • write_bcdc_manifest() Persist the resolve/download result as JSON for later promotion/review, including any WFS service hints.

Cross-References

BC Data Catalogue lookup and direct-download helpers.

exception femic.bcdc_catalog.BcdcCatalogError[source]

Bases: RuntimeError

Raised when the BC Data Catalogue API cannot be queried or parsed.

class femic.bcdc_catalog.BcdcDownloadFailure(resource_name, resource_url, error)[source]

Bases: object

One failed direct-download attempt.

Parameters:

  • resource_name (str)

  • resource_url (str)

  • error (str)

error: str
resource_name: str
resource_url: str
to_dict()[source]
Return type:

dict[str, object]

class femic.bcdc_catalog.BcdcDownloadResult(destination_root, downloaded=(), skipped_resources=(), failures=())[source]

Bases: object

Direct-download outcome for the chosen top match.

Parameters:

  • destination_root (Path)

  • downloaded (tuple[BcdcDownloadedResource, ...])

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

  • failures (tuple[BcdcDownloadFailure, ...])

destination_root: Path
downloaded: tuple[BcdcDownloadedResource, ...] = ()
failures: tuple[BcdcDownloadFailure, ...] = ()
skipped_resources: tuple[str, ...] = ()
to_dict()[source]
Return type:

dict[str, object]

class femic.bcdc_catalog.BcdcDownloadedResource(resource_name, resource_url, saved_path)[source]

Bases: object

One downloaded direct-access resource.

Parameters:

  • resource_name (str)

  • resource_url (str)

  • saved_path (Path)

relative_to(*other)[source]

Delegate path-style relative resolution to the saved path.

Parameters:

other (str | Path)

Return type:

Path

resource_name: str
resource_url: str
saved_path: Path
to_dict()[source]
Return type:

dict[str, object]

class femic.bcdc_catalog.BcdcPackageMatch(package_id, package_name, title, dataset_page_url, organization_name, organization_title, license_title, download_audience, matched_by, match_score, resources, suggested_fetch_strategy=None, manual_follow_up=())[source]

Bases: object

Normalized package match plus scored resource list.

Parameters:

  • package_id (str)

  • package_name (str)

  • title (str)

  • dataset_page_url (str)

  • organization_name (str | None)

  • organization_title (str | None)

  • license_title (str | None)

  • download_audience (str | None)

  • matched_by (str)

  • match_score (int)

  • resources (tuple[BcdcResourceMatch, ...])

  • suggested_fetch_strategy (str | None)

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

dataset_page_url: str
property direct_download_resources: tuple[BcdcResourceMatch, ...]
download_audience: str | None
license_title: str | None
manual_follow_up: tuple[str, ...] = ()
match_score: int
matched_by: str
organization_name: str | None
organization_title: str | None
package_id: str
package_name: str
resources: tuple[BcdcResourceMatch, ...]
suggested_fetch_strategy: str | None = None
title: str
to_dict()[source]
Return type:

dict[str, object]

class femic.bcdc_catalog.BcdcReplacementFamilyCandidate(title, dataset_page_url, object_names, matched_query, rationale)[source]

Bases: object

One review-only replacement candidate for a stale TSR source token.

Parameters:

  • title (str)

  • dataset_page_url (str)

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

  • matched_query (str)

  • rationale (str)

dataset_page_url: str
matched_query: str
object_names: tuple[str, ...]
rationale: str
title: str
to_dict()[source]
Return type:

dict[str, object]

class femic.bcdc_catalog.BcdcResolveResult(query, limit, generated_utc, api_urls, matches, download_result=None, notes=())[source]

Bases: object

Normalized result for one BCDC query.

Parameters:

  • query (str)

  • limit (int)

  • generated_utc (str)

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

  • matches (tuple[BcdcPackageMatch, ...])

  • download_result (BcdcDownloadResult | None)

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

api_urls: tuple[str, ...]
download_result: BcdcDownloadResult | None = None
generated_utc: str
limit: int
matches: tuple[BcdcPackageMatch, ...]
notes: tuple[str, ...] = ()
query: str
to_dict()[source]
Return type:

dict[str, object]

property top_match: BcdcPackageMatch | None
class femic.bcdc_catalog.BcdcResourceMatch(resource_id, name, classification, url, format, bcdc_type, object_name, object_short_name, resource_access_method, resource_type, resource_storage_location, matched_by, match_score, service_type=None, wfs_queryable=False, wfs_capabilities_url=None, wfs_typename=None, suggested_fetch_strategy=None, notes=())[source]

Bases: object

Normalized BC Data Catalogue resource metadata.

Parameters:

  • resource_id (str)

  • name (str)

  • classification (str)

  • url (str | None)

  • format (str | None)

  • bcdc_type (str | None)

  • object_name (str | None)

  • object_short_name (str | None)

  • resource_access_method (str | None)

  • resource_type (str | None)

  • resource_storage_location (str | None)

  • matched_by (str)

  • match_score (int)

  • service_type (str | None)

  • wfs_queryable (bool)

  • wfs_capabilities_url (str | None)

  • wfs_typename (str | None)

  • suggested_fetch_strategy (str | None)

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

bcdc_type: str | None
classification: str
format: str | None
match_score: int
matched_by: str
name: str
notes: tuple[str, ...] = ()
object_name: str | None
object_short_name: str | None
resource_access_method: str | None
resource_id: str
resource_storage_location: str | None
resource_type: str | None
service_type: str | None = None
suggested_fetch_strategy: str | None = None
to_dict()[source]
Return type:

dict[str, object]

url: str | None
wfs_capabilities_url: str | None = None
wfs_queryable: bool = False
wfs_typename: str | None = None
femic.bcdc_catalog.download_direct_bcdc_resources(result, *, destination_root, query_slug=None, download_url_fn=<function _download_url_to_path>)[source]

Download direct-access resources from the top-ranked package only.

Parameters:

  • result (BcdcResolveResult)

  • destination_root (Path)

  • query_slug (str | None)

  • download_url_fn (Callable[[str, Path], None])

Return type:

BcdcDownloadResult

femic.bcdc_catalog.resolve_bcdc_candidates(query, *, limit=5)[source]

Resolve one query against the BC Data Catalogue API.

Parameters:

  • query (str)

  • limit (int)

Return type:

BcdcResolveResult

femic.bcdc_catalog.suggest_bcdc_replacement_family(query, *, limit=5, fetch_json_fn=None)[source]

Return review-only public replacement candidates for selected stale TSR tokens.

Parameters:

  • query (str)

  • limit (int)

  • fetch_json_fn (Callable[[str], dict[str, Any]] | None)

Return type:

tuple[BcdcReplacementFamilyCandidate, …]

femic.bcdc_catalog.write_bcdc_manifest(result, path)[source]

Write one resolve-result manifest as pretty-printed JSON.

Parameters:

  • result (BcdcResolveResult)

  • path (Path)

Return type:

Path