Data Sources¶

Data Source¶

class lumibot.data_sources.data_source.DataSource(api_key: str | None = None, delay: int | None = None, tzinfo=None, **kwargs)¶

Bases: ABC

DEFAULT_PYTZ = <DstTzInfo 'America/New_York' LMT-1 day, 19:04:00 STD>¶

DEFAULT_TIMEZONE = 'America/New_York'¶

IS_BACKTESTING_DATA_SOURCE = False¶

MIN_TIMESTEP = 'minute'¶

SOURCE = ''¶

TIMESTEP_MAPPING = []¶

calculate_greeks(asset, asset_price: float, underlying_price: float, risk_free_rate: float)¶: Returns Greeks in backtesting.

static convert_timestep_str_to_timedelta(timestep)¶

Convert a timestep string to a timedelta object. For example, “1minute” will be converted to a timedelta of 1 minute.

Parameters:

timestep (str) – The timestep string to convert. For example, “1minute” or “1hour” or “1day”.

Returns:

timedelta – A timedelta object representing the timestep.
unit (str) – The unit of the timestep. For example, “minute” or “hour” or “day”.

get_bars(assets, length, timestep='minute', timeshift=None, chunk_size=2, max_workers=2, quote=None, exchange=None, include_after_hours=True, sleep_time: float | None = None)¶: Get bars for the list of assets

get_chain_full_info(asset: ~lumibot.entities.asset.Asset, expiry: ~datetime.date | ~datetime.datetime, chains=None, underlying_price=<class 'float'>, risk_free_rate=<class 'float'>, strike_min=None, strike_max=None) → DataFrame¶

Get the full chain information for an option asset, including: greeks, bid/ask, open_interest, etc. For brokers that do not support this, greeks will be calculated locally. For brokers like Tradier this function is much faster as only a single API call can be done to return the data for all options simultaneously.

Parameters:

asset (Asset) – The option asset to get the chain information for.
expiry (datetime.date | datetime.datetime) – The expiry date of the option chain.
chains (dict) – The chains dictionary created by get_chains method. This is used to get the list of strikes needed to calculate the greeks.
underlying_price (float) – Price of the underlying asset.
risk_free_rate (float) – The risk-free rate used in interest calculations.
strike_min (float) – The minimum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.
strike_max (float) – The maximum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.

Returns:

A DataFrame containing the full chain information for the option asset. Greeks columns will be named as ‘greeks.delta’, ‘greeks.theta’, etc.

Return type:

pd.DataFrame

abstract get_chains(asset: Asset, quote: Asset | None = None) → dict¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for

Returns:

Mapping with keys such as Multiplier (e.g. "100") and Chains. Chains is a nested dictionary where expiration dates map to strike lists, e.g. chains['Chains']['CALL']['2023-07-31'] = [strike1, strike2, ...].

Return type:

dict

get_datetime(adjust_for_delay=False)¶

Returns the current datetime in the default timezone

Parameters:: adjust_for_delay (bool) – Whether to adjust the current time for the delay. This is useful for paper trading data sources that provide delayed data.
Return type:: datetime

get_datetime_range(length, timestep='minute', timeshift=None)¶

abstract get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, **kwargs) → Bars¶

Get bars for a given asset, going back in time from now, getting length number of bars by timestep. For example, with a length of 10 and a timestep of “day”, and no timeshift, this would return the last 10 daily bars.

Higher-level method that returns a Bars object
Handles timezone conversions automatically
Includes additional metadata and processing
Preferred for strategy development and backtesting
Returns normalized data with consistent format across data sources

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. Accepts “day” “hour” or “minute”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.
return_polars (bool (deprecated)) – Deprecated. Do not use in strategy code. This keyword will be removed in a future release. Strategy logic should use pandas operations on bars.pandas_df and should not depend on the underlying DataFrame backend.

Returns:

The bars for the asset. For strategy code, prefer bars.pandas_df for a pandas DataFrame.

Return type:

Bars

get_last_day()¶

get_last_minute()¶

abstract get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None)¶: Takes a list of assets and returns the last known prices

get_quote(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → Quote¶

Get the latest quote for an asset (stock, option, or crypto). Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information, eg. bid, ask, etc.

Return type:

Quote

get_round_day(timeshift=0)¶

Returns the current datetime rounded to the day and applies a timeshift in days :param timeshift: The number of days to shift the datetime by :type timeshift: int

Returns:: Rounded datetime with the timeshift applied
Return type:: datetime

get_round_minute(timeshift=0)¶

Returns the current datetime rounded to the minute and applies a timeshift in minutes :param timeshift: The number of minutes to shift the datetime by :type timeshift: int

Returns:: Rounded datetime with the timeshift applied
Return type:: datetime

get_strikes(asset) → list¶: Return a set of strikes for a given asset

get_timestamp()¶: Returns the current timestamp in the default timezone :rtype: float

get_timestep()¶

get_yesterday_dividend(asset, quote=None)¶: Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)¶

Return dividend per share for a list of assets for the day before.

For backtesting, this method caches all dividend data to avoid repeated API calls. On the first call for an asset, it fetches ALL historical dividend data and caches it. Subsequent calls use the cache.

localize_datetime(dt)¶

option_quote_fallback_allowed = False¶

query_greeks(asset)¶: Query for the Greeks as it can be more accurate than calculating locally.

shutdown()¶: Cleanup thread pool resources

to_default_timezone(dt)¶

Pandas¶

class lumibot.data_sources.pandas_data.PandasData(*args, pandas_data=None, auto_adjust=True, allow_option_quote_fallback: bool = False, **kwargs)¶

Bases: DataSourceBacktesting

PandasData is a Backtesting-only DataSource that uses a Pandas DataFrame (read from CSV) as the source of data for a backtest run. It is not possible to use this class to run a live trading strategy.

PREFER_NATIVE_DAY_BARS_FOR_STOCK_INDEX = False¶

SOURCE = 'PANDAS'¶

TIMESTEP_MAPPING = [{'representations': ['1D', 'day'], 'timestep': 'day'}, {'representations': ['1M', 'minute'], 'timestep': 'minute'}]¶

clean_trading_times(dt_index, pcal)¶

Fill gaps within trading days using the supplied market calendar.

Parameters:

dt_index (pandas.DatetimeIndex) – Original datetime index.
pcal (pandas.DataFrame) – Calendar with market_open and market_close columns indexed by date.

Returns:

Cleaned index with one-minute frequency during market hours.

Return type:

pandas.DatetimeIndex

