abaquant.core.provenance

Import path: abaquant.core.provenance

Domain: Auditability and metadata primitives.

Purpose

Provider-neutral data provenance metadata for AbaQuant objects.

When to use it

Use these objects when results must retain provider, cache, request, currency, reporting-date, and transformation information.

Public objects

  • class: DataProvenance — Immutable metadata describing how a dataset or result was produced. * DataProvenance.as_dict — Return a JSON-serializable provenance dictionary. * DataProvenance.with_step — Return a copy with one additional transformation step appended. * DataProvenance.from_dict — Build a provenance object from a saved dictionary payload.

  • class: ProvenanceMixin — Mixin for objects that expose a ‘’provenance’’ metadata attribute. * ProvenanceMixin.provenance_dict — Return this object’s provenance as a plain dictionary.

  • function: utc_now_iso — Return the current UTC timestamp in second precision.

  • function: provenance_from_dataframe — Build provenance with shape metadata for a tabular object.

  • function: merge_provenance — Combine several provenance records into one derived record.

Detailed reference

Provider-neutral data provenance metadata for AbaQuant objects.

Purpose

This module defines a compact immutable provenance record used by market data, financial statements, rate curves, option chains, portfolio inputs, backtests, calibrations, reports, and risk dashboards. The record is intentionally simple: it captures where data came from, when it was retrieved or constructed, how cache was used, which source labels were transformed, and the reporting conventions attached to the dataset.

Conventions

Timestamps are stored as ISO-8601 UTC text. cache_status and request are read-only mappings so provider-specific cache keys, URLs, refresh policies, or shape diagnostics can be preserved without forcing a global schema.

class abaquant.core.provenance.DataProvenance(provider, dataset, retrieved_at_utc=None, cache_status=<factory>, source_labels=(), currency=None, reporting_date=None, transformation_steps=(), request=<factory>, notes=())

Bases: object

Immutable metadata describing how a dataset or result was produced.

Parameters:

  • provider (str) – Source provider or construction mechanism, such as "yahoo", "sec", "fred", "manual", or "derived".

  • dataset (str) – Dataset or object category, for example "option_chain" or "financial_statement_snapshot".

  • retrieved_at_utc (str | None, default=None) – ISO-8601 UTC retrieval/construction timestamp. When omitted, the current UTC time is used.

  • cache_status (Mapping[str, object], optional) – Provider-specific cache diagnostics.

  • source_labels (Sequence[str], optional) – Provider-native labels or series identifiers used in the dataset.

  • currency (str | None, default=None) – Reporting currency where applicable.

  • reporting_date (str | None, default=None) – Reporting date, observation date, or period label.

  • transformation_steps (Sequence[str], optional) – Ordered human-readable transformations applied to the source data.

  • request (Mapping[str, object], optional) – Request metadata such as symbol, period, source, or refresh policy.

  • notes (Sequence[str], optional) – Additional limitations or interpretation notes.

as_dict()

Return a JSON-serializable provenance dictionary.

Return type:

dict[str, object]

with_step(step)

Return a copy with one additional transformation step appended.

Parameters:

step (str)

Return type:

DataProvenance

classmethod from_dict(payload)

Build a provenance object from a saved dictionary payload.

Parameters:

payload (mapping or None) – Serialized provenance dictionary. None returns None.

Returns:

Reconstructed provenance record or None when unavailable.

Return type:

DataProvenance | None

class abaquant.core.provenance.ProvenanceMixin

Bases: object

Mixin for objects that expose a provenance metadata attribute.

provenance_dict()

Return this object’s provenance as a plain dictionary.

Return type:

dict[str, object]

abaquant.core.provenance.merge_provenance(records, *, provider='derived', dataset='combined', transformation_steps=(), request=None)

Combine several provenance records into one derived record.

Parameters:

  • records (sequence of DataProvenance or None) – Input provenance records. None values are ignored.

  • provider (str, default="derived") – Provider label for the combined object.

  • dataset (str, default="combined") – Dataset label for the combined object.

  • transformation_steps (sequence of str, optional) – Extra transformation steps appended after source steps.

  • request (mapping, optional) – Combined-object request metadata.

Returns:

Derived provenance record with nested source metadata in request.

Return type:

DataProvenance

abaquant.core.provenance.provenance_from_dataframe(frame, *, provider, dataset, source_labels=(), transformation_steps=(), currency=None, reporting_date=None, request=None, cache_status=None)

Build provenance with shape metadata for a tabular object.

Parameters:

  • frame (object) – DataFrame-like object exposing shape.

  • provider (str) – Fields passed to DataProvenance.

  • dataset (str) – Fields passed to DataProvenance.

  • source_labels (Sequence[str]) – Fields passed to DataProvenance.

  • transformation_steps (Sequence[str]) – Fields passed to DataProvenance.

  • currency (str | None) – Fields passed to DataProvenance.

  • reporting_date (str | None) – Fields passed to DataProvenance.

  • request (Mapping[str, object] | None) – Fields passed to DataProvenance.

  • cache_status (Mapping[str, object] | None) – Fields passed to DataProvenance.

Returns:

Provenance record including table-shape request metadata.

Return type:

DataProvenance

abaquant.core.provenance.utc_now_iso()

Return the current UTC timestamp in second precision.

Return type:

str