Data Reference

OHLCV data providers, caching, and resampling utilities.

Back to API Reference

Market data contracts, adapters, and cache helpers.

BarsCache

Simple parquet cache for Bars DataFrames.

__init__

__init__(root: Path | str, *, ttl: timedelta | int | float | None = None, offline: bool = False) -> None

Create a cache rooted at root.

write

write(engine: str, symbol: str, freq: str, bars: DataFrame, *, now: Timestamp | datetime | str | None = None) -> CacheEntry

Write Bars data and sidecar metadata.

read

read(engine: str, symbol: str, freq: str, *, ttl: timedelta | int | float | None = None, offline: bool | None = None, now: Timestamp | datetime | str | None = None) -> pd.DataFrame

Read cached Bars data and restore attrs.

fingerprint

fingerprint(engine: str, symbol: str, freq: str) -> str

Return the cached fingerprint for one engine/symbol/frequency key.

exists

exists(engine: str, symbol: str, freq: str) -> bool

Return whether both parquet data and metadata exist for a cache key.

is_fresh

is_fresh(engine: str, symbol: str, freq: str, *, ttl: timedelta | int | float | None = None, now: Timestamp | datetime | str | None = None) -> bool

Return whether a cache entry exists and has not exceeded its TTL.

CacheEntry dataclass

Paths written for one cached Bars object.

CacheExpiredError

Raised when a requested Bars cache entry is stale in online mode.

CacheMissError

Raised when a requested Bars cache entry is missing.

DuckDBBarsBackend

Columnar Bars storage backed by DuckDB.

DuckDB is optional. Tests and custom integrations may inject a connection object with execute/register/unregister methods to avoid importing the package.

ensure_schema

ensure_schema() -> None

Create the Bars table if it does not exist.

write

write(bars: DataFrame, *, mode: str = 'append') -> None

Write contract-valid Bars rows into DuckDB.

read

read(*, symbols: str | list[str] | tuple[str, ...] | None = None, start: str | Timestamp | None = None, end: str | Timestamp | None = None, columns: list[str] | tuple[str, ...] | None = None, market: str | None = None, freq: str | None = None) -> pd.DataFrame

Read Bars rows with optional symbol, date, and column filters.

read_cross_section

read_cross_section(timestamp: str | Timestamp, *, symbols: str | list[str] | tuple[str, ...] | None = None, columns: list[str] | tuple[str, ...] | None = None, market: str | None = None, freq: str | None = None) -> pd.DataFrame

Read one timestamp as a symbol-indexed cross section.

read_panel

read_panel(*, symbols: str | list[str] | tuple[str, ...] | None = None, start: str | Timestamp | None = None, end: str | Timestamp | None = None, columns: list[str] | tuple[str, ...] | None = None, market: str | None = None, freq: str | None = None) -> pd.DataFrame

Read a timestamp/symbol indexed Bars panel.

DataExplorer

Explore raw Bars-like market data before research or backtesting.

__init__

__init__(data: DataFrame) -> None

Create an explorer from a Bars contract frame or raw DataFrame.

summary

summary() -> dict[str, Any]

Return compact dataset-level diagnostics.

schema

schema() -> pd.DataFrame

Return dtype, missingness, and cardinality by column.

missing

missing() -> pd.DataFrame

Return columns sorted by missing value count.

describe

describe() -> pd.DataFrame

Return numeric descriptive statistics including skew and kurtosis.

ohlcv_quality

ohlcv_quality() -> pd.DataFrame

Return market-data-specific quality checks.

gaps

gaps() -> pd.DataFrame

Return observed timestamp gaps by symbol.

returns

returns(column: str = 'close') -> pd.Series

Return per-symbol percentage returns.

outliers

outliers(*, column: str = 'close', zscore: float = 4.0) -> pd.DataFrame

Return return outliers by absolute z-score.

correlation

correlation(column: str = 'close') -> pd.DataFrame

Return multi-symbol return correlation.

report

report(path: str | Path) -> Path

Write a standalone HTML data exploration report.

DataProvider

Protocol for OHLCV market data providers.

history_ohlc

history_ohlc(symbol: str | list[str] | tuple[str, ...], *, start: str | None = None, end: str | None = None, freq: Frequency = '1d') -> pd.DataFrame

Fetch historical OHLCV bars.

TdxProvider

TDX-backed A-share OHLCV provider.

__init__

__init__(*, host: str | None = None, port: int = 7709, timeout: float = 5.0, count: int = 800, client_factory: Callable[[], object] | None = None) -> None

Create a provider with optional TDX client injection.

history_ohlc

history_ohlc(symbol: str | list[str] | tuple[str, ...], *, start: str | None = None, end: str | None = None, freq: Frequency = '1d') -> pd.DataFrame

Fetch A-share OHLCV data and return contract-valid Bars.

TradingViewProvider

tvdatafeed-backed OHLCV provider.

history_ohlc

history_ohlc(symbol: str | list[str] | tuple[str, ...], *, start: str | None = None, end: str | None = None, freq: Frequency = '1d', exchange: str | None = None) -> pd.DataFrame

Fetch TradingView OHLCV data and return contract-valid Bars.