Skip to content

API reference / Archive, sampling contract and types

tsdive.SamplingContract dataclass 

SamplingContract(
    calculation_basis: CalculationBasis,
    retrieval_mode: RetrievalMode,
    *,
    aggregate_type: AggregateType = AggregateType.NONE,
    stepped: bool = False,
)

Declares how a window's samples were produced.

Passed as a required positional argument on every window read so a caller cannot accidentally omit the statement of provenance.

Methods:

Name Description
digest

Stable hash across processes and platforms.
comparable_with

True when two windows may be compared or combined.

Attributes:

Name Type Description
calculation_basis CalculationBasis
retrieval_mode RetrievalMode
aggregate_type AggregateType
stepped bool

calculation_basis instance-attribute 

calculation_basis: CalculationBasis

retrieval_mode instance-attribute 

retrieval_mode: RetrievalMode

_ instance-attribute 

_: KW_ONLY

aggregate_type class-attribute instance-attribute 

aggregate_type: AggregateType = AggregateType.NONE

stepped class-attribute instance-attribute 

stepped: bool = False

digest 

digest() -> str

Stable hash across processes and platforms.

Dataclass hashes are stable for StrEnum members, but we commit to an explicit SHA-256 over canonical text so the value can be stored in provenance records and compared years later.

comparable_with 

comparable_with(other: SamplingContract) -> bool

True when two windows may be compared or combined.

Only the calculation basis changes the meaning of aggregated numbers; retrieval mode and stepped-ness change sample placement. The store refuses cross-basis mixing outright.