find_asset_in_data_store(asset, quote=None, timestep=None)¶

get_asset_by_name(name)¶

get_asset_by_symbol(symbol, asset_type=None)¶

Finds the assets that match the symbol. If type is specified finds the assets matching symbol and type.

Parameters:

symbol (str) – The symbol of the asset.
asset_type (str) – Asset type. One of: - stock - future - option - forex

Return type:

list of Asset

get_assets()¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Returns option chains.

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset object) – The stock whose option chain is being fetched. Represented as an asset object.
quote (Asset object, optional) – The quote asset. Default is None.
exchange (str, optional) – The exchange to fetch the option chains from. For PandasData, will only use “SMART”.

Returns:

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str | None = None, timeshift: int | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False)¶: Get bars for a given asset

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None, **kwargs)¶: Takes a list of assets and returns the last known prices

get_quote(asset, quote=None, exchange=None) → Quote¶

Get the latest quote for an asset. Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information.

Return type:

Quote

get_start_datetime_and_ts_unit(length, timestep, start_dt=None, start_buffer=datetime.timedelta(days=5))¶

Get the start datetime for the data.

Parameters:

length (int) – The number of data points to get.
timestep (str) – The timestep to use. For example, “1minute” or “1hour” or “1day”.

Returns:

datetime – The start datetime.
str – The timestep unit.

get_trading_days_pandas()¶

get_yesterday_dividend(asset, quote=None)¶: Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)¶

Return dividend per share for a list of assets for the day before.

load_data()¶

update_date_index()¶

Yahoo¶

class lumibot.data_sources.yahoo_data.YahooData(auto_adjust=False, datetime_start=None, datetime_end=None, **kwargs)¶

Bases: DataSourceBacktesting

MIN_TIMESTEP = 'day'¶

SOURCE = 'YAHOO'¶

TIMESTEP_MAPPING = [{'representations': ['1d', 'day'], 'timestep': 'day'}, {'representations': ['15m', '15 minutes'], 'timestep': '15 minutes'}, {'representations': ['1m', '1 minute'], 'timestep': 'minute'}]¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Get the chains for a given asset. This is not implemented for YahooData becuase Yahoo does not support historical options data.

yfinance module does support getting some of the info for current options chains, but it is not implemented. See yf methods: >>> import yfinance as yf >>> spy = yf.Ticker(“SPY”) >>> expirations = spy.options >>> chain_data = spy.option_chain()

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True)¶: Get bars for a given asset

get_last_price(asset, timestep=None, quote=None, exchange=None, **kwargs) → float | Decimal | None¶: Takes an asset and returns the last known price

get_strikes(asset)¶: Return a set of strikes for a given asset

Module contents¶

Data source package exports without importing every provider backend.

class lumibot.data_sources.AlpacaData(config: dict, max_workers: int = 20, chunk_size: int = 100, delay: int | None = None, tzinfo: timezone | None = None, remove_incomplete_current_bar: bool = False, **kwargs)¶

Bases: DataSource

LUMIBOT_DEFAULT_QUOTE_ASSET = USD¶: Common base class for data_sources/alpaca and brokers/alpaca

MIN_TIMESTEP = 'minute'¶

SOURCE = 'ALPACA'¶

TIMESTEP_MAPPING = [{'representations': [alpaca.data.timeframe.TimeFrame.Minute, 'minute'], 'timestep': 'minute'}, {'representations': [['5alpaca.data.timeframe.TimeFrame.Minute', 'minute']], 'timestep': '5 minutes'}, {'representations': [['10alpaca.data.timeframe.TimeFrame.Minute', 'minute']], 'timestep': '10 minutes'}, {'representations': [['15alpaca.data.timeframe.TimeFrame.Minute', 'minute']], 'timestep': '15 minutes'}, {'representations': [['30alpaca.data.timeframe.TimeFrame.Minute', 'minute']], 'timestep': '30 minutes'}, {'representations': [['alpaca.data.timeframe.TimeFrame.Hour', 'hour']], 'timestep': 'hour'}, {'representations': [['alpaca.data.timeframe.TimeFrame.Hour', 'hour']], 'timestep': '1 hour'}, {'representations': [['2alpaca.data.timeframe.TimeFrame.Hour', 'hour']], 'timestep': '2 hours'}, {'representations': [['4alpaca.data.timeframe.TimeFrame.Hour', 'hour']], 'timestep': '4 hours'}, {'representations': [alpaca.data.timeframe.TimeFrame.Day, 'day'], 'timestep': 'day'}]¶

get_bars(assets: List[Asset | str | tuple], length: int, timestep: str = 'minute', timeshift: timedelta | None = None, chunk_size: int = 1000, max_workers: int = 1, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, sleep_time: float = 0.0) → Dict[Asset, Bars]¶

Fetch historical bars for multiple assets using Alpaca’s multi-symbol API.

This override batches symbols per asset class (stocks, options, crypto) and performs one request per class (with chunking if needed), dramatically reducing HTTP overhead compared to the threaded single-symbol approach in the base DataSource.

Parameters mirror the base class; unsupported parameters are accepted for compatibility. Returns a dict mapping the original Asset objects to Bars objects.

get_chains(asset: Asset) → dict¶

Get the options chain for the given asset.

Parameters:

asset (Asset) – The asset to get the chain data for.

Returns:

chains – A dictionary containing the chain data in lumibot format: {

”Chains”: {

“PUT”: {
“2025-01-17”: [560, 565, 570, …], “2025-01-24”: [560, 565, 570, …],

}, “CALL”: {

”2025-01-17”: [560, 565, 570, …], “2025-01-24”: [560, 565, 570, …],

}

}

}

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str = '', timeshift: timedelta | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False) → Bars | None¶: Get bars for a given asset

get_last_price(asset, quote=None, exchange=None, **kwargs) → float | Decimal | None¶: Get the last price for an asset by calling get_quote and returning the last price.

get_quote(asset: Asset, quote: Asset | None = None, exchange=None) → Quote¶: Get the latest quote for an asset (stock, option, or crypto). Returns a Quote object with bid, ask, last, and other fields if available.

query_greeks(asset: Asset)¶: Get the option greeks for an option asset via Alpaca Market Data API. Returns a dict mapping greek names to float values, e.g., {‘delta’: …, ‘gamma’: …, ‘theta’: …, ‘vega’: …, ‘rho’: …}.

reset_auth_failure()¶: Reset the authentication failure state and clear cached clients. This allows the data source to retry authentication after a failure.

class lumibot.data_sources.AlphaVantageData(config=None, auto_adjust=True, **kwargs)¶

