Models

Model classes validate identity, normalized observations, and provenance. Import the public names from persistra.model.

Identity

persistra.model.identity

Provider-neutral catalog identities.

InstrumentKind

Bases: StrEnum

Supported instrument families.

OptionType

Bases: StrEnum

Option contract sides.

SeriesKind

Bases: StrEnum

Supported scalar series families.

Instrument dataclass

A provider-neutral financial or economic instrument.

Listing dataclass

A venue listing for an instrument.

ProviderSymbol dataclass

A provider key mapped to one instrument or listing.

OptionContract dataclass

Provider-scoped option terms.

SeriesDefinition dataclass

Provider-neutral identity for a scalar series.

_require_text(value: str, name: str) -> None

_require_optional_text(value: str | None, name: str) -> None

provider_instrument_id(provider: str, kind: InstrumentKind, symbol: str) -> str

Create a stable provider-scoped instrument identity.

provider_series_id(provider: str, provider_series: str, frequency: str) -> str

Create a stable provider-scoped series identity.

_scoped_id(*parts: str) -> str

Market results and metadata

persistra.model.market

Normalized market data results.

BAR_CONTRACT = FrameContract(name='bars', target='BarSet.frame', dtypes=BAR_DTYPES, required=('instrument_id', 'provider', 'provider_symbol', 'interval', 'timestamp_position', 'source_timezone', 'session', 'price_adjustment', 'open', 'high', 'low', 'close', 'retrieved_at'), identity_key=('instrument_id', 'interval', 'price_adjustment', 'session', 'date', 'timestamp'), sort_by=('instrument_id', 'interval', 'price_adjustment', 'session', 'date', 'timestamp'), invariants=('positive-ohlc', 'nonnegative-activity', 'exactly-one-temporal-identity', 'ohlc-bounds', 'instrument-scope', 'metadata-scope')) module-attribute

QUOTE_CONTRACT = FrameContract(name='latest-quotes', target='QuoteSet.frame', dtypes=QUOTE_DTYPES, required=('instrument_id', 'provider', 'provider_symbol', 'price', 'entitlement', 'retrieved_at'), identity_key=('provider', 'provider_symbol'), sort_by=(), invariants=('positive-price', 'finite-quote-fields', 'nonnegative-volume', 'metadata-scope')) module-attribute

TOP_OF_BOOK_CONTRACT = FrameContract(name='top-of-book', target='TopOfBookSet.frame', dtypes=TOP_OF_BOOK_DTYPES, required=('instrument_id', 'provider', 'provider_symbol', 'retrieved_at'), identity_key=('provider', 'provider_symbol'), sort_by=(), invariants=('nonnegative-quotes', 'size-requires-price', 'quote-state-diagnostics', 'metadata-scope')) module-attribute

DataValidationError

Bases: PersistraError, ValueError

Raised when normalized data violates its contract.

QuoteState dataclass

One bid-ask pair used to derive nonfatal state diagnostics.

Instrument dataclass

A provider-neutral financial or economic instrument.

EntitlementMode

Bases: StrEnum

Provider freshness and entitlement modes.

CacheStatus

Bases: StrEnum

Raw response cache outcomes.

SchemaDiagnostic dataclass

A nonfatal provider schema difference.

ResultMetadata dataclass

Required provenance with deeply immutable portable request parameters.

Request parameters may contain strings, integers, finite floats, booleans, None, string-keyed mappings, lists, and tuples. Persistra copies the complete structure, removes api_key and apikey fields recursively, freezes mappings, and converts sequences to tuples.

BarSet dataclass

Validated bars and their acquisition provenance.

QuoteSet dataclass

Validated latest quotes and acquisition provenance.

TopOfBookSet dataclass

Validated top-of-book snapshots and provenance.

Missing and one-sided quotes are valid. Locked and crossed quotes are retained with bid_ask diagnostics. A size without its corresponding price is invalid.

