Python API Reference

The public package entrypoint is fresh_hectaresbc.HectaresBC. It exposes catalog search and lookup, local path/status inspection, backend diagnostics, and fetch planning/retrieval methods.

Public Package

Public package interface for fresh-hectaresbc.

API Facade

Top-level public API facade.

class fresh_hectaresbc.api.HectaresBC(metadata_root=None, data_repo_path=None, backend=None)[source]

Convenience entrypoint for HectaresBC catalog and data access.

The facade exposes catalog, local path/status, diagnostics, and fetch behavior through structured result objects.

Parameters:

  • metadata_root (Path | str | None)

  • data_repo_path (Path | str | None)

  • backend (BackendAdapter | None)

backend: BackendAdapter | None = None
property catalog: Catalog

Load the recovered catalog on first use.

content_status(dataset)[source]

Report local content status without fetching data.

Parameters:

dataset (str | DatasetRecord)

Return type:

ContentStatus

data_repo_path: Path | str | None = None
diagnostics()[source]

Return backend diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(dataset, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one dataset.

Parameters:
Return type:

FetchResult

fetch_many(datasets, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for multiple datasets.

Parameters:
Return type:

tuple[FetchResult, …]

filter(**filters)[source]

Filter recovered catalog records.

Parameters:

filters (object)

Return type:

list[DatasetRecord]

get(dataset_id)[source]

Return one dataset record by exact recovered ID.

Parameters:

dataset_id (str)

Return type:

DatasetRecord

local_path(dataset)[source]

Return the expected local filesystem path for a dataset.

Parameters:

dataset (str | DatasetRecord)

Return type:

Path

metadata_root: Path | str | None = None
resolve(dataset)[source]

Resolve a dataset ID or record to a data-repository path.

Parameters:

dataset (str | DatasetRecord)

Return type:

ResolvedDatasetPath

property resolver: Resolver

Create the read-only data repository resolver on first use.

search(query, *, family=None, limit=None, allow_empty=False)[source]

Search recovered catalog records.

Parameters:

  • query (str)

  • family (str | None)

  • limit (int | None)

  • allow_empty (bool)

Return type:

list[DatasetRecord]

Catalog

Recovered HectaresBC catalog loading and query APIs.

class fresh_hectaresbc.catalog.Catalog(records, metadata_root)[source]

In-memory view of recovered HectaresBC metadata records.

Parameters:

  • records (Iterable[DatasetRecord])

  • metadata_root (Path | str | Traversable)

exists(dataset_id)[source]

Return whether a recovered dataset ID exists.

Parameters:

dataset_id (str)

Return type:

bool

filter(*, family=None, dataset_id_prefix=None, source_path_prefix=None, name_prefix=None, virtual_layer_id=None, has_category_metadata=None, has_value_metadata=None, has_wms_xml=None, has_tiff=None, verification_status=None, zip_read_status=None, min_size_bytes=None, max_size_bytes=None)[source]

Return records matching structured recovered-catalog filters.

Parameters:

  • family (str | None)

  • dataset_id_prefix (str | None)

  • source_path_prefix (str | None)

  • name_prefix (str | None)

  • virtual_layer_id (str | int | None)

  • has_category_metadata (bool | None)

  • has_value_metadata (bool | None)

  • has_wms_xml (bool | None)

  • has_tiff (bool | None)

  • verification_status (str | None)

  • zip_read_status (str | None)

  • min_size_bytes (int | None)

  • max_size_bytes (int | None)

Return type:

list[DatasetRecord]

classmethod from_default_paths(start=None)[source]

Load recovered catalog records from source metadata or package data.

Parameters:

start (Path | str | None)

Return type:

Catalog

classmethod from_metadata_root(metadata_root)[source]

Load recovered catalog records from a metadata directory.

Parameters:

metadata_root (Path | str)

Return type:

Catalog

classmethod from_package_data()[source]

Load recovered catalog records bundled with the installed package.

Return type:

Catalog

get(dataset_id)[source]

Return exactly one record by recovered dataset ID.

Parameters:

dataset_id (str)

Return type:

DatasetRecord

iter_records(*, family=None, verification_status=None, has_known_gaps=None, has_uncertainty=None)[source]

Iterate records with basic catalog-contract filters.

Parameters:

  • family (str | None)

  • verification_status (str | None)

  • has_known_gaps (bool | None)

  • has_uncertainty (bool | None)

Return type:

Iterator[DatasetRecord]

property records: tuple[DatasetRecord, ...]
search(query, *, family=None, limit=None, allow_empty=False)[source]

Search recovered source-backed text fields.

Parameters:

  • query (str)

  • family (str | None)

  • limit (int | None)

  • allow_empty (bool)

Return type:

list[DatasetRecord]

exception fresh_hectaresbc.catalog.CatalogError[source]

Base class for catalog API errors.

exception fresh_hectaresbc.catalog.CatalogFileMissing[source]

Raised when a required catalog CSV is missing.

exception fresh_hectaresbc.catalog.CatalogHeaderInvalid[source]

Raised when a catalog CSV does not contain required columns.

exception fresh_hectaresbc.catalog.DatasetNotFound[source]

Raised when exact dataset lookup fails.

exception fresh_hectaresbc.catalog.DuplicateDatasetId[source]

Raised when recovered catalog inputs contain duplicate IDs.

exception fresh_hectaresbc.catalog.QueryInvalid[source]

Raised when a query cannot be evaluated.

Models

Shared catalog data models.

class fresh_hectaresbc.models.BackendDiagnostic(backend, check, status, message, command_summary=None, remediation=None, secret_safe=True)[source]

One backend readiness diagnostic check.

Parameters:

  • backend (str)

  • check (str)

  • status (str)

  • message (str)

  • command_summary (str | None)

  • remediation (str | None)

  • secret_safe (bool)

backend: str
check: str
command_summary: str | None = None
message: str
remediation: str | None = None
secret_safe: bool = True
status: str
class fresh_hectaresbc.models.ContentStatus(dataset_id, status, local_path, submodule_initialized, path_metadata_exists, content_present, message)[source]

Local content status for a resolved raw ZIP payload.

Parameters:

  • dataset_id (str)

  • status (str)

  • local_path (Path)

  • submodule_initialized (bool)

  • path_metadata_exists (bool)

  • content_present (bool)

  • message (str)

content_present: bool
dataset_id: str
local_path: Path
message: str
path_metadata_exists: bool
status: str
submodule_initialized: bool
class fresh_hectaresbc.models.DatasetRecord(dataset_id, source_family, source_zip_path, source_filename, source_stem, title_candidate, verification_status, manifest_size_bytes, known_gaps, uncertainty_notes, fields)[source]

One recovered HectaresBC catalog record.

Parameters:

  • dataset_id (str)

  • source_family (str)

  • source_zip_path (str)

  • source_filename (str)

  • source_stem (str)

  • title_candidate (str)

  • verification_status (str)

  • manifest_size_bytes (int | None)

  • known_gaps (str)

  • uncertainty_notes (str)

  • fields (Mapping[str, str])

bool_field(name)[source]

Return a recovered flag-like field as a boolean.

Parameters:

name (str)

Return type:

bool

dataset_id: str
field(name, default='')[source]

Return a raw recovered field without changing source names.

Parameters:

  • name (str)

  • default (str)

Return type:

str

fields: Mapping[str, str]
classmethod from_row(row)[source]
Parameters:

row (Mapping[str, str])

Return type:

DatasetRecord

int_field(name)[source]

Return a recovered integer field when present.

Parameters:

name (str)

Return type:

int | None

known_gaps: str
manifest_size_bytes: int | None
source_family: str
source_filename: str
source_stem: str
source_zip_path: str
title_candidate: str
to_dict()[source]

Serialize the record while preserving all recovered source fields.

Return type:

dict[str, object]

uncertainty_notes: str
verification_status: str
class fresh_hectaresbc.models.FetchResult(dataset_id, status, backend, local_path, message, diagnostics=(), command_summary=None, verification_performed=False, secret_safe=True)[source]

Structured result for a dataset retrieval request.

Parameters:

  • dataset_id (str)

  • status (str)

  • backend (str)

  • local_path (Path)

  • message (str)

  • diagnostics (tuple[BackendDiagnostic, ...])

  • command_summary (str | None)

  • verification_performed (bool)

  • secret_safe (bool)

backend: str
command_summary: str | None = None
dataset_id: str
diagnostics: tuple[BackendDiagnostic, ...] = ()
local_path: Path
message: str
secret_safe: bool = True
status: str
verification_performed: bool = False
class fresh_hectaresbc.models.ResolvedDatasetPath(dataset_id, source_zip_path, data_repo_path, raw_relative_path, absolute_path, submodule_initialized, path_metadata_exists, content_present)[source]

Filesystem resolution for a catalog record’s raw ZIP payload.

Parameters:

  • dataset_id (str)

  • source_zip_path (str)

  • data_repo_path (Path)

  • raw_relative_path (Path)

  • absolute_path (Path)

  • submodule_initialized (bool)

  • path_metadata_exists (bool)

  • content_present (bool)

absolute_path: Path
content_present: bool
data_repo_path: Path
dataset_id: str
path_metadata_exists: bool
raw_relative_path: Path
source_zip_path: str
submodule_initialized: bool

Retrieval

Read-only dataset resolution and local content-status APIs.

class fresh_hectaresbc.retrieval.Resolver(catalog, data_repo_path=None, backend=None)[source]

Resolve catalog records to paths in the linked data repository.

Parameters:
content_status(dataset)[source]

Report local availability without fetching content.

Parameters:

dataset (str | DatasetRecord)

Return type:

ContentStatus

diagnostics()[source]

Return backend diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(dataset, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one dataset.

Parameters:
Return type:

FetchResult

fetch_many(datasets, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for multiple datasets in input order.

Parameters:
Return type:

tuple[FetchResult, …]

local_path(dataset)[source]

Return the expected local filesystem path for a dataset.

Parameters:

dataset (str | DatasetRecord)

Return type:

Path

resolve(dataset)[source]

Resolve a dataset ID or record to the expected raw ZIP path.

Parameters:

dataset (str | DatasetRecord)

Return type:

ResolvedDatasetPath

Backends

Backend adapter protocol.

class fresh_hectaresbc.backends.base.BackendAdapter(*args, **kwargs)[source]

Minimal interface for dataset retrieval backends.

content_status(resolved_path)[source]

Return local content status for a resolved path.

Parameters:

resolved_path (ResolvedDatasetPath)

Return type:

ContentStatus

diagnostics()[source]

Return non-mutating backend readiness diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(resolved_path, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one resolved path.

Parameters:
Return type:

FetchResult

name: str

DataLad/git-annex backend adapter.

class fresh_hectaresbc.backends.datalad.DataladBackend(data_repo_path, *, special_remote='arbutus-s3', command_timeout=120, env=None)[source]

Backend adapter for the linked DataLad/git-annex data repository.

Parameters:

  • data_repo_path (Path | str)

  • special_remote (str)

  • command_timeout (int)

  • env (dict[str, str] | None)

content_status(resolved_path)[source]

Return local content status without retrieving content.

Parameters:

resolved_path (ResolvedDatasetPath)

Return type:

ContentStatus

diagnostics()[source]

Return non-mutating backend readiness checks.

Return type:

tuple[BackendDiagnostic, …]

fetch(resolved_path, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one resolved path.

Parameters:
Return type:

FetchResult

name = 'datalad'