Bases: DataSource

DATA_STALE_AFTER = datetime.timedelta(days=1)¶

MIN_TIMESTEP = 'minute'¶

SOURCE = 'ALPHA_VANTAGE'¶

get_chains(asset: Asset, quote: Asset | None = None, exchange=None)¶: AlphaVantage does not support options chains

class lumibot.data_sources.BitunixData(config: dict, max_workers: int = 1, chunk_size: int = 100, tzinfo: timezone | None = None)¶

Bases: DataSource

MIN_TIMESTEP = 'minute'¶

SOURCE = 'BITUNIX'¶

TIMESTEP_MAPPING = [{'representations': ['1', '1m', 'minute'], 'timestep': 'minute'}, {'representations': ['3', '3m'], 'timestep': '3 minutes'}, {'representations': ['5', '5m'], 'timestep': '5 minutes'}, {'representations': ['15', '15m'], 'timestep': '15 minutes'}, {'representations': ['30', '30m'], 'timestep': '30 minutes'}, {'representations': ['60', '60m', '1h', 'hour'], 'timestep': 'hour'}, {'representations': ['120', '120m', '2h'], 'timestep': '2 hours'}, {'representations': ['240', '240m', '4h'], 'timestep': '4 hours'}, {'representations': ['D', '1d', 'day'], 'timestep': 'day'}]¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None, strike_count: int = 100) → dict¶: Option chains not supported by BitUnix.

get_historical_prices(asset: Asset, length: int, timestep: str = '', timeshift=None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True) → Bars | None¶

Higher-level method that returns a Bars object
Handles timezone conversions automatically
Includes additional metadata and processing
Preferred for strategy development and backtesting
Returns normalized data with consistent format across data sources

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. Accepts “day” “hour” or “minute”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.
return_polars (bool (deprecated)) – Deprecated. Do not use in strategy code. This keyword will be removed in a future release. Strategy logic should use pandas operations on bars.pandas_df and should not depend on the underlying DataFrame backend.

Returns:

The bars for the asset. For strategy code, prefer bars.pandas_df for a pandas DataFrame.

Return type:

Bars

get_last_price(asset: Asset, quote: Asset = USDT, **kwargs) → float | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_timestep_from_string(timestep: str) → str¶: Maps a string representation of a timestep to the normalized timestep.

class lumibot.data_sources.CcxtBacktestingData(*args, auto_adjust: bool = False, **kwargs)¶

Bases: DataSourceBacktesting

Use CcxtCacheDB to download and cache data.

MIN_TIMESTEP = 'day'¶

SOURCE = 'CCXT'¶

TIMESTEP_MAPPING = [{'representations': ['1m'], 'timestep': 'minute'}, {'representations': ['1d'], 'timestep': 'day'}]¶

get_chains(asset)¶: Get the chains for a given asset. This is not implemented for BinanceData becuase Yahoo does not support historical options data.

get_historical_prices(asset: tuple[Asset, Asset], length: int, timestep: str | None = None, timeshift: int | None = None, quote: Asset | None = None, exchange: Any | None = None, include_after_hours: bool = True) → Bars¶: Get bars for a given asset

get_historical_prices_between_dates(asset: tuple[Asset, Asset], timestep: str = 'minute', quote: Asset | None = None, exchange: Any | None = None, include_after_hours: bool = True, start_date: datetime | None = None, end_date: datetime | None = None) → Bars¶

get_last_price(asset, timestep=None, quote=None, exchange=None, **kwargs) → float | Decimal | None¶: Takes an asset and returns the last known price of close

get_strikes(asset)¶: Return a set of strikes for a given asset

class lumibot.data_sources.CcxtData(config, max_workers=20, chunk_size=100, **kwargs)¶

Bases: DataSource

IS_BACKTESTING_DATA_SOURCE = False¶: Common base class for data_sources/ccxt and brokers/ccxt

MIN_TIMESTEP = 'minute'¶

SOURCE = 'CCXT'¶

TIMESTEP_MAPPING = [{'representations': ['1m'], 'timestep': 'minute'}, {'representations': ['1d'], 'timestep': 'day'}]¶

get_barset_from_api(api, symbol, freq, limit=None, end=None)¶

gets historical bar data for the given stock symbol and time params.

outputs a dataframe open, high, low, close columns and a UTC timezone aware index.

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for

Returns:

Return type:

dict

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars: bool = False)¶: Get bars for a given asset

get_last_price(asset, quote=None, exchange=None, **kwargs) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

lumibot.data_sources.DataBentoData¶: alias of DataBentoDataPolars

class lumibot.data_sources.DataBentoDataPandas(api_key: str, timeout: int = 30, max_retries: int = 3, **kwargs)¶

Bases: DataSource

DataBento data source for historical market data

This data source provides access to DataBento’s institutional-grade market data, with a focus on futures data and support for multiple asset types.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'DATABENTO'¶

TIMESTEP_MAPPING = [{'representations': ['1m', 'minute', '1 minute'], 'timestep': 'minute'}, {'representations': ['1h', 'hour', '1 hour'], 'timestep': 'hour'}, {'representations': ['1d', 'day', '1 day'], 'timestep': 'day'}]¶

get_chains(asset: Asset, quote: Asset | None = None) → dict¶

Get option chains for an asset

Note: DataBento primarily focuses on market data rather than options chains. This method returns an empty dict as DataBento doesn’t provide options chain data.

Parameters:

asset (Asset) – The asset to get option chains for
quote (Asset, optional) – Quote asset

Returns:

Empty dictionary as DataBento doesn’t provide options chains

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str = 'minute', timeshift: timedelta | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False) → Bars¶

Get historical price data for an asset

Parameters:

asset (Asset) – The asset to get historical prices for
length (int) – Number of bars to retrieve
timestep (str, optional) – Timestep for the data (‘minute’, ‘hour’, ‘day’), default ‘minute’
timeshift (timedelta, optional) – Time shift to apply to the data retrieval
quote (Asset, optional) – Quote asset (not used for DataBento)
exchange (str, optional) – Exchange/venue filter
include_after_hours (bool, optional) – Whether to include after-hours data, default True

Returns:

Historical price data as Bars object

Return type:

Bars