freeze_portable_mapping(value: Mapping[str, Any], *, name: str, redact_api_keys: bool = False) -> Mapping[str, Any]

Copy and recursively freeze one portable JSON mapping.

require_finite(frame: pd.DataFrame, columns: list[str], *, positive: bool = False) -> None

Validate finite numeric values while allowing missing values.

require_metadata_values(frame: pd.DataFrame, *, provider: str | None = None, retrieved_at: Any | None = None, entitlement: str | None = None) -> None

Require row-level provenance to agree with result metadata.

require_nonnegative(frame: pd.DataFrame, columns: list[str]) -> None

Validate nonnegative numeric values while allowing missing values.

require_scope_values(frame: pd.DataFrame, expected: Mapping[str, Any | None]) -> None

Require every row to agree with its enclosing result scope.

validate_frame(frame: pd.DataFrame, contract: FrameContract, *, validate_rows: Callable[[pd.DataFrame], None]) -> pd.DataFrame

Copy and validate an exact normalized frame.

require_sizes_have_prices(frame: pd.DataFrame, *, bid_price: str, bid_size: str, ask_price: str, ask_size: str) -> None

Reject a quoted size when the corresponding price is missing.

with_quote_diagnostics(metadata: ResultMetadata, states: Iterable[QuoteState]) -> ResultMetadata

Add deterministic locked and crossed quote diagnostics.

Historical options

persistra.model.options

Normalized historical option-chain results.

OPTION_CONTRACT_CONTRACT = FrameContract(name='option-contracts', target='OptionChain.contracts', dtypes=OPTION_CONTRACT_DTYPES, required=(tuple(OPTION_CONTRACT_DTYPES)), identity_key=('provider', 'contract_id'), sort_by=('expiration', 'strike', 'option_type', 'contract_id'), invariants=('positive-strike', 'known-option-type', 'expiration-on-or-after-chain-date', 'chain-scope', 'metadata-scope')) module-attribute

OPTION_OBSERVATION_CONTRACT = FrameContract(name='option-observations', target='OptionChain.observations', dtypes=OPTION_OBSERVATION_DTYPES, required=('contract_id', 'provider', 'chain_date', 'retrieved_at'), identity_key=('provider', 'contract_id', 'chain_date'), sort_by=('provider', 'contract_id'), invariants=('nonnegative-market-fields', 'finite-greeks', 'size-requires-price', 'chain-date-scope', 'contract-membership', 'metadata-scope', 'quote-state-diagnostics')) module-attribute

DataValidationError

Bases: PersistraError, ValueError

Raised when normalized data violates its contract.

QuoteState dataclass

One bid-ask pair used to derive nonfatal state diagnostics.

ResultMetadata dataclass

Required provenance with deeply immutable portable request parameters.

Request parameters may contain strings, integers, finite floats, booleans, None, string-keyed mappings, lists, and tuples. Persistra copies the complete structure, removes api_key and apikey fields recursively, freezes mappings, and converts sequences to tuples.

OptionChain dataclass

Contracts and observations for one historical chain.

Missing and one-sided quotes are valid. Locked and crossed quotes are retained with bid_ask diagnostics. A size without its corresponding price is invalid.

require_finite(frame: pd.DataFrame, columns: list[str], *, positive: bool = False) -> None

Validate finite numeric values while allowing missing values.

require_metadata_values(frame: pd.DataFrame, *, provider: str | None = None, retrieved_at: Any | None = None, entitlement: str | None = None) -> None

Require row-level provenance to agree with result metadata.

require_nonnegative(frame: pd.DataFrame, columns: list[str]) -> None

Validate nonnegative numeric values while allowing missing values.

require_scope_values(frame: pd.DataFrame, expected: Mapping[str, Any | None]) -> None

Require every row to agree with its enclosing result scope.

validate_frame(frame: pd.DataFrame, contract: FrameContract, *, validate_rows: Callable[[pd.DataFrame], None]) -> pd.DataFrame

