"""
IndicatorSpec 包装器

提供更便捷的指标访问方式：
- .col() -> pl.Expr（用于条件表达式）
- .display_name -> str（用于依赖引用，作为属性访问）
- .spec -> IndicatorSpec（返回原始对象，用于最终 build）

Usage:
    from tradepose_client.builder import StrategyBuilder

    builder = StrategyBuilder(...)
    atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)

    # 使用 .col() 在条件表达式中
    condition = atr.col() > 100
    stop_loss_price = entry_price - atr.col() * 2

    # 使用 .display_name 引用依赖（SuperTrend 引用 ATR）
    st = builder.add_indicator(
        "supertrend",
        multiplier=3.0,
        volatility_column=atr.display_name,  # 属性访问
        freq="1D",
        shift=1
    )
"""

import polars as pl
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from tradepose_models.strategy import IndicatorSpec


class IndicatorSpecWrapper:
    """
    IndicatorSpec 包装器

    封装 IndicatorSpec，提供更便捷的访问方式。

    Attributes:
        display_name (str): 完整列名（属性访问）
        spec (IndicatorSpec): 原始 IndicatorSpec 对象

    Methods:
        col() -> pl.Expr: 返回 Polars 表达式
    """

    def __init__(self, spec: "IndicatorSpec"):
        """
        初始化包装器

        Args:
            spec: IndicatorSpec 对象
        """
        self._spec = spec

    def col(self) -> pl.Expr:
        """
        返回 Polars 表达式

        用于条件表达式或价格计算。

        Returns:
            pl.Expr: Polars 列表达式，等价于 pl.col(display_name)

        Examples:
            >>> atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
            >>>
            >>> # 在条件中使用
            >>> condition = atr.col() > 100
            >>>
            >>> # 在价格表达式中使用
            >>> stop_loss_price = entry_price - atr.col() * 2
            >>>
            >>> # 访问 struct 字段（如 SuperTrend）
            >>> st = builder.add_indicator("supertrend", ...)
            >>> direction = st.col().struct.field("direction")
        """
        return self._spec.col()

    @property
    def display_name(self) -> str:
        """
        完整列名（属性访问）

        用于指标依赖引用（如 SuperTrend 引用 ATR 的列名）。

        Returns:
            str: 完整的列名，格式为 "{instrument_id}_{freq}_{indicator_short_name}"

        Examples:
            >>> atr = builder.add_indicator("atr", period=21, freq="1D", shift=1)
            >>> print(atr.display_name)
            "US100.cash_M15_FTMO_FUTURE_1D_ATR|21"
            >>>
            >>> # 用于依赖引用
            >>> st = builder.add_indicator(
            ...     "supertrend",
            ...     multiplier=3.0,
            ...     volatility_column=atr.display_name,  # 引用 ATR 列名
            ...     freq="1D",
            ...     shift=1
            ... )
        """
        return self._spec.display_name()

    @property
    def spec(self) -> "IndicatorSpec":
        """
        返回原始 IndicatorSpec 对象

        用于最终构建 StrategyConfig。

        Returns:
            IndicatorSpec: 原始指标规范对象

        Note:
            用户通常不需要直接访问此属性，仅在高级场景下使用。
        """
        return self._spec

    def __repr__(self) -> str:
        """字符串表示"""
        return f"IndicatorSpecWrapper(display_name='{self.display_name}')"