get_last_price(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → float | Decimal | None¶

Get the last known price for an asset

Parameters:

asset (Asset) – The asset to get the last price for
quote (Asset, optional) – Quote asset (not used for DataBento)
exchange (str, optional) – Exchange/venue filter

Returns:

Last known price of the asset

Return type:

float, Decimal, or None

get_quote(asset: Asset, quote: Asset | None = None) → float | Decimal | None¶

Get current quote for an asset

For DataBento, this returns the last known price since real-time quotes may not be available for all assets.

Parameters:

asset (Asset) – The asset to get the quote for
quote (Asset, optional) – Quote asset (not used for DataBento)

Returns:

Current quote/last price of the asset

Return type:

float, Decimal, or None

class lumibot.data_sources.DataBentoDataPolars(api_key: str, has_paid_subscription: bool = False, enable_cache: bool = True, cache_duration_minutes: int = 60, enable_live_stream: bool = True, timeout: int | None = None, max_retries: int | None = None)¶

Bases: PolarsMixin, DataSource

DataBento data source optimized with Polars and proper Live API usage.

Uses Live API for real-time trade streaming to achieve <1 minute lag. Falls back to Historical API for older data.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'DATABENTO'¶

TIMESTEP_MAPPING = {'day': '1d', 'hour': '1h', 'minute': '1m'}¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → dict¶: Get option chains - not supported for futures

get_historical_prices(asset: Asset, length: int, timestep: str = 'minute', timeshift: timedelta | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False) → Bars | None¶: Get historical prices with live tail merge

get_last_price(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → float | None¶: Get the last price for an asset

get_quote(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → Quote¶

Get the latest quote for an asset (stock, option, or crypto). Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information, eg. bid, ask, etc.

Return type:

Quote

class lumibot.data_sources.DataSource(api_key: str | None = None, delay: int | None = None, tzinfo=None, **kwargs)¶

Bases: ABC

DEFAULT_PYTZ = <DstTzInfo 'America/New_York' LMT-1 day, 19:04:00 STD>¶

DEFAULT_TIMEZONE = 'America/New_York'¶

IS_BACKTESTING_DATA_SOURCE = False¶

MIN_TIMESTEP = 'minute'¶

SOURCE = ''¶

TIMESTEP_MAPPING = []¶

calculate_greeks(asset, asset_price: float, underlying_price: float, risk_free_rate: float)¶: Returns Greeks in backtesting.

static convert_timestep_str_to_timedelta(timestep)¶

Convert a timestep string to a timedelta object. For example, “1minute” will be converted to a timedelta of 1 minute.

Parameters:

timestep (str) – The timestep string to convert. For example, “1minute” or “1hour” or “1day”.

Returns:

timedelta – A timedelta object representing the timestep.
unit (str) – The unit of the timestep. For example, “minute” or “hour” or “day”.

get_bars(assets, length, timestep='minute', timeshift=None, chunk_size=2, max_workers=2, quote=None, exchange=None, include_after_hours=True, sleep_time: float | None = None)¶: Get bars for the list of assets

Parameters:

asset (Asset) – The option asset to get the chain information for.
expiry (datetime.date | datetime.datetime) – The expiry date of the option chain.
chains (dict) – The chains dictionary created by get_chains method. This is used to get the list of strikes needed to calculate the greeks.
underlying_price (float) – Price of the underlying asset.
risk_free_rate (float) – The risk-free rate used in interest calculations.
strike_min (float) – The minimum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.
strike_max (float) – The maximum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.

Returns:

A DataFrame containing the full chain information for the option asset. Greeks columns will be named as ‘greeks.delta’, ‘greeks.theta’, etc.

Return type:

pd.DataFrame

abstract get_chains(asset: Asset, quote: Asset | None = None) → dict¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for

Returns:

Return type:

dict

get_datetime(adjust_for_delay=False)¶

Returns the current datetime in the default timezone

Parameters:: adjust_for_delay (bool) – Whether to adjust the current time for the delay. This is useful for paper trading data sources that provide delayed data.
Return type:: datetime

get_datetime_range(length, timestep='minute', timeshift=None)¶

abstract get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, **kwargs) → Bars¶

Higher-level method that returns a Bars object
Handles timezone conversions automatically
Includes additional metadata and processing
Preferred for strategy development and backtesting
Returns normalized data with consistent format across data sources

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. Accepts “day” “hour” or “minute”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.
return_polars (bool (deprecated)) – Deprecated. Do not use in strategy code. This keyword will be removed in a future release. Strategy logic should use pandas operations on bars.pandas_df and should not depend on the underlying DataFrame backend.

Returns:

The bars for the asset. For strategy code, prefer bars.pandas_df for a pandas DataFrame.

Return type:

Bars

get_last_day()¶

get_last_minute()¶

abstract get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None)¶: Takes a list of assets and returns the last known prices

get_quote(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → Quote¶

Get the latest quote for an asset (stock, option, or crypto). Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information, eg. bid, ask, etc.

Return type:

Quote

get_round_day(timeshift=0)¶

Returns the current datetime rounded to the day and applies a timeshift in days :param timeshift: The number of days to shift the datetime by :type timeshift: int

Returns:: Rounded datetime with the timeshift applied
Return type:: datetime

get_round_minute(timeshift=0)¶

Returns the current datetime rounded to the minute and applies a timeshift in minutes :param timeshift: The number of minutes to shift the datetime by :type timeshift: int

Returns:: Rounded datetime with the timeshift applied
Return type:: datetime

get_strikes(asset) → list¶: Return a set of strikes for a given asset

get_timestamp()¶: Returns the current timestamp in the default timezone :rtype: float

get_timestep()¶

get_yesterday_dividend(asset, quote=None)¶: Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)¶

Return dividend per share for a list of assets for the day before.

localize_datetime(dt)¶

option_quote_fallback_allowed = False¶

query_greeks(asset)¶: Query for the Greeks as it can be more accurate than calculating locally.

shutdown()¶: Cleanup thread pool resources

to_default_timezone(dt)¶

Bases: DataSource, ABC

This class is the base class for all backtesting data sources. It is also an abstract class and should not be instantiated directly because it does not define all necessary methods. Instead, instantiate one of the child classes like PandasData.

IS_BACKTESTING_DATA_SOURCE = True¶

static estimate_requested_length(length=None, start_date=None, end_date=None, timestep='minute')¶: Infer the number of rows required to satisfy a backtest data request.

get_datetime(adjust_for_delay=False)¶

Get the current datetime of the backtest.

Parameters:: adjust_for_delay (bool) – Not used for backtesting data sources. This parameter is only used for live data sources.
Returns:: The current datetime of the backtest.
Return type:: datetime

get_datetime_range(length, timestep='minute', timeshift=None)¶

log_backtest_progress_to_csv(percent, elapsed, log_eta, portfolio_value, simulation_date=None, cash=None, total_return_pct=None, positions_json=None, orders_json=None)¶

Log backtest progress to CSV file.

Parameters:

percent (float) – Progress percentage (0-100)
elapsed (timedelta) – Time elapsed since backtest started
log_eta (timedelta) – Estimated time remaining
portfolio_value (str or float) – Current portfolio value
simulation_date (str, optional) – Current date/time in the backtest simulation (YYYY-MM-DD HH:MM:SS format)
cash (float, optional) – Current cash balance
total_return_pct (float, optional) – Running total return percentage
positions_json (str, optional) – JSON string of minimal position data from Position.to_minimal_dict(): [{“asset”: {“symbol”: “AAPL”, “type”: “stock”}, “qty”: 100, “val”: 15000.0, “pnl”: 500.0}, …]
orders_json (str, optional) – JSON string of minimal order data from Order.to_minimal_dict(): [{“asset”: {“symbol”: “AAPL”, “type”: “stock”}, “side”: “buy”, “qty”: 100, “type”: “market”, “status”: “new”}, …]

shutdown()¶: Cleanup any background resources (thread pools, progress heartbeat).

stop_progress_heartbeat() → None¶

class lumibot.data_sources.ExampleBrokerData(**kwargs)¶

Bases: DataSource

Data source that connects to the Example Broker API.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'ExampleBroker'¶

get_chains(asset: Asset, quote: Asset | None = None) → dict¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for

Returns:

Return type:

dict

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True) → Bars¶

