cfquant 0.2.62__tar.gz → 0.2.64__tar.gz

{cfquant-0.2.62/cfquant.egg-info → cfquant-0.2.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cfquant
-Version: 0.2.62
+Version: 0.2.64
 Summary: QMT local bridge and xtquant-compatible Python client.
 License: MIT
 Requires-Python: >=3.8
@@ -48,6 +48,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 |---|---|
 | MiniQMT / `xtquant` 兼容调用 | 原有外部 Python 策略可以沿用接近 `xtdata`、`XtQuantTrader`、`StockAccount` 的写法，降低迁移成本。 |
 | 大 QMT 本地桥接 | 把大 QMT 内部的行情、查询、交易、撤单和回调能力桥接给外部 Python 程序和 Web 控制台。 |
+| 大 QMT 原生接口类 | 独立的 `QmtInnerApi` 面向外部数据查询、研究和实盘交易，按系统、行情、交易、回调、扩展数据与因子细分，保留原生函数名与参数，详见 [内置接口说明](docs/大QMT内置接口.md)。 |
 | Web 控制台 | 在浏览器里完成账号绑定、QMT 入口脚本指引、在线检测、接口调试、版本更新和回滚。 |
 | 多账号 / 多 QMT 路由 | 按 `bridge_id`、`account_type`、`account_id` 路由请求，适配多资金账号、普通账户、信用账户和多 QMT 终端。 |
 | 通用、极致、高级三种模式 | 普通环境快速跑通；受限 QMT 使用自包含入口；低延迟场景可拆分普通桥和交易桥。 |
@@ -283,6 +284,8 @@ print(result["status"], result["message"])
 
 `version_info(include_remote=False)` 只查询本地版本；`updates.check(force=True)` 只检查更新。按需更新也识别同版本号的安装包变化，首次安装包哈希未知时会执行一次更新以建立记录。真正需要更新时，默认要求先关闭相关 QMT；也可显式传入 `auto_close_qmt=True` 允许自动关闭。`restart=False` 可留待调用方重启。部分 QMT 部署失败返回 `update_incomplete`，已安装但尚未重启返回 `restart_required`；执行更新失败会抛出 `ManagementError`。
 
+外部程序复用绑定时的 `runtime` 对象，直接调用 `runtime.recover_strategy("YOUR_ACCOUNT_ID", account_type="STOCK")` 即可检测并尝试恢复已停止的 QMT 托管策略。本地托管实例由 SDK 自动读取管理凭据。也支持 `runtime.accounts.recover_strategy(...)` 和鉴权后的 `POST /api/qmt/strategies/recover`。返回值区分已提交启动、模型运行和通信确认，具体条件及示例见 [策略恢复接口](docs/第三方项目管理SDK.md#外部程序恢复-qmt-托管策略)。
+
 模拟／实盘参数需与实际账号一致。完整的启动策略、更新接口、重复绑定行为与错误处理见 [第三方项目管理 SDK](docs/第三方项目管理SDK.md)。
 
 ## 从 `xtquant` 迁移到 `cfquant`
@@ -395,6 +398,7 @@ restart_cfquant.bat     重启
 | QMT 综合部署教程 | [QMT 部署教程](docs/QMT部署教程.md) |
 | cftrader 批量同步/异步下单与撤单 | [cftrader 批量交易与撤单](docs/cftrader批量交易.md)，含 100 单本地基准 |
 | cftrader TWAP / VWAP / POV | [算法交易与共享全推行情](docs/algorithm_trading.md)，含自动订阅、生命周期和接口示例 |
+| 条件单 / 仓位计算 / 下单计划 | [条件单、仓位计算与下单计划](docs/conditional_orders.md)，含止盈止损、到时平仓、回撤 / 保本保护、风险仓位及 Python / HTTP 接口 |
 | 通用模式部署 | [通用模式部署指南](docs/通用模式部署指南.md) |
 | 极致模式部署 | [极致模式部署指南](docs/极致模式部署指南.md) |
 | 高级模式部署 | [高级模式部署指南](docs/高级模式部署指南.md) |

cfquant-0.2.62/PKG-INFO → cfquant-0.2.64/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.1
-Name: cfquant
-Version: 0.2.62
-Summary: QMT local bridge and xtquant-compatible Python client.
-License: MIT
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pandas>=1.0
-Requires-Dist: packaging>=20
-Requires-Dist: psutil>=5.8
-Requires-Dist: tomli>=1.1.0; python_version < "3.11"
-Requires-Dist: pycryptodome>=3.20
-Requires-Dist: pytz
-Requires-Dist: tabulate
-Requires-Dist: pandas-market-calendars
-Requires-Dist: importlib-resources>=5
-Requires-Dist: frida==17.16.4; sys_platform == "win32"
-Requires-Dist: pywin32>=306; sys_platform == "win32"
-Provides-Extra: dev
-Requires-Dist: build>=1.0; extra == "dev"
-Requires-Dist: twine>=5.0; extra == "dev"
-Provides-Extra: zmq
-Requires-Dist: pyzmq>=25; extra == "zmq"
-
 # cfquant
 
 <p>
@@ -48,6 +23,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 |---|---|
 | MiniQMT / `xtquant` 兼容调用 | 原有外部 Python 策略可以沿用接近 `xtdata`、`XtQuantTrader`、`StockAccount` 的写法，降低迁移成本。 |
 | 大 QMT 本地桥接 | 把大 QMT 内部的行情、查询、交易、撤单和回调能力桥接给外部 Python 程序和 Web 控制台。 |
+| 大 QMT 原生接口类 | 独立的 `QmtInnerApi` 面向外部数据查询、研究和实盘交易，按系统、行情、交易、回调、扩展数据与因子细分，保留原生函数名与参数，详见 [内置接口说明](docs/大QMT内置接口.md)。 |
 | Web 控制台 | 在浏览器里完成账号绑定、QMT 入口脚本指引、在线检测、接口调试、版本更新和回滚。 |
 | 多账号 / 多 QMT 路由 | 按 `bridge_id`、`account_type`、`account_id` 路由请求，适配多资金账号、普通账户、信用账户和多 QMT 终端。 |
 | 通用、极致、高级三种模式 | 普通环境快速跑通；受限 QMT 使用自包含入口；低延迟场景可拆分普通桥和交易桥。 |
@@ -283,6 +259,8 @@ print(result["status"], result["message"])
 
 `version_info(include_remote=False)` 只查询本地版本；`updates.check(force=True)` 只检查更新。按需更新也识别同版本号的安装包变化，首次安装包哈希未知时会执行一次更新以建立记录。真正需要更新时，默认要求先关闭相关 QMT；也可显式传入 `auto_close_qmt=True` 允许自动关闭。`restart=False` 可留待调用方重启。部分 QMT 部署失败返回 `update_incomplete`，已安装但尚未重启返回 `restart_required`；执行更新失败会抛出 `ManagementError`。
 
+外部程序复用绑定时的 `runtime` 对象，直接调用 `runtime.recover_strategy("YOUR_ACCOUNT_ID", account_type="STOCK")` 即可检测并尝试恢复已停止的 QMT 托管策略。本地托管实例由 SDK 自动读取管理凭据。也支持 `runtime.accounts.recover_strategy(...)` 和鉴权后的 `POST /api/qmt/strategies/recover`。返回值区分已提交启动、模型运行和通信确认，具体条件及示例见 [策略恢复接口](docs/第三方项目管理SDK.md#外部程序恢复-qmt-托管策略)。
+
 模拟／实盘参数需与实际账号一致。完整的启动策略、更新接口、重复绑定行为与错误处理见 [第三方项目管理 SDK](docs/第三方项目管理SDK.md)。
 
 ## 从 `xtquant` 迁移到 `cfquant`
@@ -395,6 +373,7 @@ restart_cfquant.bat     重启
 | QMT 综合部署教程 | [QMT 部署教程](docs/QMT部署教程.md) |
 | cftrader 批量同步/异步下单与撤单 | [cftrader 批量交易与撤单](docs/cftrader批量交易.md)，含 100 单本地基准 |
 | cftrader TWAP / VWAP / POV | [算法交易与共享全推行情](docs/algorithm_trading.md)，含自动订阅、生命周期和接口示例 |
+| 条件单 / 仓位计算 / 下单计划 | [条件单、仓位计算与下单计划](docs/conditional_orders.md)，含止盈止损、到时平仓、回撤 / 保本保护、风险仓位及 Python / HTTP 接口 |
 | 通用模式部署 | [通用模式部署指南](docs/通用模式部署指南.md) |
 | 极致模式部署 | [极致模式部署指南](docs/极致模式部署指南.md) |
 | 高级模式部署 | [高级模式部署指南](docs/高级模式部署指南.md) |

{cfquant-0.2.62 → cfquant-0.2.64}/cfquant/__init__.py

@@ -11,6 +11,7 @@ cfquant: 面向 QMT 的 xtquant 兼容层。
 
 from . import xtconstant, xtdata, xttrader, xttype
 from . import cftrader
+from .qmt_inner import QmtInnerApi
 from .client import CfquantError, CfquantTimeout, configure, get_client
 from .version import __version__
 from .build_info import build_identity, get_git_commit
@@ -25,6 +26,7 @@ __all__ = [
     "xtdata",
     "xttrader",
     "cftrader",
+    "QmtInnerApi",
     "xttype",
     "configure",
     "get_client",

{cfquant-0.2.62 → cfquant-0.2.64}/cfquant/cftrader.py

@@ -5,6 +5,7 @@ from .batch_orders import (
     prepare_batch_cancels, prepare_batch_orders, validate_batch_cancel_response, validate_batch_response,
 )
 from .protocol import new_id
+from .position_sizing import calculate_position
 from .xttrader import XtQuantTrader, _account_payload
 import threading
 
@@ -26,7 +27,7 @@ def _algo_rpc(action, params):
     return client.request(action, params)
 
 
-__all__ = ["CfQuantTrader"]
+__all__ = ["CfQuantTrader", "calculate_position"]
 
 class CfQuantTrader:
     """Use CfQuantTrader(trader) with an existing cfquant XtQuantTrader instance.
@@ -57,6 +58,70 @@ class CfQuantTrader:
     def order_twap(self, account, stock_code, order_type, order_volume, limit_price, **options):
         return self.order_algo(account, stock_code, order_type, order_volume, "TWAP", limit_price, **options)
 
+    calculate_position = staticmethod(calculate_position)
+
+    def order_condition(self, account, stock_code, conditions, execution, **options):
+        """Create a persistent sell protection group; manage it with query/pause/cancel_algo."""
+        payload = _account_payload(self._trader._resolve_account(account))
+        params = dict(options, account=payload, stock_code=stock_code, conditions=conditions, execution=execution)
+        params.setdefault("request_key", new_id("condition_request"))
+        task_id = _algo_rpc("cftrader.order_condition", params)
+        self._algo_accounts[task_id] = payload
+        return task_id
+
+    def order_stop_loss(self, account, stock_code, order_volume, stop_price, limit_price, **options):
+        return self.order_condition(account, stock_code, [{"type": "stop_loss", "price": stop_price}],
+                                    {"limit_price": limit_price}, order_volume=order_volume, **options)
+
+    def order_take_profit(self, account, stock_code, order_volume, take_profit_price, limit_price, **options):
+        return self.order_condition(account, stock_code, [{"type": "take_profit", "price": take_profit_price}],
+                                    {"limit_price": limit_price}, order_volume=order_volume, **options)
+
+    def order_trailing_stop(self, account, stock_code, order_volume, drawdown_percent, limit_price,
+                            activation_price=None, **options):
+        rule = dict(type="trailing_stop", drawdown_percent=drawdown_percent)
+        if activation_price is not None:
+            rule["activation_price"] = activation_price
+        return self.order_condition(account, stock_code, [rule], {"limit_price": limit_price},
+                                    order_volume=order_volume, **options)
+
+    def order_breakeven_stop(self, account, stock_code, order_volume, reference_price, activation_percent,
+                             limit_price, offset_amount=0, **options):
+        return self.order_condition(account, stock_code,
+            [dict(type="breakeven_stop", activation_percent=activation_percent, offset_amount=offset_amount)],
+            {"limit_price": limit_price}, order_volume=order_volume, reference_price=reference_price, **options)
+
+    def order_time_exit(self, account, stock_code, order_volume, at, limit_price, only_if_loss=False, **options):
+        return self.order_condition(account, stock_code, [dict(type="time_exit", at=at, only_if_loss=only_if_loss)],
+                                    {"limit_price": limit_price}, order_volume=order_volume, **options)
+
+    def preview_order_plan(self, account, stock_code, sizing, **options):
+        """Persist a preview without ordering; account balances are read by the service."""
+        payload = _account_payload(self._trader._resolve_account(account))
+        params = dict(options, account=payload, stock_code=stock_code, sizing=sizing)
+        params.setdefault("request_key", new_id("plan_request"))
+        plan = _algo_rpc("cftrader.preview_order_plan", params)
+        self._algo_accounts[plan["algo_id"]] = payload
+        return plan
+
+    def _plan_control(self, action, plan_id=None, account=None):
+        payload = _account_payload(self._trader._resolve_account(account or self._algo_accounts.get(plan_id)))
+        return _algo_rpc("cftrader." + action, dict(plan_id=plan_id, account=payload))
+
+    def submit_order_plan(self, plan_id, account=None):
+        """Revalidate and submit once. Repeating the same plan_id returns its current state."""
+        return self._plan_control("submit_order_plan", plan_id, account)
+
+    def query_order_plan(self, plan_id, account=None):
+        return self._plan_control("query_order_plan", plan_id, account)
+
+    def list_order_plans(self, account=None):
+        return self._plan_control("list_order_plans", account=account)
+
+    def cancel_order_plan(self, plan_id, account=None):
+        """Cancel the entry remainder; retain protection for confirmed fills."""
+        return self._plan_control("cancel_order_plan", plan_id, account)
+
     def order_vwap(self, account, stock_code, order_type, order_volume, limit_price, **options):
         return self.order_algo(account, stock_code, order_type, order_volume, "VWAP", limit_price, **options)
 

cfquant-0.2.64/cfquant/conditional_orders.py

@@ -0,0 +1,149 @@
+"""Validated, serializable conditions evaluated against observed quote prices."""
+import copy
+import math
+
+from .algo import positive
+from .algo_broker import execution_time
+
+
+def validate_conditions(conditions, reference_price=None):
+    if not isinstance(conditions, list) or not 1 <= len(conditions) <= 32:
+        raise ValueError("conditions must contain 1 to 32 rules (any matching rule triggers the group)")
+    reference = positive(reference_price, "reference_price") if reference_price is not None else None
+    result = []
+    fields = {
+        "stop_loss": {"price", "percent"}, "take_profit": {"price", "percent"},
+        "time_exit": {"at", "only_if_loss"}, "holding_exit": {"seconds", "trading_days", "opened_at", "exit_time"},
+        "trailing_stop": {"drawdown_percent", "drawdown_amount", "activation_price", "activation_percent"},
+        "breakeven_stop": {"activation_percent", "activation_price", "offset_percent", "offset_amount", "protect_price"},
+        "step_stop": {"steps"},
+    }
+    for index, original in enumerate(conditions):
+        if not isinstance(original, dict):
+            raise ValueError("each condition must be an object")
+        rule = copy.deepcopy(original)
+        kind = rule.get("type")
+        if kind not in fields or set(rule) - (fields.get(kind, set()) | {"type", "name"}):
+            raise ValueError("unknown condition type or fields")
+        rule.setdefault("name", "%s_%d" % (kind, index + 1))
+        if not isinstance(rule["name"], str) or not rule["name"]:
+            raise ValueError("condition name must be nonempty text")
+        if kind in ("stop_loss", "take_profit"):
+            if ("price" in rule) == ("percent" in rule):
+                raise ValueError(kind + " requires exactly one of price or percent")
+            if "percent" in rule:
+                pct = positive(rule["percent"], "percent")
+                if reference is None or (kind == "stop_loss" and pct >= 1):
+                    raise ValueError("percentage conditions require reference_price; stop percent must be below 1")
+                rule["price"] = reference * (1 + pct if kind == "take_profit" else 1 - pct)
+            rule["price"] = positive(rule["price"], "condition price")
+        elif kind == "time_exit":
+            rule["at"] = execution_time(rule.get("at"))
+            if rule["at"] is None:
+                raise ValueError("time_exit requires at")
+            if not isinstance(rule.get("only_if_loss", False), bool):
+                raise ValueError("only_if_loss must be boolean")
+            if rule.get("only_if_loss") and reference is None:
+                raise ValueError("only_if_loss requires reference_price")
+        elif kind == "holding_exit":
+            if ("seconds" in rule) == ("trading_days" in rule):
+                raise ValueError("holding_exit requires exactly one of seconds or trading_days")
+            rule["opened_at"] = execution_time(rule.get("opened_at"))
+            if rule["opened_at"] is None:
+                raise ValueError("holding_exit requires opened_at")
+            if "seconds" in rule:
+                rule["at"] = rule["opened_at"] + positive(rule["seconds"], "seconds")
+            else:
+                rule["trading_days"] = positive(rule["trading_days"], "trading_days", integer=True)
+                if rule["trading_days"] > 2500:
+                    raise ValueError("trading_days must not exceed 2500")
+                import datetime
+                datetime.time.fromisoformat(rule.setdefault("exit_time", "14:50"))
+        elif kind in ("trailing_stop", "breakeven_stop"):
+            if "activation_price" in rule and "activation_percent" in rule:
+                raise ValueError("use one activation threshold")
+            if "activation_percent" in rule:
+                if reference is None:
+                    raise ValueError("activation_percent requires reference_price")
+                rule["activation_price"] = reference * (1 + positive(rule["activation_percent"], "activation_percent", allow_zero=True))
+            if "activation_price" in rule:
+                rule["activation_price"] = positive(rule["activation_price"], "activation_price")
+            if kind == "trailing_stop":
+                if ("drawdown_percent" in rule) == ("drawdown_amount" in rule):
+                    raise ValueError("trailing_stop requires exactly one drawdown threshold")
+                key = "drawdown_percent" if "drawdown_percent" in rule else "drawdown_amount"
+                rule[key] = positive(rule[key], key)
+                if key == "drawdown_percent" and rule[key] >= 1:
+                    raise ValueError("drawdown_percent must be below 1")
+            else:
+                if "activation_price" not in rule:
+                    raise ValueError("breakeven_stop requires activation_price or activation_percent")
+                offsets = set(rule) & {"offset_amount", "offset_percent", "protect_price"}
+                if len(offsets) > 1:
+                    raise ValueError("use one breakeven protection offset")
+                if "protect_price" not in rule:
+                    if reference is None:
+                        raise ValueError("breakeven_stop requires reference_price or protect_price")
+                    rule["protect_price"] = reference + (reference * positive(rule["offset_percent"], "offset_percent", allow_zero=True)
+                        if "offset_percent" in rule else positive(rule.get("offset_amount", 0), "offset_amount", allow_zero=True))
+                rule["protect_price"] = positive(rule["protect_price"], "protect_price")
+                if rule["protect_price"] >= rule["activation_price"]:
+                    raise ValueError("protect_price must be below activation_price")
+        elif kind == "step_stop":
+            if reference is None or not isinstance(rule.get("steps"), list) or not rule["steps"]:
+                raise ValueError("step_stop requires reference_price and steps")
+            previous_gain = previous_stop = -1
+            for step in rule["steps"]:
+                if not isinstance(step, dict) or set(step) != {"gain_percent", "protect_percent"}:
+                    raise ValueError("each step requires gain_percent and protect_percent")
+                gain = positive(step["gain_percent"], "gain_percent", allow_zero=True)
+                protect = positive(step["protect_percent"], "protect_percent", allow_zero=True)
+                if gain <= previous_gain or protect < previous_stop or protect >= gain:
+                    raise ValueError("steps must have increasing gains and nondecreasing protection below each gain")
+                previous_gain, previous_stop = gain, protect
+        result.append(rule)
+    return result
+
+
+def evaluate_conditions(rules, states, price, now, reference, trigger_on_create=True):
+    """Mutate persisted states; return the first trigger. Observed highs never fall."""
+    triggered = None
+    def above(value, threshold):
+        return value >= threshold or math.isclose(value, threshold, rel_tol=1e-12, abs_tol=1e-10)
+    def below(value, threshold):
+        return value <= threshold or math.isclose(value, threshold, rel_tol=1e-12, abs_tol=1e-10)
+    for index, rule in enumerate(rules):
+        state = states.setdefault(str(index), {})
+        kind = rule["type"]
+        hit = False
+        if kind in ("stop_loss", "take_profit"):
+            hit = below(price, rule["price"]) if kind == "stop_loss" else above(price, rule["price"])
+        elif kind in ("time_exit", "holding_exit"):
+            if now >= rule["at"]:
+                # Evaluate the loss gate once, at the first executable fresh snapshot.
+                if "time_decision" not in state:
+                    state["time_decision"] = not rule.get("only_if_loss") or price < reference
+                hit = state["time_decision"]
+        elif kind in ("trailing_stop", "breakeven_stop"):
+            if above(price, rule.get("activation_price", 0)):
+                state.setdefault("activated_at", now)
+            if "activated_at" in state:
+                if kind == "trailing_stop":
+                    state["high"] = max(state.get("high", price), price)
+                    candidate = (state["high"] * (1 - rule["drawdown_percent"]) if "drawdown_percent" in rule
+                                 else state["high"] - rule["drawdown_amount"])
+                else:
+                    candidate = rule["protect_price"]
+                state["stop"] = max(state.get("stop", candidate), candidate)
+                hit = below(price, state["stop"])
+        else:
+            for step in rule["steps"]:
+                if above(price, reference * (1 + step["gain_percent"])):
+                    state["stop"] = max(state.get("stop", 0), reference * (1 + step["protect_percent"]))
+            hit = "stop" in state and below(price, state["stop"])
+        if not hit:
+            state["armed"] = True
+        if hit and (trigger_on_create or state.get("armed") or kind in ("time_exit", "holding_exit")) and triggered is None:
+            triggered = dict(index=index, name=rule["name"], type=kind, price=price, at=now,
+                             threshold=state.get("stop", rule.get("price", rule.get("at"))))
+    return triggered

{cfquant-0.2.62 → cfquant-0.2.64}/cfquant/management.py

@@ -314,6 +314,17 @@ class RuntimeManager:
         """Initialize the first binding; subsequent calls upsert that binding."""
         return self.accounts.upsert(account_id, qmt_dir, _initialize=True, **options)
 
+    def recover_strategy(self, account_id=None, *, account_type=None, bridge_id=None,
+                         account_key=None, timeout=180):
+        """Recover a binding using the same managed service as initialize().
+
+        Reuse this RuntimeManager after binding accounts. Local managed services
+        automatically use home/management.key, just like account management.
+        """
+        return self.accounts.recover_strategy(account_id, account_type=account_type,
+                                             bridge_id=bridge_id, account_key=account_key,
+                                             timeout=timeout)
+
     def wait_ready(self, account_id, *, account_type="STOCK", bridge_id=None, timeout=120):
         deadline = time.monotonic() + timeout
         last = None
@@ -363,6 +374,27 @@ class AccountManager:
     def status(self, timeout=None):
         return self.runtime._request("GET", "/api/bindings/status", timeout=timeout)
 
+    def recover_strategy(self, account_id=None, *, account_type=None, bridge_id=None,
+                         account_key=None, timeout=180):
+        """Check and recover this binding's stopped managed QMT strategies.
+
+        Requires enabled strategy automation and a completed deployment. Returns
+        running/start_requested and per-target recovery states; submitting a start
+        is not confirmation that the strategy or its bridge is already running.
+        Uses the Web service, so it also works while the QMT bridge is offline.
+        """
+        body = {key: str(value).strip() for key, value in {
+            "account_id": account_id, "account_type": account_type,
+            "bridge_id": bridge_id, "account_key": account_key,
+        }.items() if value is not None}
+        if not body.get("account_id") and not body.get("account_key"):
+            raise ValueError("account_id or account_key is required")
+        if any(not value for value in body.values()):
+            raise ValueError("account selectors must not be empty")
+        if not self.runtime.attached:
+            self.runtime.status()  # Verify managed instance ownership first.
+        return self.runtime._request("POST", "/api/qmt/strategies/recover", body, timeout=timeout)
+
     def upsert(self, account_id, qmt_dir, *, account_type="STOCK", mode="ctypes",
                auto_start_qmt=False, deploy_strategy=True, strategy_autorun=True,
                live=True, auto_close_qmt=False, force=False, _initialize=False, **options):

cfquant-0.2.64/cfquant/planning_broker.py

@@ -0,0 +1,90 @@
+"""Account snapshots and exchange calendars used by persistent order plans."""
+import datetime as dt
+import time
+
+from .algo import positive
+from .algo_broker import RoutedAlgoBroker, SHANGHAI
+from .diagnostics import quote_time_ms
+from .position_sizing import instrument_rules
+from .xttype import XtAsset, XtPosition
+
+
+class PlanningBroker(RoutedAlgoBroker):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._calendar = {}
+
+    def rules(self, code):
+        detail = self.market_request("xtdata.get_instrument_detail", dict(stock_code=code, iscomplete=True))
+        if not isinstance(detail, dict):
+            raise ValueError("instrument metadata unavailable")
+        return instrument_rules(code, price_tick=positive(detail.get("PriceTick"), "PriceTick"))
+
+    def snapshot(self, account, code):
+        params = dict(account=account, stock_code=code)
+        asset = self.trade_request(account, "xttrader.query_stock_asset", params)
+        if isinstance(asset, list):
+            asset = asset[0] if len(asset) == 1 else None
+        if asset is None:
+            raise RuntimeError("account assets unavailable")
+        asset = XtAsset.from_any(asset)
+        rows = self.trade_request(account, "xttrader.query_stock_positions", params)
+        if not isinstance(rows, (list, tuple)):
+            raise RuntimeError("account positions unavailable")
+        positions = [XtPosition.from_any(row) for row in rows]
+        positions = [row for row in positions if row.stock_code == code]
+        orders = self.orders(account, code)
+        pending = sum(max(0, int(row.get("order_volume") or 0) - int(row.get("traded_volume") or 0))
+                      for row in orders if row.get("stock_code") == code and int(row.get("order_type") or 0) == 23
+                      and int(row.get("order_status", 255)) not in (53, 54, 56, 57))
+        return dict(total_asset=positive(asset.total_asset, "total_asset", allow_zero=True),
+                    available_cash=positive(asset.cash, "available_cash", allow_zero=True),
+                    current_volume=sum(int(row.volume) for row in positions),
+                    sellable_volume=sum(int(row.can_use_volume) for row in positions),
+                    pending_buy_volume=pending, captured_at=time.time())
+
+    def trading_dates(self, market, first, last):
+        key = (market, first, last)
+        cached = self._calendar.get(key)
+        if cached and time.monotonic() - cached[0] < 300:
+            return cached[1]
+        values = self.market_request("xtdata.get_trading_dates", dict(market=market, start_time=first, end_time=last, count=-1))
+        if values is None:
+            raise RuntimeError("exchange calendar unavailable")
+        dates = set()
+        for value in values:
+            text = str(value).replace("-", "")
+            if len(text) == 8 and text.isdigit():
+                dates.add(text)
+            else:
+                stamp = quote_time_ms(value)
+                if stamp is not None:
+                    dates.add(dt.datetime.fromtimestamp(stamp / 1000, SHANGHAI).strftime("%Y%m%d"))
+        result = sorted(dates)
+        self._calendar[key] = (time.monotonic(), result)
+        return result
+
+    def session_end(self, code, now):
+        local = dt.datetime.fromtimestamp(now, SHANGHAI)
+        date = local.strftime("%Y%m%d")
+        if date not in self.trading_dates(code.rsplit(".", 1)[-1], date, date):
+            return None
+        for begin, end in (("09:30", "11:30"), ("13:00", "14:57")):
+            a = dt.datetime.combine(local.date(), dt.time.fromisoformat(begin), SHANGHAI).timestamp()
+            b = dt.datetime.combine(local.date(), dt.time.fromisoformat(end), SHANGHAI).timestamp()
+            if a <= now < b:
+                return b
+        return None
+
+    def holding_deadline(self, code, rule):
+        if "at" in rule:
+            return rule["at"]
+        opened = dt.datetime.fromtimestamp(rule["opened_at"], SHANGHAI)
+        count = rule["trading_days"]
+        # Query actual exchange days; never infer holidays from weekdays.
+        dates = self.trading_dates(code.rsplit(".", 1)[-1], (opened + dt.timedelta(days=1)).strftime("%Y%m%d"),
+                                   (opened + dt.timedelta(days=count * 3 + 30)).strftime("%Y%m%d"))
+        if len(dates) < count:
+            raise ValueError("exchange calendar does not yet cover the requested holding period")
+        day = dt.datetime.strptime(dates[count - 1], "%Y%m%d").date()
+        return dt.datetime.combine(day, dt.time.fromisoformat(rule["exit_time"]), SHANGHAI).timestamp()

cfquant-0.2.64/cfquant/position_sizing.py

@@ -0,0 +1,161 @@
+"""Pure long-only cash-equity sizing. No connection or order is created here."""
+from decimal import Decimal, ROUND_FLOOR
+
+from .algo import positive
+
+
+def instrument_rules(stock_code, min_volume=None, volume_step=None, price_tick=0.01):
+    symbol, _, market = str(stock_code).upper().rpartition(".")
+    stock = (len(symbol) == 6 and symbol.isdigit() and
+             ((market == "SH" and symbol.startswith(("60", "68"))) or
+              (market == "SZ" and symbol.startswith(("00", "30"))) or
+              (market == "BJ" and symbol.startswith(("43", "83", "87", "88", "92")))))
+    if not stock:
+        raise ValueError("position sizing currently supports SH/SZ/BJ cash equities only")
+    star = market == "SH" and symbol.startswith("68")
+    minimum = positive(min_volume if min_volume is not None else (200 if star else 100), "min_volume", integer=True)
+    step = positive(volume_step if volume_step is not None else (1 if star or market == "BJ" else 100), "volume_step", integer=True)
+    if minimum % step:
+        raise ValueError("min_volume must be a multiple of volume_step")
+    return dict(min_volume=minimum, volume_step=step, price_tick=positive(price_tick, "price_tick"),
+                source="explicit" if min_volume is not None or volume_step is not None else "cash_equity_defaults")
+
+
+def calculate_position(*, stock_code, entry_price, method="risk_percent", stop_price=None,
+                       total_asset=None, available_cash=None, risk_amount=None, risk_percent=None,
+                       cash_amount=None, allocation_percent=None, allocation_base="total_asset",
+                       target_weight=None, current_volume=0, pending_buy_volume=0,
+                       max_position_percent=None, max_volume=None, reserved_cash=0,
+                       commission_rate=0.0003, min_commission=5, sell_tax_rate=0.0005,
+                       transfer_fee_rate=0.00001, slippage_per_share=0,
+                       take_profit_price=None, min_volume=None, volume_step=None, price_tick=0.01):
+    """Largest legal buy quantity satisfying cash, estimated stop risk and position caps.
+
+    Percentages are fractions (0.02 = 2%). Fees are configurable estimates,
+    including minimum commission on each side. Missing cash imposes no cash cap;
+    server-side plans always supply a fresh account snapshot.
+    """
+    rules = instrument_rules(stock_code, min_volume, volume_step, price_tick)
+    p = Decimal(str(positive(entry_price, "entry_price")))
+    tick = Decimal(str(rules["price_tick"]))
+    if p % tick:
+        raise ValueError("entry_price must align with price_tick")
+    stop = Decimal(str(positive(stop_price, "stop_price"))) if stop_price is not None else None
+    if stop is not None and (stop >= p or stop % tick):
+        raise ValueError("long stop_price must be below entry_price and align with price_tick")
+    methods = ("risk_amount", "risk_percent", "cash_amount", "allocation_percent", "target_weight")
+    if method not in methods:
+        raise ValueError("unknown sizing method: " + str(method))
+    def number(value, name, zero=True):
+        return Decimal(str(positive(value, name, allow_zero=zero)))
+    def fraction(value, name):
+        value = number(value, name)
+        if value > 1:
+            raise ValueError(name + " must be a fraction between 0 and 1")
+        return value
+    equity = number(total_asset, "total_asset") if total_asset is not None else None
+    cash = number(available_cash, "available_cash") if available_cash is not None else None
+    reserved = number(reserved_cash, "reserved_cash")
+    spendable = max(Decimal(0), cash - reserved) if cash is not None else None
+    current = positive(current_volume, "current_volume", integer=True, allow_zero=True)
+    pending = positive(pending_buy_volume, "pending_buy_volume", integer=True, allow_zero=True)
+    commission = number(commission_rate, "commission_rate")
+    minimum_fee = number(min_commission, "min_commission")
+    tax = number(sell_tax_rate, "sell_tax_rate")
+    transfer = number(transfer_fee_rate, "transfer_fee_rate")
+    slip = number(slippage_per_share, "slippage_per_share")
+    risk = budget = None
+    if method in ("risk_amount", "risk_percent"):
+        if stop is None:
+            raise ValueError("risk sizing requires stop_price")
+        if method == "risk_amount":
+            risk = number(risk_amount, "risk_amount", False)
+        else:
+            if equity is None or equity <= 0:
+                raise ValueError("risk_percent requires positive total_asset")
+            risk = equity * fraction(risk_percent, "risk_percent")
+        theoretical = risk / (p - stop)
+    else:
+        if method == "cash_amount":
+            budget = number(cash_amount, "cash_amount", False)
+        elif method == "allocation_percent":
+            if allocation_base not in ("total_asset", "available_cash"):
+                raise ValueError("allocation_base must be total_asset or available_cash")
+            base = equity if allocation_base == "total_asset" else spendable
+            if base is None:
+                raise ValueError("allocation base is required")
+            budget = base * fraction(allocation_percent, "allocation_percent")
+        else:
+            if equity is None or equity <= 0:
+                raise ValueError("target_weight requires positive total_asset")
+            budget = max(Decimal(0), equity * fraction(target_weight, "target_weight") - (current + pending) * p)
+        theoretical = budget / p
+    caps = {"sizing_budget": theoretical}
+    if spendable is not None:
+        caps["available_cash"] = spendable / p
+    if max_position_percent is not None:
+        if equity is None or equity <= 0:
+            raise ValueError("max_position_percent requires positive total_asset")
+        caps["position_cap"] = max(Decimal(0), equity * fraction(max_position_percent, "max_position_percent") / p - current - pending)
+    if max_volume is not None:
+        caps["max_volume"] = Decimal(positive(max_volume, "max_volume", integer=True, allow_zero=True))
+    def costs(q):
+        if not q:
+            return Decimal(0), Decimal(0), Decimal(0), Decimal(0)
+        buy = q * p
+        entry_fee = max(minimum_fee, buy * commission) + buy * transfer
+        exit_value = q * stop if stop is not None else Decimal(0)
+        exit_fee = max(minimum_fee, exit_value * commission) + exit_value * (tax + transfer) if stop is not None else Decimal(0)
+        loss = q * (p - stop + slip) + entry_fee + exit_fee if stop is not None else Decimal(0)
+        return buy + entry_fee, loss, entry_fee, exit_fee
+    def failures(q):
+        cash_used, loss, _, _ = costs(q)
+        reasons = [name for name, cap in caps.items() if q > cap]
+        if spendable is not None and cash_used > spendable:
+            reasons.append("available_cash")
+        if budget is not None and cash_used > budget:
+            reasons.append("sizing_budget")
+        if risk is not None and loss > risk:
+            reasons.append("stop_risk_budget")
+        return sorted(set(reasons))
+    step = rules["volume_step"]
+    low, high = 0, int((min(caps.values()) / step).to_integral_value(rounding=ROUND_FLOOR))
+    while low < high:
+        mid = (low + high + 1) // 2
+        if failures(mid * step):
+            high = mid - 1
+        else:
+            low = mid
+    quantity = low * step
+    if quantity < rules["min_volume"]:
+        quantity = 0
+    used, loss, entry_fee, exit_fee = costs(quantity)
+    reasons = failures(quantity + step if quantity else rules["min_volume"])
+    if not quantity:
+        reasons.append("below_minimum_order")
+    profit = ratio = None
+    if take_profit_price is not None:
+        tp = number(take_profit_price, "take_profit_price", False)
+        if tp <= p or tp % tick:
+            raise ValueError("take_profit_price must exceed entry_price and align with price_tick")
+        exit_tp_fee = max(minimum_fee, quantity * tp * commission) + quantity * tp * (tax + transfer) if quantity else Decimal(0)
+        profit = quantity * (tp - p - slip) - entry_fee - exit_tp_fee
+        ratio = profit / loss if loss else None
+    return dict(stock_code=stock_code, method=method, quantity=quantity, theoretical_quantity=float(theoretical),
+                entry_price=float(p), stop_price=float(stop) if stop is not None else None,
+                notional=float(quantity * p), cash_required=float(used),
+                risk_budget=float(risk) if risk is not None else None,
+                estimated_loss=float(loss) if stop is not None else None,
+                risk_percent=float(loss / equity) if stop is not None and equity else None,
+                position_percent=float((current + pending + quantity) * p / equity) if equity else None,
+                entry_fee=float(entry_fee), exit_fee=float(exit_fee), slippage_amount=float(quantity * slip),
+                estimated_profit=float(profit) if profit is not None else None,
+                reward_risk_ratio=float(ratio) if ratio is not None else None,
+                limiting_reasons=reasons, rules=rules,
+                assumptions=dict(total_asset=float(equity) if equity is not None else None,
+                                 available_cash=float(cash) if cash is not None else None,
+                                 reserved_cash=float(reserved), current_volume=current, pending_buy_volume=pending,
+                                 commission_rate=float(commission), min_commission=float(minimum_fee),
+                                 sell_tax_rate=float(tax), transfer_fee_rate=float(transfer),
+                                 slippage_per_share=float(slip)),
+                risk_note="Estimated loss at the assumed stop fill; gaps, liquidity and T+1 can increase actual loss.")