oipd.sources module provides a unified interface for loading option chain data. You can fetch live data from vendors, list available expiry dates, or load chains from CSV files and existing DataFrames. All loading functions return DataFrames that are normalized to OIPD’s standard column names and ready to pass directly to VolCurve.fit, VolSurface.fit, or the probability constructors.
Functions
sources.list_expiry_dates
List all available option expiry dates for a ticker from a vendor.
str
required
Ticker symbol, e.g.
"AAPL" or "SPY".str
default:"yfinance"
Vendor alias. Currently
"yfinance" is the built-in supported vendor.Any
Additional keyword arguments forwarded to the vendor implementation.
list[str]
Available expiry dates as ISO-format strings (
YYYY-MM-DD), sorted ascending.NotImplementedError if the specified vendor does not support expiry listing.
sources.fetch_chain
Fetch an option chain from a vendor for one or more expiry dates, and return it alongside a VendorSnapshot.
str
required
Ticker symbol, e.g.
"AAPL" or "SPY".str | date | list[str] | list[date] | None
default:"None"
One or more specific expiry dates to fetch. Accepts a single ISO date string, a
date object, or a list of either. Mutually exclusive with horizon.str | None
default:"None"
Automatically fetch all expiries within the given time horizon. Accepts strings like
"3m", "6m", or "1y". Mutually exclusive with expiries.str
default:"yfinance"
Vendor alias.
dict[str, str] | None
default:"None"
Optional mapping in the form
{"vendor_column": "oipd_column"}. See Standard columns for the target names.bool
default:"True"
Whether to use the vendor response cache.
int
default:"15"
Number of minutes to keep cached vendor responses.
tuple[pd.DataFrame, VendorSnapshot]
A 2-tuple of
(chain_dataframe, vendor_snapshot). The chain DataFrame is normalized to OIPD standard column names. The snapshot records the vendor name, download timestamp, and underlying price.ValueError if both expiries and horizon are specified, or if neither is specified. ValueError if no expiries are found within the given horizon.
You must specify exactly one of
expiries or horizon. Providing both raises ValueError.sources.from_csv
Load and normalize long-form option chain data from a CSV file. For fitting, use one row per contract with strike, expiry, option_type, and either bid / ask or last_price.
str
required
Filesystem path to the CSV file.
dict[str, str] | None
default:"None"
Optional mapping in the form
{"csv_column": "oipd_column"}. See Standard columns for the target names.pd.DataFrame
Cleaned and normalized DataFrame, sorted by strike, with numeric quote columns coerced and
option_type normalized to "C" / "P".FileNotFoundError if the file does not exist. CSVReadError if the file cannot be read. ValueError if the file is empty or missing required columns.
sources.from_dataframe
Normalize an existing in-memory DataFrame to OIPD standard column names and validation rules.
pd.DataFrame
required
Input DataFrame containing option chain data. Must not be empty and must contain at least 5 rows.
dict[str, str] | None
default:"None"
Optional mapping in the form
{"dataframe_column": "oipd_column"}. See Standard columns for the target names.pd.DataFrame
Cleaned and normalized DataFrame with the same validation rules as
from_csv.TypeError if df is not a DataFrame. ValueError if df is empty, missing required columns, or contains fewer than 5 rows after cleaning.
Readers
The module-level functions delegate to these reader classes, which you can instantiate directly if you need more control.CSVReader
Reads and normalizes a CSV file. The .read(path, column_mapping=None) method follows the same contract as sources.from_csv.
DataFrameReader
Reads and normalizes an existing DataFrame. The .read(df, column_mapping=None) method follows the same contract as sources.from_dataframe.