Higher-level method that returns a Bars object
Handles timezone conversions automatically
Includes additional metadata and processing
Preferred for strategy development and backtesting
Returns normalized data with consistent format across data sources

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. Accepts “day” “hour” or “minute”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.
return_polars (bool (deprecated)) – Deprecated. Do not use in strategy code. This keyword will be removed in a future release. Strategy logic should use pandas operations on bars.pandas_df and should not depend on the underlying DataFrame backend.

Returns:

The bars for the asset. For strategy code, prefer bars.pandas_df for a pandas DataFrame.

Return type:

Bars

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_quote(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → Quote¶

Get the latest quote for an asset. This is a placeholder implementation that returns an empty Quote object.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information.

Return type:

Quote

class lumibot.data_sources.InteractiveBrokersData(config, max_workers=20, chunk_size=100, **kwargs)¶

Bases: DataSource

Make Interactive Brokers connection and gets data.

Create connection to Interactive Brokers market through either Gateway or TWS which must be running locally for connection to be made.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'InteractiveBrokers'¶

TIMESTEP_MAPPING = [{'representations': ['1 secs'], 'timestep': 'second'}, {'representations': ['1 min'], 'timestep': 'minute'}, {'representations': ['5 mins'], 'timestep': '5 minutes'}, {'representations': ['10 mins'], 'timestep': '10 minutes'}, {'representations': ['15 mins'], 'timestep': '15 minutes'}, {'representations': ['30 mins'], 'timestep': '30 minutes'}, {'representations': ['1 hour'], 'timestep': '1 hour'}, {'representations': ['2 hours'], 'timestep': '2 hours'}, {'representations': ['4 hours'], 'timestep': '4 hours'}, {'representations': ['1 day'], 'timestep': 'day'}]¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶: For InteractiveBrokers, this function is defined in the broker because the broker object has access to additional API calls that are not available in the data source object because of the way IBClient and IBWrapper are designed.

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars: bool = False)¶: Get bars for a given asset

get_last_price(asset, timestep=None, quote=None, exchange=None, **kwargs) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_quote(asset, quote=None, exchange=None) → Quote¶

This function returns the quote of an asset. The quote includes the bid and ask price.

Parameters:

asset (Asset) – The asset to get the quote for
quote (Asset) – The quote asset to get the quote for (currently not used for Interactive Brokers)
exchange (str) – The exchange to get the quote from

Returns:

Quote object containing bid, ask, price and other information

Return type:

Quote

get_yesterday_dividend(asset, quote=None)¶: Unavailable

get_yesterday_dividends(asset, quote=None)¶: Unavailable

class lumibot.data_sources.InteractiveBrokersRESTData(config, **kwargs)¶

Bases: DataSource

Data source that connects to the Interactive Brokers REST API.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'InteractiveBrokersREST'¶

delete_order(order)¶

delete_to_endpoint(url, description='', silent=False, allow_fail=True)¶

execute_order(order_data)¶

fetch_account_id()¶

get_account_balances()¶: Retrieves the account balances for a given account ID.

get_broker_all_orders()¶

get_chains(asset: Asset, quote=None) → dict¶

Multiplier (str) eg: 100
‘Chains’ - paired Expiration/Strike info to guarentee that the strikes are valid for the specific
expiration date. Format:

chains[‘Chains’][‘CALL’][exp_date] = [strike1, strike2, …]

Expiration Date Format: 2023-07-31

get_conid_from_asset(asset: Asset, exchange: str | None = None)¶

get_contract_details(conId)¶

get_contract_rules(conid)¶

Get the contract rules for a given contract ID (conid) and whether it is a buy or sell.

Parameters:

conid (int) – The contract ID.
isBuy (bool) – True if it is a buy order, False if it is a sell order.

Returns:

The contract rules if the request is successful, None otherwise.

Return type:

dict

get_from_endpoint(url, description='', silent=False, allow_fail=True)¶

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars: bool = False) → Bars¶

Get bars for a given asset

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. For example, “minute” or “day”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶: Get the last price for an asset. For futures, always use get_market_snapshot (the official IBKR endpoint for all asset types).

get_market_snapshot(asset: Asset, fields: list, exchange: str | None = None)¶

get_open_orders()¶

get_order_info(orderid)¶

get_positions()¶: Retrieves the current positions for a given account ID.

get_quote(asset, quote=None, exchange=None)¶

This function returns the quote of an asset. The quote includes the bid and ask price.

Parameters:

asset (Asset) – The asset to get the quote for.
quote (Asset, optional) – The quote asset to get the quote for (currently not used for Interactive Brokers).
exchange (str, optional) – The exchange to get the quote for (currently not used for Interactive Brokers).

Returns:

Quote object containing bid, ask, price and other information.

Return type:

Quote

handle_http_errors(response, silent, retries, description, allow_fail)¶

is_authenticated()¶

ping_iserver()¶

ping_portfolio()¶

post_to_endpoint(url, json: dict, description='', silent=False, allow_fail=True)¶

