"""
因子抽象基类。

所有因子必须继承 BaseFactor，实现 calculate(df) → pd.Series。
"""

from abc import ABC, abstractmethod

import pandas as pd


class BaseFactor(ABC):
    """因子抽象基类。

    属性:
        name: 因子名称，如 'momentum_20'
        category: 'technical' | 'fundamental' | 'sentiment'
        required_columns: 计算所需的 DataFrame 列名列表
    """

    name: str = ""
    category: str = ""

    @abstractmethod
    def calculate(self, df: pd.DataFrame) -> pd.Series:
        """计算因子值。

        参数:
            df: 日线 DataFrame，index 为 trade_date，
                列至少包含 OHLCV 等基础字段。

        返回:
            pd.Series，index 与 df 对齐，值为因子值。
        """
        ...

    def get_required_columns(self) -> list[str]:
        """返回计算所需的列名列表。子类可覆盖。"""
        return ["close"]

    def __repr__(self) -> str:
        return f"{self.__class__.__name__}(name='{self.name}')"