Skip to content

Providers

Structural provider protocols

base

Structural protocols implemented by community provider adapters.

MarketNotFoundError

Bases: LookupError

A provider catalog has no exact match for a normalized symbol.

MarketDataProvider

Bases: HistoricalBarProvider, MarketCatalogProvider, Protocol

Catalog plus historical bars required by the backtest harness.

Registry and third-party entry points

ProviderFactory

Bases: Protocol

ProviderRegistry 

ProviderRegistry(*, include_builtin: bool = True)

Resolve built-ins and externally installed provider factories by name.

register 

register(
    name: str,
    factory: ProviderFactory,
    *,
    replace: bool = False,
) -> None

Register an in-process provider factory.

create 

create(
    name: str,
    venue: str,
    *,
    config: Mapping[str, object] | None = None,
) -> MarketDataProvider

Create one provider bound to a venue or broker environment.

names 

names() -> tuple[str, ...]

List built-in, registered, and advertised provider names.

ProviderRegistryError

Bases: RuntimeError

A provider factory cannot be registered or loaded.

ProviderNotFoundError

Bases: ProviderRegistryError

No built-in or installed provider has the requested name.

create_provider 

create_provider(
    name: str,
    venue: str,
    *,
    config: Mapping[str, object] | None = None,
) -> MarketDataProvider

Create a provider from the process-wide registry.

Runtime tabular mapping

TimestampUnit

Bases: StrEnum

Storage unit used by numeric timestamps.

SourceColumn dataclass 

SourceColumn(
    name: str,
    data_type: str = "",
    nullable: bool | None = None,
)

One column discovered from a file header or database reflection.

BarColumnMapping dataclass 

BarColumnMapping(
    timestamp: str,
    open: str,
    high: str,
    low: str,
    close: str,
    volume: str,
    symbol: str | None = None,
    timeframe: str | None = None,
)

Map canonical PineForge bar fields to arbitrary source column names.

columns property 

columns: tuple[str, ...]

Return mapped source columns in canonical order without duplicates.

infer classmethod 

infer(
    columns: Sequence[str],
    overrides: Mapping[str, str] | None = None,
) -> BarColumnMapping

Infer common OHLCV names while requiring explicit ambiguous choices.

validate 

validate(columns: Sequence[str]) -> None

Require every selected name to exist in the reflected source schema.

TabularSchema dataclass 

TabularSchema(
    source: str, columns: tuple[SourceColumn, ...]
)

Runtime description of a user-owned file, table, or view.

infer_bar_mapping 

infer_bar_mapping(
    overrides: Mapping[str, str] | None = None,
) -> BarColumnMapping

Build a validated mapping from reflected columns and optional overrides.

TabularBarProvider 

TabularBarProvider(
    *,
    venue: str,
    mapping: ColumnMappingInput = None,
    timestamp_unit: TimestampUnit | str = MILLISECONDS,
    timestamp_timezone: str = "UTC",
    instrument: Instrument | None = None,
    timeframe: str | None = None,
)

Bases: ABC

Common catalog and OHLCV behavior for schema-mapped tabular sources.

inspect_schema async 

inspect_schema() -> TabularSchema

Reflect columns without reading or normalizing the full dataset.

fetch_bars async 

fetch_bars(request: BarRequest) -> Sequence[Bar]

Read, validate, sort, and normalize bars for one exact request.

SchemaMappingError

Bases: TabularDataError

Source columns cannot be mapped unambiguously to OHLCV fields.

TabularDataError

Bases: RuntimeError

A user-owned tabular source cannot be normalized safely.

Built-in providers

CcxtProvider 

CcxtProvider(
    exchange_id: str,
    *,
    config: Mapping[str, object] | None = None,
    exchange: _AsyncCcxtExchange | None = None,
    page_limit: int = 1000,
    poll_interval_ms: int = 1000,
    dedup_window: int = 10000,
    reload_markets: bool = False,
    market_params: Mapping[str, object] | None = None,
    ohlcv_params: Mapping[str, object] | None = None,
    trade_params: Mapping[str, object] | None = None,
)

Normalize one CCXT exchange into PineForge bars and trade ticks.

Instrument.symbol must use CCXT's unified symbol spelling, for example BTC/USDT. The adapter owns exchanges it constructs and leaves injected exchanges open, which keeps tests and shared CCXT clients composable.

list_markets async 

list_markets(
    query: MarketQuery | None = None,
) -> Sequence[MarketListing]

Load and normalize every market advertised by this CCXT exchange.

resolve_market async 

resolve_market(symbol: str) -> MarketListing

Resolve one exact CCXT unified symbol into normalized market metadata.

fetch_bars async 

fetch_bars(request: BarRequest) -> Sequence[Bar]

Fetch paginated, deduplicated, confirmed OHLCV bars.

stream_trades async 

stream_trades(
    subscription: TradeSubscription,
) -> AsyncIterator[TradeTick]

Poll CCXT public trades and emit a strictly ordered local sequence.

close async 

close() -> None

Close an exchange constructed by this provider.

CsvBarProvider 

CsvBarProvider(
    path: str | Path,
    *,
    venue: str = "local",
    mapping: ColumnMappingInput = None,
    timestamp_unit: TimestampUnit | str = MILLISECONDS,
    timestamp_timezone: str = "UTC",
    instrument: Instrument | None = None,
    timeframe: str | None = None,
    encoding: str = "utf-8-sig",
    delimiter: str = ",",
)

Bases: TabularBarProvider

Read historical bars from a local CSV file with a runtime column mapping.

SqliteBarProvider 

SqliteBarProvider(
    path: str | Path,
    table: str,
    *,
    venue: str = "local",
    mapping: ColumnMappingInput = None,
    timestamp_unit: TimestampUnit | str = MILLISECONDS,
    timestamp_timezone: str = "UTC",
    instrument: Instrument | None = None,
    timeframe: str | None = None,
)

Bases: TabularBarProvider

Read historical bars from one SQLite table or view in read-only mode.

SqlAlchemyBarProvider 

SqlAlchemyBarProvider(
    url: str,
    table: str,
    *,
    venue: str = "database",
    schema: str | None = None,
    mapping: ColumnMappingInput = None,
    timestamp_unit: TimestampUnit | str = MILLISECONDS,
    timestamp_timezone: str = "UTC",
    instrument: Instrument | None = None,
    timeframe: str | None = None,
    engine_options: Mapping[str, object] | None = None,
)

Bases: TabularBarProvider

Reflect and query one table or view through a synchronous SQLAlchemy engine.

Provider errors

CcxtError

Bases: RuntimeError

Base error raised by the CCXT adapter.

CcxtDependencyError

Bases: CcxtError

The optional CCXT dependency is unavailable.

CcxtCapabilityError

Bases: CcxtError

The configured exchange lacks a required unified method.

CcxtDataError

Bases: CcxtError

CCXT returned a record that cannot be normalized safely.

SqlAlchemyDependencyError

Bases: RuntimeError

SQLAlchemy support was requested without the optional dependency.