query_greeks(asset: Asset) → dict¶: Query for the Greeks as it can be more accurate than calculating locally.

start(ib_username, ib_password)¶

stop()¶

suppress_warnings()¶

exception lumibot.data_sources.NoDataFound(source, asset)¶: Bases: Exception

class lumibot.data_sources.PandasData(*args, pandas_data=None, auto_adjust=True, allow_option_quote_fallback: bool = False, **kwargs)¶

Bases: DataSourceBacktesting

PandasData is a Backtesting-only DataSource that uses a Pandas DataFrame (read from CSV) as the source of data for a backtest run. It is not possible to use this class to run a live trading strategy.

PREFER_NATIVE_DAY_BARS_FOR_STOCK_INDEX = False¶

SOURCE = 'PANDAS'¶

TIMESTEP_MAPPING = [{'representations': ['1D', 'day'], 'timestep': 'day'}, {'representations': ['1M', 'minute'], 'timestep': 'minute'}]¶

clean_trading_times(dt_index, pcal)¶

Fill gaps within trading days using the supplied market calendar.

Parameters:

dt_index (pandas.DatetimeIndex) – Original datetime index.
pcal (pandas.DataFrame) – Calendar with market_open and market_close columns indexed by date.

Returns:

Cleaned index with one-minute frequency during market hours.

Return type:

pandas.DatetimeIndex

find_asset_in_data_store(asset, quote=None, timestep=None)¶

get_asset_by_name(name)¶

get_asset_by_symbol(symbol, asset_type=None)¶

Finds the assets that match the symbol. If type is specified finds the assets matching symbol and type.

Parameters:

symbol (str) – The symbol of the asset.
asset_type (str) – Asset type. One of: - stock - future - option - forex

Return type:

list of Asset

get_assets()¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Returns option chains.

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset object) – The stock whose option chain is being fetched. Represented as an asset object.
quote (Asset object, optional) – The quote asset. Default is None.
exchange (str, optional) – The exchange to fetch the option chains from. For PandasData, will only use “SMART”.

Returns:

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str | None = None, timeshift: int | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False)¶: Get bars for a given asset

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None, **kwargs)¶: Takes a list of assets and returns the last known prices

get_quote(asset, quote=None, exchange=None) → Quote¶

Get the latest quote for an asset. Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information.

Return type:

Quote

get_start_datetime_and_ts_unit(length, timestep, start_dt=None, start_buffer=datetime.timedelta(days=5))¶

Get the start datetime for the data.

Parameters:

length (int) – The number of data points to get.
timestep (str) – The timestep to use. For example, “1minute” or “1hour” or “1day”.

Returns:

datetime – The start datetime.
str – The timestep unit.

get_trading_days_pandas()¶

get_yesterday_dividend(asset, quote=None)¶: Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)¶

Return dividend per share for a list of assets for the day before.

load_data()¶

update_date_index()¶

class lumibot.data_sources.PolarsData(*args, pandas_data=None, auto_adjust=True, allow_option_quote_fallback: bool = False, **kwargs)¶

Bases: DataSourceBacktesting

PolarsData is a Backtesting-only DataSource that will be optimized to use Polars DataFrames. Currently identical to PandasData as a baseline. Will be incrementally converted to use Polars.

SOURCE = 'POLARS'¶

TIMESTEP_MAPPING = [{'representations': ['1D', 'day'], 'timestep': 'day'}, {'representations': ['1M', 'minute'], 'timestep': 'minute'}]¶

clean_trading_times(dt_index, pcal)¶

Fill gaps within trading days using the supplied market calendar.

Parameters:

dt_index (pandas.DatetimeIndex) – Original datetime index.
pcal (pandas.DataFrame) – Calendar with market_open and market_close columns indexed by date.

Returns:

Cleaned index with one-minute frequency during market hours.

Return type:

pandas.DatetimeIndex

find_asset_in_data_store(asset, quote=None, timestep=None)¶: Locate the cache key for an asset, preferring timestep-aware keys but gracefully falling back to legacy (asset, quote) entries for backward compatibility.

get_asset_by_name(name)¶

get_asset_by_symbol(symbol, asset_type=None)¶

Finds the assets that match the symbol. If type is specified finds the assets matching symbol and type.

Parameters:

symbol (str) – The symbol of the asset.
asset_type (str) – Asset type. One of: - stock - future - option - forex

Return type:

list of Asset

get_assets()¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Returns option chains.

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset object) – The stock whose option chain is being fetched. Represented as an asset object.
quote (Asset object, optional) – The quote asset. Default is None.
exchange (str, optional) – The exchange to fetch the option chains from. For PandasData, will only use “SMART”.

Returns:

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str | None = None, timeshift: int | None = None, quote: Asset | None = None, exchange: str | None = None, include_after_hours: bool = True, return_polars: bool = False)¶: Get bars for a given asset

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None, **kwargs)¶: Takes a list of assets and returns the last known prices

get_quote(asset, quote=None, exchange=None) → Quote¶

Get the latest quote for an asset. Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

asset (Asset object) – The asset for which the quote is needed.
quote (Asset object, optional) – The quote asset for cryptocurrency pairs.
exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information.

Return type:

Quote

get_start_datetime_and_ts_unit(length, timestep, start_dt=None, start_buffer=datetime.timedelta(days=5))¶

Get the start datetime for the data.

Parameters:

length (int) – The number of data points to get.
timestep (str) – The timestep to use. For example, “1minute” or “1hour” or “1day”.

Returns:

datetime – The start datetime.
str – The timestep unit.

get_trading_days_pandas()¶

get_yesterday_dividend(asset, quote=None)¶: Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)¶

Return dividend per share for a list of assets for the day before.

load_data()¶

update_date_index()¶

class lumibot.data_sources.PolygonDataBacktesting(datetime_start, datetime_end, pandas_data=None, api_key=None, max_memory=None, **kwargs)¶

Bases: PandasData

Backtesting implementation of Polygon

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Integrates the Polygon client library into the LumiBot backtest for Options Data in the same structure as Interactive Brokers options chain data.

Parameters:

asset (Asset) – The underlying asset symbol. Typically an equity like “SPY” or “NVDA”.
quote (Asset, optional) – The quote asset to use, e.g. Asset(“USD”). (Usually unused for equities.)
exchange (str, optional) – The exchange to which the chain belongs (e.g., “SMART”).

Returns:

A dictionary of dictionaries describing the option chain.

Format: - “Multiplier”: int

e.g. 100

