Skip to main content

functions

Cache-persistence helpers for the gcc_calculation step (v1).

Extracted from gcc_calculation_task to keep the cache-write orchestration (building the gcc_calculation.cache accessor and upserting the per-file rows) apart from the task body.

Unlike the version-agnostic pure math in steps.gcc_calculation.functions, these are v1-specific and perform cache I/O: they bind to this version's GCCCalculation ORM, GCCCalculationRecord, and GCCCalculationResult.

Module​

Functions​

build_gcc_accessor​

def build_gcc_accessor(    cache: CacheProtocol,    task_hash: str,    config: GCCCalculationConfig,    *filter_fields: str,) ‑> CacheAccessor:

Build the CacheAccessor for this step's gcc_calculation partition.

Arguments

  • cache: The cache backend.
  • task_hash: The step's partition key.
  • config: The step config (source of any config-derived equality filters).
  • *filter_fields: The step's cache_filter_fields — empty for this step, whose rows are keyed by task_hash alone.

Returns A CacheAccessor scoped to this task_hash.

persist_gcc_metrics​

def persist_gcc_metrics(    cache: CacheProtocol,    task_hash: str,    config: GCCCalculationConfig,    output: dict[str, GCCMetrics | str | None],    *,    project_id: str | None = None,    run_id: str | None = None,    filter_fields: tuple[str, ...] = (),) ‑> GCCCalculationResult:

Upsert per-file GCC rows and return the cache-backed result.

Each output value is either a GCCMetrics (persisted to metrics_json), a reason str (persisted to error, metrics_json null), or None (both null). Metrics and reason are mutually exclusive — an uncomputable file is recorded as a reason, never as a partial object.

Arguments

  • cache: The cache backend to persist into.
  • task_hash: Partition key for the gcc_calculation table.
  • config: The step config (passed through to the accessor).
  • output: Per-file result map — a GCCMetrics (success), a reason str (missing_data:* / calculation_error:*), or None.
  • project_id: Provenance only — not part of the cache key.
  • run_id: Optional provenance run ID.
  • filter_fields: The step's cache_filter_fields, forwarded to the accessor.

Returns GCCCalculationResult carrying the row count and a scoped accessor.