Projects

The project module validates the versioned project manifest and exposes fixed format-version-1 paths. It never searches parent directories or creates paths while opening a project.

Public project namespace

persistra.project

Standard Persistra project layout and safe initialization.

PROJECT_FORMAT_VERSION = 1 module-attribute

__all__ = ['PersistraProject', 'ProjectValidation', 'create_project', 'validate_project'] module-attribute

_PROJECT_NAME = re.compile('^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$') module-attribute

_VERSION = re.compile('(?:(?P<epoch>[0-9]+)!)?(?P<major>0|[1-9][0-9]*)(?:\\.(?:0|[1-9][0-9]*))+(?:(?:a|b|rc)[0-9]+)?(?:\\.post[0-9]+)?(?:\\.dev[0-9]+)?') module-attribute

_DIRECTORIES = (Path('cache'), Path('cache/responses'), Path('artifacts'), Path('artifacts/research'), Path('artifacts/trading-engine'), Path('notebooks'), Path('tests')) module-attribute

_MARKERS = (Path('cache/responses/.gitkeep'), Path('artifacts/research/.gitkeep'), Path('artifacts/trading-engine/.gitkeep'), Path('notebooks/.gitkeep')) module-attribute

_STORE_STAGING_DIRECTORY = Path('.persistra-init') module-attribute

FileIdentity = tuple[int, int]

ProjectValidation dataclass

Structured result of one explicit-directory project validation.

error_count: int property

Return the number of error findings.

warning_count: int property

Return the number of warning findings.

is_valid: bool property

Return whether project validation found no errors.

to_dict() -> dict[str, object]

Return the deterministic versioned JSON representation.

DuckDBStore

A one-process DuckDB store with snapshots and cumulative research datasets.

schema_version: int property

Return the validated store schema version.

create(path: str | Path) -> Self classmethod

Create a new store with the current supported schema at an absent path.

open(path: str | Path, *, read_only: bool = False) -> Self classmethod

Open an existing store after validating its schema without migrating it.

close() -> None

Close the explicit DuckDB connection.

load_catalog() -> Catalog

Load the complete persistent instrument catalog into an isolated value.

save_catalog(catalog: Catalog) -> None

Merge one explicit catalog into persistent storage atomically.

save(result: object) -> str

Validate and save one supported normalized result.

load_bars(instrument_id: str, *, retrieved_before: datetime | None = None) -> BarSet | None

Load the latest stored bars for one instrument scope.

load_options(underlying_instrument_id: str, chain_date: date, *, retrieved_before: datetime | None = None) -> OptionChain | None

Load the latest stored historical chain for one date.

load_quotes(symbols: tuple[str, ...], *, retrieved_before: datetime | None = None) -> QuoteSet | None

Load the latest stored quote batch for an exact symbol scope.

load_top_of_book(symbols: tuple[str, ...], *, retrieved_before: datetime | None = None) -> TopOfBookSet | None

Load the latest stored book batch for an exact symbol scope.

load_series(series_id: str, *, retrieved_before: datetime | None = None) -> SeriesSet | None

Load the latest stored scalar series for one identity.

load_vintage_series(series_id: str, *, retrieved_before: datetime | None = None) -> VintageSeriesSet | None

Load the latest stored revision history for one series identity.

load_vintage_dates(provider_series: str, *, retrieved_before: datetime | None = None) -> VintageDatesResult | None

Load the latest stored FRED vintage-date result for one provider series.

load_search(query: str) -> InstrumentSearchResult | None

Load the latest stored provider search result.

load_market_status() -> MarketStatusResult | None

Load the latest stored provider market status.

load_index_catalog() -> IndexCatalogResult | None

Load the latest stored provider index catalog.

load_exchange_rate(instrument_id: str) -> ExchangeRateQuote | None

Load the latest stored exchange-rate quote.

load_commodity_spot(series_id: str) -> CommoditySpotQuote | None

Load the latest stored commodity spot quote.

latest_payload(family: str, scope_key: str) -> dict[str, Any] | None

Return a copy of the latest stored payload for research diagnostics.

list_datasets() -> tuple[StoredDataset, ...]

List stored family scopes in deterministic order.

list_snapshots(family: str, scope_key: str) -> tuple[StoredSnapshot, ...]

List exact snapshots for one dataset, newest first.

load_snapshot(snapshot_id: str) -> StoredResult | None

Load and validate one exact acquisition snapshot by identity.

query_bars(instrument_id: str, *, interval: str | None = None, start: date | datetime | None = None, end: date | datetime | None = None, retrieved_before: datetime | None = None) -> pd.DataFrame

Query cumulative bars with latest-observed row revisions and inclusive filters.

query_bars_page(instrument_id: str, *, interval: str | None = None, start: date | datetime | None = None, end: date | datetime | None = None, retrieved_before: datetime | None = None, limit: int = 100, offset: int = 0, sort_by: str | None = None, descending: bool = False) -> StoredPage

Query one bounded cumulative bar page with an exact filtered total.

query_series(series_id: str, *, start_label: str | None = None, end_label: str | None = None, retrieved_before: datetime | None = None) -> pd.DataFrame

Query cumulative scalar observations with latest-observed row revisions.