”Exchange”: str
e.g. “NYSE”
”Chains”: dict
Dictionary with “CALL” and “PUT” keys. Each key is itself a dictionary mapping expiration dates (YYYY-MM-DD) to a list of strikes.

Example

{

“Multiplier”: 100, “Exchange”: “NYSE”, “Chains”: {

”CALL”: {
“2023-07-31”: [100.0, 101.0, …], “2023-08-07”: […], …

}, “PUT”: {

”2023-07-31”: [100.0, 101.0, …], …

}

}

Return type:

dict

Notes

This function simply calls get_chains_cached() from polygon_helper, which may reuse recent chain data to speed up backtests.

get_historical_prices_between_dates(asset, timestep='minute', quote=None, exchange=None, include_after_hours=True, start_date=None, end_date=None)¶

get_last_price(asset, timestep='minute', quote=None, exchange=None, **kwargs) → float | Decimal | None¶

Takes an asset and returns the last known price

Parameters:

asset (Asset) – The asset to get the price of.
quote (Asset) – The quote asset to get the price of.
exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

option_quote_fallback_allowed = True¶

class lumibot.data_sources.ProjectXData(config: dict | None = None, **kwargs)¶

Bases: DataSource

ProjectX data source implementation for market data.

Provides historical data for futures contracts through ProjectX API. Supports multiple underlying brokers through ProjectX gateway.

Required Configuration: - PROJECTX_{FIRM}_API_KEY: API key for the broker - PROJECTX_{FIRM}_USERNAME: Username for the broker - PROJECTX_{FIRM}_PREFERRED_ACCOUNT_NAME: Account name (recommended)

Optional Configuration: - PROJECTX_FIRM: Explicitly specify firm (auto-detected if not set) - PROJECTX_{FIRM}_BASE_URL: Override default API URL - PROJECTX_{FIRM}_STREAMING_BASE_URL: Override default streaming URL

SOURCE = 'PROJECTX'¶

TIME_UNIT_MAPPING = {'day': 4, 'hour': 3, 'minute': 2, 'month': 6, 'second': 1, 'week': 5}¶

get_bars(assets, length, timestep='minute', timeshift=None, chunk_size=2, max_workers=2, quote=None, exchange=None, include_after_hours=True, sleep_time=0.1)¶: Override: return Bars directly only for continuous futures (CONT_FUTURE) single asset; else parent dict. This satisfies unit tests expecting Bars for continuous futures while keeping alias test expecting dict.

get_bars_from_datetime(asset: Asset, start_datetime: datetime, end_datetime: datetime, timespan: str = 'minute') → Bars¶

Get historical bars between specific datetime range.

Parameters:

asset – Asset to get bars for
start_datetime – Start datetime
end_datetime – End datetime
timespan – Time span for bars (minute, hour, day, week, month)

Returns:

Bars object containing the historical data

get_chains(asset: Asset) → Dict¶

Get options chains for an asset.

ProjectX is a futures broker, so options chains are not applicable. Raises NotImplementedError as futures don’t have options chains.

get_contract_details(asset: Asset) → dict¶

Get detailed contract information for an asset.

Parameters:: asset – Asset to get contract details for
Returns:: Dictionary containing contract details

get_historical_prices(asset: Asset, length: int, timestep: str = 'minute', timeshift=None, quote=None, exchange=None, include_after_hours=True) → Bars¶

Get historical prices for an asset.

Parameters:

asset – Asset to get prices for
length – Number of prices to retrieve
timestep – Time step for prices (minute, hour, day, week, month)
timeshift – Time shift for historical data
quote – Quote asset (not used for futures)
exchange – Exchange (not used)
include_after_hours – Whether to include after hours data (not used for futures)

Returns:

Bars object containing historical data

get_last_price(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → float¶

Get the last price for an asset.

Parameters:

asset – Asset to get price for
quote – Quote asset (not used for futures)
exchange – Exchange name (not used)

Returns:

Last price as float, or None if not available

get_quote(asset: Asset, quote: Asset | None = None, exchange: str | None = None) → Quote¶

Get current quote (bid/ask) for an asset.

Note: This is a basic implementation using last price. Real-time quote data would require streaming connection.

Parameters:

asset – Asset to get quote for
quote – Quote asset (for cryptocurrency pairs, not used in ProjectX)
exchange – Exchange to get quote from (not used in ProjectX)

Returns:

Quote object with quote information

get_yesterday_dividend(asset: Asset) → float¶

Get yesterday’s dividend for an asset.

ProjectX is a futures broker, so dividends are not applicable. Returns 0.0 as futures don’t have dividends.

search_contracts(search_text: str) → List[dict]¶

Search for contracts matching the given text.

Parameters:: search_text – Text to search for in contract symbols/names
Returns:: List of contract dictionaries

class lumibot.data_sources.SchwabData(client=None, api_key=None, secret=None, account_number=None, **kwargs)¶

Bases: DataSource

Data source that connects to the Schwab Broker API.

This class provides methods to fetch historical price data, option chains, and other information from the Schwab API. It requires a Schwab API client to be passed in during initialization.

Link to Schwab API documentation: https://developer.schwab.com/ and create an account to get API doc access. Link to the Python client library: https://schwab-py.readthedocs.io/en/latest/

MIN_TIMESTEP = 'minute'¶

SOURCE = 'Schwab'¶

convert_epoch_ms_to_datetime(epoch_ms)¶: Convert epoch milliseconds to datetime object with timezone info

convert_timestep_str_to_timedelta(timestep_str)¶

Convert a timestep string to a timedelta object.

Parameters:: timestep_str – String representing the timestep (e.g., ‘1minute’, ‘1day’)
Returns:: (timedelta object, timestep_unit string)
Return type:: tuple

static create_schwab_client(api_key=None, secret=None, account_number=None)¶

Create and return a Schwab client instance.

Parameters:

api_key (str) – Schwab API key
secret (str) – Schwab API secret
account_number (str) – Schwab account number

Returns:

Configured Schwab client or None if credentials are missing

Return type:

client

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None, strike_count: int = 100) → dict¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for
exchange (str | None) – The exchange to get the option chains for
strike_count (int) – Number of strikes to return above and below the at-the-money price (default: 10)

Returns:

Format: - Multiplier (str) eg: 100 - ‘Chains’ - paired Expiration/Strike info to guarantee that the strikes are valid for the specific

expiration date. Format:

chains[‘Chains’][‘CALL’][exp_date] = [strike1, strike2, …]

Expiration Date Format: 2023-07-31

Return type:

dictionary of dictionary

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars: bool = False) → Bars¶

