tradepose-client 0.1.0__py3-none-any.whl

tradepose_client/api/health.py

@@ -0,0 +1,70 @@
+"""健康檢查 API"""
+
+from typing import Dict
+import requests
+
+
+class HealthAPI:
+    """健康檢查 API Mixin"""
+
+    def health(self) -> Dict:
+        """健康檢查 - 簡單的存活探測
+
+        Returns:
+            健康狀態 {"status": "ok"}
+
+        Example:
+            >>> status = client.health()
+            >>> print(status)  # {"status": "ok"}
+        """
+        response = requests.get(
+            f"{self.api_url}/health",
+            headers=self._get_headers()
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def readiness(self) -> Dict:
+        """就緒檢查 - 檢查所有依賴是否可用
+
+        Returns:
+            就緒狀態
+
+        Raises:
+            requests.HTTPError: 503 (Service not ready)
+
+        Example:
+            >>> try:
+            ...     status = client.readiness()
+            ...     print("Service is ready")
+            ... except requests.HTTPError as e:
+            ...     if e.response.status_code == 503:
+            ...         print("Service not ready yet")
+        """
+        response = requests.get(
+            f"{self.api_url}/ready",
+            headers=self._get_headers()
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def system_status(self) -> Dict:
+        """獲取完整系統狀態
+
+        Returns:
+            系統狀態信息（包括緩存、策略等統計）
+
+        Raises:
+            requests.HTTPError: 500
+
+        Example:
+            >>> status = client.system_status()
+            >>> print(f"Strategies: {status.get('strategies_count', 0)}")
+            >>> print(f"Cache usage: {status.get('cache_info', {})}")
+        """
+        response = requests.get(
+            f"{self.api_url}/api/v1/status",
+            headers=self._get_headers()
+        )
+        response.raise_for_status()
+        return response.json()

tradepose_client/api/strategy.py

@@ -0,0 +1,228 @@
+"""策略管理 API"""
+
+import json
+from typing import Dict, List, Union
+import requests
+
+
+class StrategyAPI:
+    """策略管理 API Mixin"""
+
+    def list_strategies(
+        self, full: bool = False, instrument_id: Union[str, None] = None
+    ) -> List[Dict]:
+        """列出所有可用策略
+
+        Args:
+            full: True 返回完整配置，False 返回简化列表（默认）
+            instrument_id: 按商品 ID 过滤（可选）
+
+        Returns:
+            策略列表（简化或完整格式）
+
+        Example:
+            >>> # 获取简化列表
+            >>> strategies = client.list_strategies()
+            >>>
+            >>> # 获取完整配置
+            >>> full_configs = client.list_strategies(full=True)
+            >>>
+            >>> # 按商品过滤
+            >>> txf_strategies = client.list_strategies(instrument_id="TXF_M1_SHIOAJI_FUTURE")
+            >>>
+            >>> # 组合使用
+            >>> txf_full = client.list_strategies(
+            ...     full=True,
+            ...     instrument_id="TXF_M1_SHIOAJI_FUTURE"
+            ... )
+        """
+        params = {}
+        if full:
+            params["full"] = "true"
+        if instrument_id:
+            params["instrument_id"] = instrument_id
+
+        response = requests.get(
+            f"{self.api_url}/api/v1/strategies",
+            params=params,
+            headers=self._get_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def get_strategy_detail(self, strategy_name: str) -> Dict:
+        """獲取策略詳情
+
+        Args:
+            strategy_name: 策略名稱
+
+        Returns:
+            策略詳情
+        """
+        response = requests.get(
+            f"{self.api_url}/api/v1/strategies/{strategy_name}",
+            headers=self._get_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def register_strategy(self, strategy_config, overwrite: bool = False) -> Dict:
+        """註冊策略（支持單個或批量註冊）
+
+        Args:
+            strategy_config: StrategyConfig 實例或 List[StrategyConfig]
+            overwrite: 是否覆蓋已存在的策略（默認 False）
+
+        Returns:
+            註冊結果（包含 succeeded/failed 或批量結果信息）
+
+        Raises:
+            requests.HTTPError: 400 (Invalid request), 409 (Already exists), 500
+
+        Example:
+            >>> from tradepose_client.models import StrategyConfig
+            >>>
+            >>> # 單個註冊
+            >>> strategy = StrategyConfig(...)
+            >>> response = client.register_strategy(strategy)
+            >>>
+            >>> # 覆蓋註冊
+            >>> response = client.register_strategy(strategy, overwrite=True)
+            >>>
+            >>> # 批量註冊
+            >>> strategies = [StrategyConfig(...), StrategyConfig(...)]
+            >>> response = client.register_strategy(strategies)
+            >>>
+            >>> # 批量覆蓋
+            >>> response = client.register_strategy(strategies, overwrite=True)
+        """
+        from ..models import StrategyConfig
+
+        # 判斷是否為列表（批量）
+        if isinstance(strategy_config, list):
+            # 批量註冊：直接傳遞配置列表
+            configs = []
+            for cfg in strategy_config:
+                if isinstance(cfg, StrategyConfig):
+                    configs.append(cfg.to_dict())
+                else:
+                    configs.append(cfg)
+            payload = configs
+        else:
+            # 單個註冊：直接傳遞 strategy_config 對象（不需要 {"config": ...} 包裝）
+            assert isinstance(
+                strategy_config, StrategyConfig
+            ), "strategy_config 必須是 StrategyConfig 實例或其列表"
+            payload = strategy_config.to_dict()
+
+        # 構建 URL（帶 overwrite 參數）
+        url = f"{self.api_url}/api/v1/strategies"
+        if overwrite:
+            url += "?overwrite=true"
+
+        response = requests.post(
+            url,
+            json=payload,
+            headers=self._get_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+    def delete_strategy(self, strategy_name: Union[str, List[str]]) -> Dict:
+        """刪除策略（支持單個或批量刪除）
+
+        內部使用 POST /api/v1/strategies/delete 端點
+
+        Args:
+            strategy_name: 策略名稱（str）或策略名稱列表（List[str]）
+
+        Returns:
+            刪除結果（包含 deleted/not_found 信息）
+
+        Example:
+            >>> # 單個刪除
+            >>> client.delete_strategy("my_strategy")
+            >>>
+            >>> # 批量刪除
+            >>> client.delete_strategy(["strategy1", "strategy2", "strategy3"])
+        """
+        # 判斷是否為列表
+        if isinstance(strategy_name, list):
+            names = strategy_name
+        else:
+            names = [strategy_name]
+
+        response = requests.post(
+            f"{self.api_url}/api/v1/strategies/delete",
+            json=names,
+            headers=self._get_headers(),
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def clear_strategies(self) -> Dict:
+        """清空所有策略（使用批量刪除端點）
+
+        Returns:
+            刪除結果（包含 deleted/not_found 信息）
+        """
+        strategies = self.list_strategies()
+        if not strategies:
+            return {
+                "deleted": [],
+                "not_found": [],
+                "total": 0,
+                "deleted_count": 0,
+                "not_found_count": 0,
+            }
+
+        strategy_names = [s["name"] for s in strategies]
+        return self.delete_strategy(strategy_names)
+
+    def add_blueprint(self, strategy_name: str, blueprint) -> Dict:
+        """為策略添加進階 Blueprint
+
+        Args:
+            strategy_name: 策略名稱
+            blueprint: Blueprint 實例
+
+        Returns:
+            添加結果
+
+        Raises:
+            requests.HTTPError: 404 (Strategy not found), 500
+
+        Example:
+            >>> from tradepose_client.models import create_blueprint, create_trigger
+            >>> import polars as pl
+            >>>
+            >>> # 創建 blueprint
+            >>> entry = create_trigger(
+            ...     name="reversal_entry",
+            ...     conditions=[pl.col("rsi") < 30],
+            ...     price_expr=pl.col("open")
+            ... )
+            >>> blueprint = create_blueprint(
+            ...     name="reversal_strategy",
+            ...     direction="Long",
+            ...     entry_triggers=[entry],
+            ...     exit_triggers=[]
+            ... )
+            >>>
+            >>> # 添加到策略
+            >>> client.add_blueprint("my_strategy", blueprint)
+        """
+        from ..models import Blueprint
+
+        assert isinstance(blueprint, Blueprint), "blueprint 必須是 Blueprint 實例"
+
+        payload = {"blueprint": blueprint.model_dump()}
+
+        response = requests.post(
+            f"{self.api_url}/api/v1/strategies/{strategy_name}/blueprints",
+            json=payload,
+            headers=self._get_headers(),
+        )
+        response.raise_for_status()
+        return response.json()

tradepose_client/client.py

@@ -0,0 +1,58 @@
+"""Tradepose API 客戶端"""
+
+import os
+import redis
+from typing import Optional
+
+from .api.strategy import StrategyAPI
+from .api.export import ExportAPI
+from .api.engine import EngineAPI
+from .api.health import HealthAPI
+
+
+class TradeposeClient(StrategyAPI, ExportAPI, EngineAPI, HealthAPI):
+    """Tradepose API 客戶端
+
+    整合所有 API 功能的主客戶端類
+    """
+
+    def __init__(
+        self,
+        api_url: str = "http://localhost:8080",
+        redis_url: str = "redis://:tradepose_password@localhost:6379",
+        api_token: Optional[str] = None,
+    ):
+        """初始化客戶端
+
+        Args:
+            api_url: Tradepose API 基礎 URL
+            redis_url: Redis 連接 URL
+            api_token: JWT Bearer Token (如果為 None，從 TRADEPOSE_API_TOKEN 環境變數讀取)
+        """
+        self.api_url = api_url.rstrip("/")
+        self.redis_url = redis_url
+        self.api_token = api_token or os.getenv("TRADEPOSE_API_TOKEN")
+        self._redis_client = None
+
+    @property
+    def redis(self):
+        """懶加載 Redis 客戶端"""
+        if self._redis_client is None:
+            self._redis_client = redis.from_url(self.redis_url, decode_responses=True)
+        return self._redis_client
+
+    def _get_headers(self, additional_headers: Optional[dict] = None) -> dict:
+        """獲取包含認證信息的請求 headers
+
+        Args:
+            additional_headers: 額外的 headers (可選)
+
+        Returns:
+            dict: 包含 Content-Type 和 Authorization 的 headers
+        """
+        headers = {"Content-Type": "application/json"}
+        if self.api_token:
+            headers["Authorization"] = f"Bearer {self.api_token}"
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers