Source code for quantdata.massive.expiries

"""
quantdata.massive.expiries

Per-ticker option expiry flags via the Massive API.

For each trading day, checks whether ANY option on the underlying expires on that day
and classifies it (MONTHLY, QUAD_WITCHING, etc.).

The :func:`ticker_expiries` function uses an incremental cache: it only fetches the
dates that are not already stored, so repeated calls for overlapping date ranges are
cheap.
"""

from __future__ import annotations

import warnings
from datetime import date

import polars as pl
from cdxcore.err import verify
from cdxcore.jcpool import JCPool
from cdxcore.util import fmt_date
from cdxcore.verbose import Context
from cdxcore.version import version

from quantdata.massive import MassiveClient
from quantdata.tickers import SubDir, _locations_tickers
from quantdata.tickers.ticker_calendar import EXPIRY

_expiries_cache = _locations_tickers

# ---------------------------------------------------------------------------
# Calendar classification (pure Polars, no API)
# ---------------------------------------------------------------------------


@version("0.1")
def _third_friday_expr() -> pl.Expr:
    """Calendar third Friday for the month containing the ``date`` column."""
    d = pl.col("date")
    m_start = d.dt.month_start()
    wd0 = m_start.dt.weekday()
    off = (pl.lit(5) - wd0 + pl.lit(7)) % pl.lit(7)  # Polars ISO weekday: Fri=5
    first_friday = m_start + off * pl.duration(days=1)
    return first_friday + pl.duration(days=14)