Copy and validate an exact normalized frame.

require_sizes_have_prices(frame: pd.DataFrame, *, bid_price: str, bid_size: str, ask_price: str, ask_size: str) -> None

Reject a quoted size when the corresponding price is missing.

with_quote_diagnostics(metadata: ResultMetadata, states: Iterable[QuoteState]) -> ResultMetadata

Add deterministic locked and crossed quote diagnostics.

_require_text(value: str, name: str) -> None

Scalar quotes and series

persistra.model.series

Normalized scalar quote and series results.

SERIES_CONTRACT = FrameContract(name='scalar-series', target='SeriesSet.frame', dtypes=SERIES_DTYPES, required=('series_id', 'provider', 'provider_series', 'series_kind', 'frequency', 'period_label', 'retrieved_at'), identity_key=('series_id', 'frequency', 'maturity', 'period_label'), sort_by=('series_id', 'frequency', 'maturity', 'period_label'), invariants=('finite-values-when-observed', 'definition-scope', 'metadata-scope')) module-attribute

VINTAGE_SERIES_CONTRACT = FrameContract(name='vintage-scalar-series', target='VintageSeriesSet.frame', dtypes=VINTAGE_SERIES_DTYPES, required=('series_id', 'provider', 'provider_series', 'series_kind', 'frequency', 'period_label', 'available_from', 'is_deleted', 'retrieved_at'), identity_key=('series_id', 'frequency', 'maturity', 'period_label', 'available_from'), sort_by=('series_id', 'frequency', 'maturity', 'period_label', 'available_from'), invariants=('finite-values-when-observed', 'calendar-date-availability', 'nonoverlapping-availability', 'deleted-value-missing', 'definition-scope', 'metadata-scope')) module-attribute

DataValidationError

Bases: PersistraError, ValueError

Raised when normalized data violates its contract.

QuoteState dataclass

One bid-ask pair used to derive nonfatal state diagnostics.

SeriesDefinition dataclass

Provider-neutral identity for a scalar series.

ResultMetadata dataclass

Required provenance with deeply immutable portable request parameters.

Request parameters may contain strings, integers, finite floats, booleans, None, string-keyed mappings, lists, and tuples. Persistra copies the complete structure, removes api_key and apikey fields recursively, freezes mappings, and converts sequences to tuples.

ExchangeRateQuote dataclass

One provider exchange-rate observation.

Missing and one-sided bid-ask quotes are valid. Locked and crossed quotes are retained with a bid_ask diagnostic.

CommoditySpotQuote dataclass

One provider commodity spot observation.

SeriesSet dataclass

One validated scalar series and its provenance.

VintageSeriesSet dataclass

One validated scalar-series revision history and its provenance.

VintageDatesResult dataclass

Release dates when one provider series changed and their provenance.

require_finite(frame: pd.DataFrame, columns: list[str], *, positive: bool = False) -> None

Validate finite numeric values while allowing missing values.

require_metadata_values(frame: pd.DataFrame, *, provider: str | None = None, retrieved_at: Any | None = None, entitlement: str | None = None) -> None

Require row-level provenance to agree with result metadata.

require_scope_values(frame: pd.DataFrame, expected: Mapping[str, Any | None]) -> None

Require every row to agree with its enclosing result scope.

validate_frame(frame: pd.DataFrame, contract: FrameContract, *, validate_rows: Callable[[pd.DataFrame], None]) -> pd.DataFrame

Copy and validate an exact normalized frame.

with_quote_diagnostics(metadata: ResultMetadata, states: Iterable[QuoteState]) -> ResultMetadata

Add deterministic locked and crossed quote diagnostics.

_require_result_text(value: str, name: str) -> None

_validate_vintage_dates(frame: pd.DataFrame) -> None

_validate_vintage_intervals(frame: pd.DataFrame) -> None

