qka 2.2.3.dev3__tar.gz → 2.2.4.dev2__tar.gz

{qka-2.2.3.dev3 → qka-2.2.4.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.2.3.dev3
+Version: 2.2.4.dev2
 Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Repository, https://github.com/zsrl/qka

{qka-2.2.3.dev3 → qka-2.2.4.dev2}/qka/core/backtest.py

@@ -79,7 +79,10 @@ class Backtest:
 
     def run(self, cash: float = 100000.0,
             start_date: str = None, end_date: str = None,
-            benchmark: Optional[str] = None):
+            benchmark: Optional[str] = None,
+            commission_rate: float = None,
+            stamp_duty_rate: float = None,
+            slippage: float = None):
         """
         执行回测
 
@@ -95,13 +98,23 @@ class Backtest:
             end_date: 回测截止日期 YYYY-MM-DD，None 表示数据最晚日期
             benchmark: 基准代码，如 '000300.SH'（沪深300）。
                        如果提供，会下载基准数据用于对比。
+            commission_rate: 佣金费率，None 表示用 Broker 默认（万 2.5，最低 5 元）
+            stamp_duty_rate: 印花税率（仅卖出），None 表示用 Broker 默认（万 5）
+            slippage: 滑点比率，None 表示用 Broker 默认（0.1%）
 
         Returns:
             None。回测结果保存在 self.results、self.metrics、self.trade_history 中。
         """
         # 注入基础设施
         self.initial_cash = cash
-        self.strategy.broker = Broker(initial_cash=cash)
+        broker_kwargs = {'initial_cash': cash}
+        if commission_rate is not None:
+            broker_kwargs['commission_rate'] = commission_rate
+        if stamp_duty_rate is not None:
+            broker_kwargs['stamp_duty_rate'] = stamp_duty_rate
+        if slippage is not None:
+            broker_kwargs['slippage'] = slippage
+        self.strategy.broker = Broker(**broker_kwargs)
         self.strategy.sizing = SizingAccessor(self.strategy.broker)
         self.strategy._data = DataAccessor()
 

{qka-2.2.3.dev3 → qka-2.2.4.dev2}/qka/core/broker.py

@@ -99,6 +99,39 @@ class Broker:
             'trades': list(self.trade_history),
         }
 
+    def _buy_cost(self, price: float, size: int):
+        """
+        计算买入成本明细（滑点后执行价、成交额、佣金、总成本）。
+
+        作为买入费用的唯一来源，供 buy() 与仓位计算 estimate_buy_cost() 复用，
+        保证"预留费用"与"实际扣费"口径一致。
+
+        Returns:
+            tuple: (exec_price, amount, commission, total_cost)
+        """
+        exec_price = price * (1 + self.slippage)
+        amount = exec_price * size
+        if self.commission_rate > 0:
+            commission = max(amount * self.commission_rate, MIN_COMMISSION)
+        else:
+            commission = 0.0
+        return exec_price, amount, commission, amount + commission
+
+    def estimate_buy_cost(self, price: float, size: int) -> float:
+        """
+        预估买入总成本（含滑点与佣金）。
+
+        供仓位计算预留费用使用，口径与 buy() 完全一致。
+
+        Args:
+            price (float): 市价
+            size (int): 拟买入数量
+
+        Returns:
+            float: 总成本（成交额 + 佣金）
+        """
+        return self._buy_cost(price, size)[3]
+
     def buy(self, symbol: str, price: float, size: int) -> bool:
         """
         买入操作
@@ -121,13 +154,7 @@ class Broker:
             logger.warning(f"价格 {price:.2f} 不合法（前复权可能导致早期价格为负），跳过买入 {symbol}")
             return False
 
-        exec_price = price * (1 + self.slippage)
-        amount = exec_price * size
-        if self.commission_rate > 0:
-            commission = max(amount * self.commission_rate, MIN_COMMISSION)
-        else:
-            commission = 0.0
-        total_cost = amount + commission
+        exec_price, amount, commission, total_cost = self._buy_cost(price, size)
 
         if self.cash < total_cost:
             logger.debug(f"资金不足！需要 {total_cost:.2f}（佣金 {commission:.2f}），当前可用 {self.cash:.2f}")

{qka-2.2.3.dev3 → qka-2.2.4.dev2}/qka/core/sizing.py

@@ -63,10 +63,14 @@ class SizingAccessor:
         """
         固定金额。
         
-        计算 amount 能买多少股，向下按手取整。
+        计算 amount 能买多少股（预留滑点与佣金，保证买入总成本不超过 amount），
+        向下按手取整。
+        
+        注意：amount 为「总成本」上限（成交额 + 佣金），非纯「成交额」；
+        与 percent() 同口径，避免满仓时因费用超支被 Broker 拒单。
         
         Args:
-            amount: 投入金额
+            amount: 投入金额上限
             price: 每股价格
         
         Returns:
@@ -74,7 +78,13 @@ class SizingAccessor:
         """
         self._validate_positive(amount, 'amount')
         self._validate_positive(price, 'price')
-        return self._round_lot(amount / price)
+        # 以含滑点的成交价估算可买股数，再逐手下调，
+        # 确保「成交额 + 佣金」不超过 amount（与 Broker.buy 口径一致）。
+        exec_price = price * (1 + self._broker.slippage)
+        size = self._round_lot(amount / exec_price)
+        while size > 0 and self._broker.estimate_buy_cost(price, size) > amount:
+            size -= self.MIN_LOT
+        return size
 
     def percent(self, ratio: float, price: float) -> int:
         """
@@ -82,6 +92,9 @@ class SizingAccessor:
         
         使用可用现金的 ratio 比例买入，按手取整。
         
+        已预留滑点与佣金：返回的股数保证买入总成本（含费用）不超过
+        cash * ratio，避免满仓时因费用超支被 Broker 拒单。
+        
         Args:
             ratio: 0~1 之间的比例，如 0.1 表示 10%
             price: 每股价格
@@ -93,7 +106,14 @@ class SizingAccessor:
         self._validate_positive(price, 'price')
         if self._broker.cash <= 0:
             return 0
-        return self._round_lot(self._broker.cash * ratio / price)
+        budget = self._broker.cash * ratio
+        # 以含滑点的成交价估算可买股数，再逐手下调，
+        # 确保「成交额 + 佣金」不超过预算（与 Broker.buy 口径一致）。
+        exec_price = price * (1 + self._broker.slippage)
+        size = self._round_lot(budget / exec_price)
+        while size > 0 and self._broker.estimate_buy_cost(price, size) > budget:
+            size -= self.MIN_LOT
+        return size
 
     def atr_risk(self, risk_ratio: float, price: float, atr_value: float,
                  multiplier: float = 2.0) -> int: