tradepose-client 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

tradepose_client/__init__.py

@@ -19,14 +19,25 @@ from .models import (
     Blueprint,
     Trigger,
     IndicatorSpec,
-    Freq,
-    OrderStrategy,
     Indicator,
     create_trigger,
     create_blueprint,
     create_indicator_spec,
     parse_strategy,
 )
+from .enums import (
+    Freq,
+    OrderStrategy,
+    TradeDirection,
+    TrendType,
+    Weekday,
+    IndicatorType,
+)
+from .builder import (
+    TradingContext,
+    BlueprintBuilder,
+    StrategyBuilder,
+)
 from .schema import (
     enhanced_ohlcv_schema,
     trades_schema,
@@ -68,13 +79,22 @@ __all__ = [
     "Blueprint",
     "Trigger",
     "IndicatorSpec",
-    "Freq",
-    "OrderStrategy",
     "Indicator",
     "create_trigger",
     "create_blueprint",
     "create_indicator_spec",
     "parse_strategy",
+    # Enums
+    "Freq",
+    "OrderStrategy",
+    "TradeDirection",
+    "TrendType",
+    "Weekday",
+    "IndicatorType",
+    # Builder API (New)
+    "TradingContext",
+    "BlueprintBuilder",
+    "StrategyBuilder",
     # Schema
     "enhanced_ohlcv_schema",
     "trades_schema",

tradepose_client/builder/__init__.py

@@ -0,0 +1,22 @@
+"""Strategy Builder API
+
+Provides a more concise and user-friendly strategy building interface.
+
+Core classes:
+- TradingContext: Trading Context fixed field accessor
+- IndicatorSpecWrapper: Indicator wrapper (.col(), .display_name)
+- BlueprintBuilder: Blueprint builder with chain calls
+- StrategyBuilder: Strategy builder (main entry)
+"""
+
+from .trading_context import TradingContext
+from .indicator_wrapper import IndicatorSpecWrapper
+from .blueprint_builder import BlueprintBuilder
+from .strategy_builder import StrategyBuilder
+
+__all__ = [
+    "TradingContext",
+    "IndicatorSpecWrapper",
+    "BlueprintBuilder",
+    "StrategyBuilder",
+]

tradepose_client/builder/blueprint_builder.py

@@ -0,0 +1,276 @@
+"""
+Blueprint 链式构建器
+
+支持链式添加 entry/exit triggers，最后通过 .build() 返回 BlueprintConfig。
+
+Usage:
+    from tradepose_client.builder import BlueprintBuilder, TradingContext
+    import polars as pl
+
+    # 创建 Base Blueprint
+    base_bp = BlueprintBuilder(
+        name="base_trend",
+        direction="Long",
+        trend_type="Trend",
+        note="基础趋势策略"
+    ).add_entry_trigger(
+        name="entry",
+        conditions=[pl.col("ema_20") > pl.col("ema_50")],
+        price_expr=pl.col("open"),
+        order_strategy="ImmediateEntry",
+        priority=1,
+        note="EMA 金叉"
+    ).add_exit_trigger(
+        name="exit",
+        conditions=[pl.col("ema_20") < pl.col("ema_50")],
+        price_expr=pl.col("open"),
+        order_strategy="ImmediateExit",
+        priority=1,
+        note="EMA 死叉"
+    ).build()
+
+    # 创建 Advanced Blueprint
+    adv_bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+        .add_exit_trigger(
+            name="stop_loss",
+            conditions=[],
+            price_expr=TradingContext.advanced_entry.entry_price - pl.col("atr") * 2,
+            order_strategy="StopLoss",
+            priority=1
+        )\
+        .add_exit_trigger(
+            name="take_profit",
+            conditions=[],
+            price_expr=TradingContext.advanced_entry.entry_price + pl.col("atr") * 3,
+            order_strategy="TakeProfit",
+            priority=2
+        )\
+        .build()
+"""
+
+import polars as pl
+from typing import List, Literal, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tradepose_client.models import Blueprint, Trigger, OrderStrategy
+    from tradepose_client.enums import TradeDirection, TrendType
+
+
+class BlueprintBuilder:
+    """
+    Blueprint 链式构建器
+
+    支持链式添加 entry/exit triggers，提供流畅的 API 体验。
+
+    Attributes:
+        name (str): Blueprint 名称
+        direction (str): 交易方向（"Long", "Short", "Both"）
+        trend_type (str): 趋势类型（"Trend", "Range", "Reversal"）
+        entry_first (bool): 是否必须先进场才能出场
+        note (str): 备注
+
+    Methods:
+        add_entry_trigger(...) -> BlueprintBuilder: 添加进场触发器（链式）
+        add_exit_trigger(...) -> BlueprintBuilder: 添加出场触发器（链式）
+        build() -> Blueprint: 构建最终 Blueprint 对象
+    """
+
+    def __init__(
+        self,
+        name: str,
+        direction: Union["TradeDirection", str],
+        trend_type: Union["TrendType", str] = "Trend",
+        entry_first: bool = True,
+        note: str = "",
+    ):
+        """
+        初始化 Blueprint 构建器
+
+        Args:
+            name: Blueprint 名称（唯一标识）
+            direction: 交易方向
+                - "Long": 做多
+                - "Short": 做空
+                - "Both": 双向（暂不支持）
+            trend_type: 趋势类型
+                - "Trend": 趋势跟随
+                - "Range": 区间震荡
+                - "Reversal": 反转交易
+            entry_first: 是否必须先进场才能出场（推荐 True）
+            note: Blueprint 说明
+
+        Examples:
+            >>> # Base Blueprint（简洁形式）
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")
+            >>>
+            >>> # Advanced Blueprint（完整形式）
+            >>> adv_bp = BlueprintBuilder(
+            ...     name="risk_management",
+            ...     direction="Long",
+            ...     trend_type="Trend",
+            ...     entry_first=True,
+            ...     note="Stop Loss + Take Profit"
+            ... )
+        """
+        self.name = name
+        self.direction = direction
+        self.trend_type = trend_type
+        self.entry_first = entry_first
+        self.note = note
+
+        self._entry_triggers: List["Trigger"] = []
+        self._exit_triggers: List["Trigger"] = []
+
+    def add_entry_trigger(
+        self,
+        name: str,
+        conditions: List[pl.Expr],
+        price_expr: pl.Expr,
+        order_strategy: Union["OrderStrategy", str],
+        priority: int,
+        note: str = "",
+    ) -> "BlueprintBuilder":
+        """
+        添加进场触发器（链式调用）
+
+        Args:
+            name: 触发器名称（唯一标识）
+            conditions: 条件表达式列表（全部为 True 才触发）
+            price_expr: 价格表达式（Polars Expr）
+            order_strategy: 订单策略
+                - Base Blueprint 必须使用 "ImmediateEntry"
+                - Advanced Blueprint 可使用 "FavorableDelayEntry", "AdverseDelayEntry" 等
+            priority: 优先级（1-100，越小优先级越高）
+            note: 触发器说明
+
+        Returns:
+            BlueprintBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")\
+            ...     .add_entry_trigger(
+            ...         name="entry",
+            ...         conditions=[pl.col("ema_20") > pl.col("ema_50")],
+            ...         price_expr=pl.col("open"),
+            ...         order_strategy="ImmediateEntry",
+            ...         priority=1,
+            ...         note="EMA 金叉"
+            ...     )
+        """
+        from tradepose_client.models import create_trigger
+
+        trigger = create_trigger(
+            name=name,
+            conditions=conditions,
+            price_expr=price_expr,
+            order_strategy=order_strategy,
+            priority=priority,
+            note=note,
+        )
+        self._entry_triggers.append(trigger)
+        return self
+
+    def add_exit_trigger(
+        self,
+        name: str,
+        conditions: List[pl.Expr],
+        price_expr: pl.Expr,
+        order_strategy: Union["OrderStrategy", str],
+        priority: int,
+        note: str = "",
+    ) -> "BlueprintBuilder":
+        """
+        添加出场触发器（链式调用）
+
+        Args:
+            name: 触发器名称（唯一标识）
+            conditions: 条件表达式列表（全部为 True 才触发）
+            price_expr: 价格表达式（Polars Expr）
+            order_strategy: 订单策略
+                - Base Blueprint 必须使用 "ImmediateExit"
+                - Advanced Blueprint 可使用 "StopLoss", "TakeProfit", "TrailingStop",
+                  "Breakeven", "TimeoutExit" 等
+            priority: 优先级（1-100，越小优先级越高）
+            note: 触发器说明
+
+        Returns:
+            BlueprintBuilder: 返回自身，支持链式调用
+
+        Examples:
+            >>> bp = BlueprintBuilder("risk_mgmt", "Long", "Trend")\
+            ...     .add_exit_trigger(
+            ...         name="stop_loss",
+            ...         conditions=[],
+            ...         price_expr=TradingContext.advanced_entry.entry_price - pl.col("atr") * 2,
+            ...         order_strategy="StopLoss",
+            ...         priority=1,
+            ...         note="固定止损 2 ATR"
+            ...     )\
+            ...     .add_exit_trigger(
+            ...         name="take_profit",
+            ...         conditions=[],
+            ...         price_expr=TradingContext.advanced_entry.entry_price + pl.col("atr") * 3,
+            ...         order_strategy="TakeProfit",
+            ...         priority=2,
+            ...         note="目标止盈 3 ATR"
+            ...     )
+        """
+        from tradepose_client.models import create_trigger
+
+        trigger = create_trigger(
+            name=name,
+            conditions=conditions,
+            price_expr=price_expr,
+            order_strategy=order_strategy,
+            priority=priority,
+            note=note,
+        )
+        self._exit_triggers.append(trigger)
+        return self
+
+    def build(self) -> "Blueprint":
+        """
+        构建最终 Blueprint 对象
+
+        Returns:
+            Blueprint: 完整的 Blueprint 配置对象
+
+        Raises:
+            ValueError: 如果未添加任何 trigger
+
+        Examples:
+            >>> bp = BlueprintBuilder("base", "Long", "Trend")\
+            ...     .add_entry_trigger(...)\
+            ...     .add_exit_trigger(...)\
+            ...     .build()
+            >>>
+            >>> # 用于 StrategyBuilder
+            >>> builder.set_base_blueprint(bp)
+            >>> builder.add_advanced_blueprint(adv_bp)
+        """
+        from tradepose_client.models import create_blueprint
+
+        if not self._entry_triggers and not self._exit_triggers:
+            raise ValueError(
+                f"Blueprint '{self.name}' must have at least one entry or exit trigger. "
+                f"Use .add_entry_trigger() or .add_exit_trigger() before calling .build()"
+            )
+
+        return create_blueprint(
+            name=self.name,
+            direction=self.direction,
+            entry_triggers=self._entry_triggers,
+            exit_triggers=self._exit_triggers,
+            trend_type=self.trend_type,
+            entry_first=self.entry_first,
+            note=self.note,
+        )
+
+    def __repr__(self) -> str:
+        """字符串表示"""
+        return (
+            f"BlueprintBuilder(name='{self.name}', "
+            f"direction='{self.direction}', "
+            f"entry_triggers={len(self._entry_triggers)}, "
+            f"exit_triggers={len(self._exit_triggers)})"
+        )

tradepose_client/builder/indicator_wrapper.py

@@ -0,0 +1,126 @@
+"""
+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_client.models 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}')"