_validate_vintage_scope(frame: pd.DataFrame, definition: SeriesDefinition, metadata: ResultMetadata) -> None

_validate_series_scope(frame: pd.DataFrame, definition: SeriesDefinition, metadata: ResultMetadata) -> None

Reference results and catalogs

persistra.model.reference

Normalized reference results and explicit catalog mappings.

INDEX_CATALOG_CONTRACT = FrameContract(name='index-catalog', target='IndexCatalogResult.frame', dtypes=INDEX_CATALOG_DTYPES, required=('provider_symbol', 'name', 'provider_type'), identity_key=('provider_symbol',), sort_by=('provider_symbol',), invariants=()) module-attribute

MARKET_STATUS_CONTRACT = FrameContract(name='market-status', target='MarketStatusResult.frame', dtypes=MARKET_STATUS_DTYPES, required=('market_type', 'region', 'current_status', 'retrieved_at'), identity_key=('market_type', 'region'), sort_by=('market_type', 'region'), invariants=('metadata-scope',)) module-attribute

SEARCH_CONTRACT = FrameContract(name='symbol-search', target='InstrumentSearchResult.frame', dtypes=SEARCH_DTYPES, required=('provider_symbol', 'name', 'provider_type', 'match_score'), identity_key=('provider_symbol', 'region'), sort_by=('match_score', 'provider_symbol'), invariants=('normalized-finite-match-score',)) module-attribute

INDEX_CATALOG_DTYPES = cast('dict[str, str]', INDEX_CATALOG_CONTRACT.dtypes) module-attribute

MARKET_STATUS_DTYPES = cast('dict[str, str]', MARKET_STATUS_CONTRACT.dtypes) module-attribute

SEARCH_DTYPES = cast('dict[str, str]', SEARCH_CONTRACT.dtypes) module-attribute

DataValidationError

Bases: PersistraError, ValueError

Raised when normalized data violates its contract.

Instrument dataclass

A provider-neutral financial or economic instrument.

Listing dataclass

A venue listing for an instrument.

ProviderSymbol dataclass

A provider key mapped to one instrument or listing.

ResultMetadata dataclass

Required provenance with deeply immutable portable request parameters.

Request parameters may contain strings, integers, finite floats, booleans, None, string-keyed mappings, lists, and tuples. Persistra copies the complete structure, removes api_key and apikey fields recursively, freezes mappings, and converts sequences to tuples.

InstrumentSearchResult dataclass

Provider search matches without inferred canonical identity.

MarketStatusResult dataclass

Provider market-status observations.

IndexCatalogResult dataclass

A normalized provider index catalog.

Catalog dataclass

An explicit instrument, listing, and provider-symbol catalog.

instruments: tuple[Instrument, ...] property

Return instruments in stable identity order.

listings: tuple[Listing, ...] property

Return listings in stable identity order.

provider_symbols: tuple[ProviderSymbol, ...] property

Return provider mappings in stable provider-key order.

add_instrument(instrument: Instrument) -> None

Add an instrument without replacing a populated identity.

add_listing(listing: Listing) -> None

Add a listing that references a known instrument.

map_provider_symbol(mapping: ProviderSymbol) -> None

Register one explicit provider-symbol mapping.

resolve(provider: str, kind: str, symbol: str) -> Instrument | None

Resolve an explicit provider mapping when one exists.

resolve_listing(provider: str, kind: str, symbol: str) -> Listing | None

Resolve the listing selected by one explicit provider mapping.

require_metadata_values(frame: pd.DataFrame, *, provider: str | None = None, retrieved_at: Any | None = None, entitlement: str | None = None) -> None

Require row-level provenance to agree with result metadata.

validate_frame(frame: pd.DataFrame, contract: FrameContract, *, validate_rows: Callable[[pd.DataFrame], None]) -> pd.DataFrame

Copy and validate an exact normalized frame.

_validate_scores(frame: pd.DataFrame) -> None