Get historical price data for an asset from Schwab API.

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. For example, “minute” or “day”.
timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.

Returns:

Historical price data as a Bars object, or None if there was an error.

Return type:

Bars

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

Get the last price of an asset from Schwab API.

Parameters:

asset – The asset to get the price for
quote – The quote asset if applicable
exchange – The exchange if applicable

Returns:

The last price of the asset or None if it can’t be retrieved

get_quote(asset, quote=None, exchange=None) → Quote¶

This function returns the quote of an asset as a Quote object.

Parameters:

asset (Asset) – The asset to get the quote for
quote (Asset) – The quote asset to get the quote for (not currently used for Schwab)
exchange (str) – The exchange to get the quote for (not currently used for Schwab)

Returns:

Quote object containing detailed information about the asset

Return type:

Quote

set_client(client)¶

Set the client for this data source.

Parameters:: client – Schwab API client instance

class lumibot.data_sources.TradierData(account_number: str, access_token: str, paper: bool = True, max_workers: int = 20, delay: int | None = None, tzinfo: ~pytz.timezone = <DstTzInfo 'America/New_York' LMT-1 day, 19:04:00 STD>, remove_incomplete_current_bar: bool = False, **kwargs)¶

Bases: DataSource

MIN_TIMESTEP = 'minute'¶

SOURCE = 'Tradier'¶

TIMESTEP_MAPPING = [{'representations': ['tick'], 'timestep': 'tick'}, {'representations': ['minute'], 'timestep': 'minute'}, {'representations': ['daily'], 'timestep': 'day'}, {'representations': ['weekly'], 'timestep': 'week'}, {'representations': ['monthly'], 'timestep': 'month'}]¶

get_chain_full_info(asset: ~lumibot.entities.asset.Asset, expiry: str, chains=None, underlying_price=<class 'float'>, risk_free_rate=<class 'float'>, strike_min=None, strike_max=None) → DataFrame¶

Parameters:

asset (Asset) – The option asset to get the chain information for.
expiry (str | dt.datetime | dt.date) – The expiry date of the option chain.
chains (dict) – The chains dictionary created by get_chains method. This is used to get the list of strikes needed to calculate the greeks.
underlying_price (float) – Price of the underlying asset.
risk_free_rate (float) – The risk-free rate used in interest calculations.
strike_min (float) – The minimum strike price to return in the chain. If None, will return all strikes. This is not necessary for Tradier as all option data is returned in a single query.
strike_max (float) – The maximum strike price to return in the chain. If None, will return all strikes. This is not necessary for Tradier as all option data is returned in a single query.

Returns:

A DataFrame containing the full chain information for the option asset. Greeks columns will be named as ‘greeks.delta’, ‘greeks.theta’, etc.

Return type:

pd.DataFrame

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for
exchange (str | None) – The exchange to get the option chains for

Returns:

Format: - Multiplier (str) eg: 100 - ‘Chains’ - paired Expiration/Strike info to guarentee that the strikes are valid for the specific

expiration date. Format:

chains[‘Chains’][‘CALL’][exp_date] = [strike1, strike2, …]

Expiration Date Format: 2023-07-31

Return type:

dictionary of dictionary

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars: bool = False)¶

Get bars for a given asset

Parameters:

asset (Asset) – The asset to get the bars for.
length (int) – The number of bars to get.
timestep (str) – The timestep to get the bars at. Accepts “day” or “minute”.
timeshift (dt.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.
quote (Asset) – The quote asset to get the bars for.
exchange (str) – The exchange to get the bars for.
include_after_hours (bool) – Whether to include after hours data.

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶

This function returns the last price of an asset. :param asset: The asset to get the last price for :type asset: Asset :param quote: The quote asset to get the last price for (currently not used for Tradier) :type quote: Asset :param exchange: The exchange to get the last price for (currently not used for Tradier) :type exchange: str

Returns:: Price of the asset
Return type:: float or Decimal or none

get_quote(asset, quote=None, exchange=None) → Quote¶

This function returns the quote of an asset. :param asset: The asset to get the quote for :type asset: Asset :param quote: The quote asset to get the quote for (currently not used for Tradier) :type quote: Asset :param exchange: The exchange to get the quote for (currently not used for Tradier) :type exchange: str

Returns:: Quote object containing bid, ask, last price and other information
Return type:: Quote

query_greeks(asset: Asset)¶

This function returns the greeks of an option as reported by the Tradier API.

Parameters:: asset (Asset) – The option asset to get the greeks for.
Returns:: A dictionary containing the greeks of the option.
Return type:: dict

class lumibot.data_sources.TradovateData(config, trading_token=None, market_token=None)¶

Bases: DataSource

Data source that connects to the Tradovate Market Data API. Note: Tradovate market data is delivered via WebSocket.

MIN_TIMESTEP = 'minute'¶

SOURCE = 'Tradovate'¶

get_chains(asset: Asset, quote: Asset | None = None) → dict¶

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

asset (Asset) – The asset to get the option chains for
quote (Asset | None) – The quote asset to get the option chains for

Returns:

Return type:

dict

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True) → Bars¶

Retrieve historical chart data for the given asset via WebSocket using the md/getChart command. This method sends a WebSocket request to retrieve ‘length’ bars of historical data.

Note: Tradovate provides historical chart data via WebSocket, not via a REST GET.

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None¶: Retrieve the most recent price for the given asset via WebSocket. This method first retrieves the contract ID for the asset’s symbol, then subscribes to market data using that contract ID.

exception lumibot.data_sources.UnavailabeTimestep(source, timestep)¶: Bases: Exception

class lumibot.data_sources.YahooData(auto_adjust=False, datetime_start=None, datetime_end=None, **kwargs)¶

Bases: DataSourceBacktesting

MIN_TIMESTEP = 'day'¶

SOURCE = 'YAHOO'¶

TIMESTEP_MAPPING = [{'representations': ['1d', 'day'], 'timestep': 'day'}, {'representations': ['15m', '15 minutes'], 'timestep': '15 minutes'}, {'representations': ['1m', '1 minute'], 'timestep': 'minute'}]¶

get_chains(asset: Asset, quote: Asset | None = None, exchange: str | None = None)¶

Get the chains for a given asset. This is not implemented for YahooData becuase Yahoo does not support historical options data.

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True)¶: Get bars for a given asset

get_last_price(asset, timestep=None, quote=None, exchange=None, **kwargs) → float | Decimal | None¶: Takes an asset and returns the last known price

get_strikes(asset)¶: Return a set of strikes for a given asset