[docs] @version("0.1", dependencies=[_third_friday_expr]) def classify_expiry(df: pl.DataFrame) -> pl.DataFrame: """ Add ``has_expiry`` (Int8, values from :class:`quantdata.tickers.ticker_calendar.EXPIRY`) to a DataFrame that already contains a ``date`` column of trading days. The classification is purely calendar-based: * :attr:`EXPIRY.QUAD_WITCHING`: shifted third Friday of Mar/Jun/Sep/Dec * :attr:`EXPIRY.MONTHLY`: shifted third Friday of other months * :attr:`EXPIRY.NORMAL`: any other trading day """ verify("date" in df.columns, "df must contain a 'date' column") df0 = df.with_columns(pl.col("date").cast(pl.Date)) df1 = df0.with_columns( pl.col("date").dt.year().alias("_y"), pl.col("date").dt.month().alias("_m"), _third_friday_expr().alias("_third_friday"), ) expiry_by_month = df1.group_by(["_y", "_m"]).agg( pl.col("_third_friday").first().alias("_third_friday"), pl.col("date") .filter(pl.col("date") <= pl.col("_third_friday").first()) .max() .alias("_monthly_expiry_date"), ) df2 = df1.join(expiry_by_month, on=["_y", "_m"], how="left") is_monthly = pl.col("date") == pl.col("_monthly_expiry_date") is_qtr = pl.col("_m").is_in([3, 6, 9, 12]) out = df2.with_columns( pl.when(is_monthly & is_qtr) .then(pl.lit(int(EXPIRY.QUAD_WITCHING))) .when(is_monthly) .then(pl.lit(int(EXPIRY.MONTHLY))) .otherwise(pl.lit(int(EXPIRY.NONE))) .alias("has_expiry") .cast(pl.Int8) ).drop(["_y", "_m", "_third_friday", "_monthly_expiry_date"]) return out
# --------------------------------------------------------------------------- # Per-day API check # ---------------------------------------------------------------------------
[docs] @version("0.1", dependencies=[classify_expiry, MassiveClient]) def ticker_expiries_day(ticker: str, dt: date) -> tuple[date, int | None]: """ Check via the Massive API whether any option on ``ticker`` expires on ``dt``. Returns ------- (dt, expiry_code) ``expiry_code`` is an :class:`EXPIRY` int value, or ``None`` if no options expire. """ client = MassiveClient() url = f"{MassiveClient.BASE_URL}/v3/reference/options/contracts" params = { "underlying_ticker": ticker, "expiration_date.gte": dt.strftime("%Y-%m-%d"), "expiration_date.lte": dt.strftime("%Y-%m-%d"), "limit": 1000, "order": "asc", "expired": True, "sort": "expiration_date", "as_of": dt.strftime("%Y-%m-%d"), } res = client.paginate(url, params) if not res: return dt, None df = None try: df = pl.DataFrame(res, strict=False).select( pl.col("expiration_date").str.strptime(pl.Date, "%Y-%m-%d").alias("date") ) df = ( df.group_by("date") .agg(pl.len().alias("num_expiring")) .with_columns(pl.col("num_expiring") > 0) .rename({"num_expiring": "has_expiry"}) ) df = classify_expiry(df) except TypeError as e: warnings.warn(str(e)) raise if df.is_empty(): return dt, None assert df.height == 1, f"Expected 1 row but got {df.height}" return dt, int(df["has_expiry"].to_list()[0])
# --------------------------------------------------------------------------- # Incremental-cache wrapper # ---------------------------------------------------------------------------
[docs] @version("0.1", dependencies=[ticker_expiries_day, MassiveClient]) def ticker_expiries( ticker: str, business_days: list[date], *, num_workers: int = -2, threading: bool = False, verbose: Context = Context.quiet, ) -> pl.DataFrame: """ For each date in ``business_days``, flag whether any option on ``ticker`` expires (0-DTE check) and return the expiry type. Results are stored in an incremental cache keyed by ``ticker`` so only the missing dates are fetched on subsequent calls. Parameters ---------- ticker : str business_days : list[date] Sorted list of NYSE trading days to check. num_workers : int Parallel workers. threading : bool Use threads instead of processes. verbose : Context Returns ------- pl.DataFrame Columns: date (Date), has_expiry (Int8) — only rows where has_expiry is not null. """ head_version = ticker_expiries.version.unique_id48 cache_key = f"expiries/{ticker}" expiries: pl.DataFrame | None = ( _expiries_cache.read(cache_key, None, version=head_version) if _expiries_cache.cache_mode.read else None ) known_dates: set[date] = set(expiries["date"].to_list()) if expiries is not None else set() missing = sorted(set(business_days) - known_dates) tmx = verbose.timer() if missing: with verbose.write_t( lambda: f"Fetching {len(missing)} expiry dates for {ticker}..." ) as tme: jcpool = JCPool(num_workers, threading=threading) found: dict[date, int | None] = {} for dt_, code in jcpool.parallel( jcpool.delayed(ticker_expiries_day)(ticker=ticker, dt=dt_) for dt_ in missing ): verbose.report( 1, lambda: f"\r {ticker}: {int((len(found) + 1) * 100 // len(missing))}%...", end="", ) found[dt_] = code verbose.write(lambda: f"\rFetched {len(missing)} dates for {ticker}. Took {tme}.") new_rows = pl.DataFrame( { "date": pl.Series(list(found.keys()), dtype=pl.Date), "has_expiry": pl.Series(list(found.values()), dtype=pl.Int8), } ) expiries = pl.concat([expiries, new_rows]) if expiries is not None else new_rows expiries = expiries.sort("date") if _expiries_cache.cache_mode.write: _expiries_cache.write(cache_key, expiries, version=head_version) result = expiries.filter( pl.col("date").is_in(business_days) & pl.col("has_expiry").is_not_null() ) dupes = result.group_by("date").len().filter(pl.col("len") > 1) if dupes.height > 0: raise RuntimeError(f"Duplicate expiry dates for {ticker}: {dupes.head()}") verbose.write( lambda: ( f"Found {result.height} expiries for '{ticker}' between " f"{fmt_date(business_days[0])} and {fmt_date(business_days[-1])}. Took {tmx}." ) ) return result