query_series_page(series_id: str, *, start_label: str | None = None, end_label: str | None = None, retrieved_before: datetime | None = None, limit: int = 100, offset: int = 0, sort_by: str | None = None, descending: bool = False) -> StoredPage

Query one bounded cumulative scalar-series page with an exact filtered total.

query_vintage_series(series_id: str, *, start_label: str | None = None, end_label: str | None = None, available_on: date | None = None, retrieved_before: datetime | None = None) -> pd.DataFrame

Query cumulative provider vintages with latest-observed row revisions.

query_vintage_series_page(series_id: str, *, start_label: str | None = None, end_label: str | None = None, available_on: date | None = None, retrieved_before: datetime | None = None, limit: int = 100, offset: int = 0, sort_by: str | None = None, descending: bool = False) -> StoredPage

Query one bounded cumulative vintage page with an exact filtered total.

query_vintage_dates(provider_series: str, *, retrieved_before: datetime | None = None) -> pd.DataFrame

Query cumulative release dates through one retrieval-time cutoff.

query_quote_history(*, provider: str | None = None, symbol: str | None = None, observed_start: datetime | None = None, observed_end: datetime | None = None, retrieved_start: datetime | None = None, retrieved_end: datetime | None = None) -> pd.DataFrame

Return chronological retained quote revisions and recurrence counts.

query_top_of_book_history(*, provider: str | None = None, symbol: str | None = None, observed_start: datetime | None = None, observed_end: datetime | None = None, retrieved_start: datetime | None = None, retrieved_end: datetime | None = None) -> pd.DataFrame

Return chronological retained top-of-book revisions and recurrence counts.

query_option_snapshots(underlying_instrument_id: str, *, provider: str | None = None, chain_date: date | None = None, expiration: date | None = None, strike: float | None = None, option_type: str | None = None, retrieved_before: datetime | None = None) -> tuple[StoredOptionSnapshot, ...]

Return filtered option-chain occurrences in retrieval order.

diff_snapshots(before_snapshot_id: str, after_snapshot_id: str) -> SnapshotDiff

Compare two exact snapshots without exposing serialized payloads.

ProjectError

Bases: PersistraError, ValueError

Raised when a project manifest or layout operation fails.

_ProjectDependency dataclass

_CreatedResource dataclass

PersistraProject dataclass

A validated version-1 project rooted at an explicit directory.

store_path: Path property

Return the fixed primary normalized-store path.

raw_cache_directory: Path property

Return the fixed raw provider-response cache directory.

research_artifact_directory: Path property

Return the fixed research artifact directory.

trading_engine_artifact_directory: Path property

Return the fixed Trading Engine replay artifact directory.

notebook_directory: Path property

Return the fixed caller-owned notebook directory.

open(root: str | Path) -> Self classmethod

Open and strictly validate a project manifest without creating paths.

file_identity(path: Path) -> FileIdentity

Return the device and inode identity of one path without following symlinks.

validate_project(root: str | Path) -> ProjectValidation

Validate exactly one project directory without searching or changing it.

create_project(root: str | Path, *, name: str | None = None) -> PersistraProject

Create one complete standard project or restore the preexisting target state.

_preflight_target(target: Path) -> bool

_preflight_generated_paths(target: Path, relatives: tuple[Path, ...]) -> None

_make_directory(path: Path, created: list[_CreatedResource], *, mode: int = 511) -> None

_write_exclusive(path: Path, content: str, created: list[_CreatedResource]) -> None

_track_created(path: Path, created: list[_CreatedResource], *, directory: bool, identity: FileIdentity | None = None) -> None

_track_existing(path: Path, created: list[_CreatedResource], *, directory: bool, failure: BaseException | None = None) -> None

_store_artifact_paths(path: Path) -> tuple[Path, ...]

_track_store_artifacts(store_path: Path, created: list[_CreatedResource], failure: BaseException | None = None) -> None

_publish_store(staging_path: Path, final_path: Path, created: list[_CreatedResource]) -> None

_track_published_store(path: Path, identity: FileIdentity, created: list[_CreatedResource], failure: BaseException | None = None) -> None

_rollback(created: list[_CreatedResource]) -> list[str]

_normalize_name(name: str) -> str

_installed_dependency() -> _ProjectDependency

_dependency_range(installed_version: str) -> str

_installed_local_source(installed: Distribution) -> tuple[Path | None, bool]

_parse_manifest(text: str, *, source: Path) -> str

_project_files(name: str, dependency: _ProjectDependency) -> dict[Path, str]

_manifest(name: str) -> str

_pyproject(name: str, dependency: _ProjectDependency) -> str

_source_table(dependency: _ProjectDependency) -> str

_main_script() -> str

_test_script(name: str) -> str

_readme(name: str) -> str

_gitignore() -> str

Project errors

Project and manifest failures raise persistra.errors.ProjectError.

Validation diagnostics

persistra.validation

Stable diagnostics shared by read-only validators.

__all__ = ['ValidationFinding', 'ValidationSeverity'] module-attribute

_CODE = re.compile('^[a-z][a-z0-9]*(?:[._][a-z0-9]+)+$') module-attribute

ValidationSeverity

Bases: StrEnum

Severity of one validation finding.

ValidationFinding dataclass

One stable, deterministic validation diagnostic.

to_dict() -> dict[str, object]

Return the version-neutral JSON representation of this finding.