"""Commodity options data provider interface.

商品期权数据提供方抽象接口，面向期货/商品期权（如"黄金期权"）。
"""

from abc import ABC, abstractmethod

import pandas as pd


class CommodityOptionsDataProvider(ABC):
    """Abstract base class for commodity options data providers.

    商品期权数据提供方抽象接口。

    Standardizes:
        - Contract month listing / 合约月份列表
        - Contract-month chain table / 当月全量 call/put 合约表
        - Single option historical OHLCV / 单合约历史行情
    """

    def __init__(
        self,
        commodity_symbol: str | None = None,
        contract: str | None = None,
    ) -> None:
        """Initialize the provider.

        Args:
            commodity_symbol: 商品期权品种名称 (e.g., '黄金期权')。
            contract: 合约月份/合约代码 (e.g., 'au2604')。
        """
        self.commodity_symbol = commodity_symbol
        self.contract = contract

    @abstractmethod
    def get_contracts(self, commodity_symbol: str | None = None) -> list[str]:
        """Fetch available contract months for a commodity option product.

        Args:
            commodity_symbol: 品种名称。为 None 时使用初始化值。

        Returns:
            list[str]: 合约列表 (e.g., ['au2604', 'au2606'])。

        Raises:
            ValueError: commodity_symbol 缺失或获取失败时抛出。
        """

    @abstractmethod
    def get_options_chain(self, contract: str | None = None) -> pd.DataFrame:
        """Fetch the chain table for a contract month.

        Args:
            contract: 合约代码。为 None 时使用初始化值。

        Returns:
            pd.DataFrame: 标准化期权链（long format，含 call/put）。

        Raises:
            ValueError: 参数缺失或获取失败时抛出。
        """

    @abstractmethod
    def get_options_history(
        self,
        symbol: str,
        start_date: str = "1970-01-01",
        end_date: str = "2030-12-31",
    ) -> pd.DataFrame:
        """Fetch historical OHLCV for a single commodity option contract.

        Args:
            symbol: 期权合约代码 (e.g., 'au2604C1200')。
            start_date: 开始日期 (YYYY-MM-DD)。
            end_date: 结束日期 (YYYY-MM-DD)。

        Returns:
            pd.DataFrame: timestamp/symbol/open/high/low/close/volume/open_interest/settlement

        Raises:
            ValueError: 参数非法或获取失败时抛出。
        """
