qka 1.6.1.dev4__tar.gz → 1.6.2.dev2__tar.gz

{qka-1.6.1.dev4 → qka-1.6.2.dev2}/.gitignore

@@ -177,9 +177,9 @@ _debug_*.py
 _temp_*.txt
 _momentum_output.txt
 
-# 示例和测试（不入库）
-examples/
-tests/
+# 示例和测试（不入库，仓库根目录下的）
+/examples/
+/tests/
 
 # 回测报告
 reports/

{qka-1.6.1.dev4 → qka-1.6.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.6.1.dev4
+Version: 1.6.2.dev2
 Summary: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Documentation, https://zsrl.github.io/qka

qka-1.6.2.dev2/docs/examples/buy_and_hold.md

@@ -0,0 +1,79 @@
+# 买入持有与定投
+
+最简单的策略：买入，然后不动。
+
+---
+
+## 买入持有
+
+```python
+"""买入平安银行，一直持有到回测结束"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class BuyAndHold(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+        self.bought = False
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        if not self.bought and '000001.SZ' in close.index:
+            price = float(close['000001.SZ'])
+            if price > 0:
+                size = self.sizing.percent(0.5, price)
+                if size > 0:
+                    self.broker.buy('000001.SZ', price, size)
+                    self.bought = True
+
+
+if __name__ == '__main__':
+    data = Data(symbols=['000001.SZ'])
+    bt = Backtest(data, BuyAndHold())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='买入持有 - 平安银行')
+```
+
+---
+
+## 定投
+
+每月固定时间买入固定金额：
+
+```python
+"""每月 1 号买入 5000 块"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class MonthlyDCA(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+
+    def on_bar(self, date):
+        # 每月 1 号买入
+        if date.day != 1:
+            return
+
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        if '000001.SZ' in close.index:
+            price = float(close['000001.SZ'])
+            if price > 0:
+                size = self.sizing.fixed_amount(5000, price)
+                if size > 0:
+                    self.broker.buy('000001.SZ', price, size)
+
+
+if __name__ == '__main__':
+    data = Data(symbols=['000001.SZ'])
+    bt = Backtest(data, MonthlyDCA())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='定投 - 每月 1 号 5000 元')
+```

qka-1.6.2.dev2/docs/examples/ma_cross.md

@@ -0,0 +1,134 @@
+# 均线交叉
+
+5 日均线上穿 20 日均线买入，下穿卖出。经典的趋势跟踪策略。
+
+---
+
+## 单股票
+
+```python
+"""5 日线上穿 20 日线买入，下穿卖出"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class MaCross(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        if '000001.SZ' not in close.index:
+            return
+
+        # 取历史均线
+        ma5 = self.history('sma_5', 3)
+        ma20 = self.history('sma_20', 3)
+
+        if len(ma5) < 2 or len(ma20) < 2:
+            return
+
+        price = float(close['000001.SZ'])
+        if price <= 0:
+            return
+
+        # 今日 5 日线 > 20 日线，且昨天 5 日线 <= 20 日线（上穿）
+        if (ma5['000001.SZ'].iloc[-1] > ma20['000001.SZ'].iloc[-1] and
+            ma5['000001.SZ'].iloc[-2] <= ma20['000001.SZ'].iloc[-2]):
+
+            if '000001.SZ' not in self.broker.positions:
+                size = self.sizing.percent(0.5, price)
+                if size > 0:
+                    self.broker.buy('000001.SZ', price, size)
+
+        # 下穿卖出
+        elif (ma5['000001.SZ'].iloc[-1] < ma20['000001.SZ'].iloc[-1] and
+              ma5['000001.SZ'].iloc[-2] >= ma20['000001.SZ'].iloc[-2]):
+
+            if '000001.SZ' in self.broker.positions:
+                pos = self.broker.positions['000001.SZ']
+                self.broker.sell('000001.SZ', price, pos['size'])
+
+
+if __name__ == '__main__':
+    data = Data(
+        symbols=['000001.SZ'],
+        indicators={
+            'sma_5': ('sma', 5),
+            'sma_20': ('sma', 20),
+        },
+    )
+    bt = Backtest(data, MaCross())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='均线交叉 - 平安银行')
+```
+
+---
+
+## 多股票
+
+每只股票独立判断，谁出信号买谁：
+
+```python
+"""多股票均线交叉，每只股票判断自己的信号"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class MultiMaCross(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=1_000_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+
+        # 取历史均线（多股票的 DataFrame）
+        ma5 = self.history('sma_5', 3)
+        ma20 = self.history('sma_20', 3)
+
+        if len(ma5) < 2 or len(ma20) < 2:
+            return
+
+        for sym in close.index:
+            price = float(close[sym])
+            if price <= 0:
+                continue
+            if sym not in ma5.columns or sym not in ma20.columns:
+                continue
+
+            # 上穿买入
+            if (ma5[sym].iloc[-1] > ma20[sym].iloc[-1] and
+                ma5[sym].iloc[-2] <= ma20[sym].iloc[-2]):
+
+                if sym not in self.broker.positions:
+                    size = self.sizing.percent(0.1, price)
+                    if size > 0:
+                        self.broker.buy(sym, price, size)
+
+            # 下穿卖出
+            elif (ma5[sym].iloc[-1] < ma20[sym].iloc[-1] and
+                  ma5[sym].iloc[-2] >= ma20[sym].iloc[-2]):
+
+                if sym in self.broker.positions:
+                    pos = self.broker.positions[sym]
+                    self.broker.sell(sym, price, pos['size'])
+
+
+if __name__ == '__main__':
+    data = Data(
+        symbols=['000001.SZ', '600000.SH', '000002.SZ'],
+        indicators={
+            'sma_5': ('sma', 5),
+            'sma_20': ('sma', 20),
+        },
+    )
+    bt = Backtest(data, MultiMaCross())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='多股票均线交叉')
+```

qka-1.6.2.dev2/docs/examples/momentum.md

@@ -0,0 +1,87 @@
+# 动量排序选股
+
+每月末按过去 N 日收益率排序，选前几名买入。最经典的量化策略之一。
+
+---
+
+```python
+"""每月末按动量排序，选前 20% 的股票买入"""
+from qka import Data, Strategy, Broker, Backtest
+import numpy as np
+
+
+class Momentum(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=1_000_000)
+        self.monthly_rebalance = False
+        self.holdings = []
+
+    def on_bar(self, date):
+        # 月末调仓
+        if date.day < 28:
+            return
+
+        # 每月只调一次（本周最后一个交易日）
+        if self.monthly_rebalance:
+            return
+        self.monthly_rebalance = True
+
+        # 下个月的第一天重置标记
+        if date.day >= 28:
+            pass  # 保持标记，等跨月再重置
+
+        close = self.get('close')
+        if close is None or close.empty or len(close) < 5:
+            return
+
+        # 过去 60 个交易日的动量
+        hist = self.history('close', 60)
+        if hist is None or hist.empty:
+            return
+
+        # 算每只股票的收益率
+        ret = {}
+        for sym in hist.columns:
+            prices = hist[sym].dropna()
+            if len(prices) >= 40:  # 至少 40 个有效数据
+                ret[sym] = prices.iloc[-1] / prices.iloc[0] - 1
+
+        if not ret:
+            return
+
+        # 排序，选前 20%
+        sorted_syms = sorted(ret, key=ret.get, reverse=True)
+        top_n = max(1, len(sorted_syms) // 5)
+        buy_list = sorted_syms[:top_n]
+
+        # 卖出不在列表里的
+        for sym in list(self.broker.positions.keys()):
+            if sym not in buy_list:
+                pos = self.broker.positions[sym]
+                price = float(close.get(sym, 0))
+                if price > 0:
+                    self.broker.sell(sym, price, pos['size'])
+
+        # 买入列表里的新标的
+        cash_per_sym = self.broker.cash / len(buy_list)
+        for sym in buy_list:
+            if sym in self.broker.positions:
+                continue
+            price = float(close.get(sym, 0))
+            if price > 0:
+                size = self.sizing.fixed_amount(cash_per_sym, price)
+                if size > 0:
+                    self.broker.buy(sym, price, size)
+
+
+if __name__ == '__main__':
+    data = Data(
+        symbols=['000001.SZ', '600000.SH', '000002.SZ',
+                 '600036.SH', '601166.SH'],
+    )
+    bt = Backtest(data, Momentum())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='动量排序选股')
+```

qka-1.6.2.dev2/docs/examples/multi_factor.md

@@ -0,0 +1,106 @@
+# 多因子打分
+
+用多个因子综合打分，选分最高的买。多因子策略的骨架。
+
+---
+
+```python
+"""PE + 动量 + 波动率三因子打分选股"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class MultiFactor(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=1_000_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+
+        # 每月末调仓
+        if date.day < 28:
+            return
+
+        rsi = self.get('rsi_14')
+        hist = self.history('rsi_14', 20)
+        if hist is None or hist.empty:
+            return
+
+        scores = {}
+        for sym in close.index:
+            price = float(close[sym])
+            if price <= 0:
+                continue
+            if sym not in rsi.index or sym not in hist.columns:
+                continue
+
+            rsi_val = float(rsi[sym])
+            hist_series = hist[sym].dropna()
+
+            # 因子 1：RSI 适中（30-70 之间最好，太高中性，太低扣分）
+            score1 = 1.0 if 30 < rsi_val < 70 else 0.0
+            if rsi_val < 30:
+                score1 = -0.5
+
+            # 因子 2：RSI 趋势（最近 20 天 RSI 上升趋势）
+            if len(hist_series) >= 10:
+                recent = hist_series.iloc[-5:].mean()
+                earlier = hist_series.iloc[-10:-5].mean()
+                score2 = (recent - earlier) / earlier
+                score2 = max(-1, min(1, score2))  # 限制到 [-1, 1]
+            else:
+                score2 = 0
+
+            # 因子 3：波动率（低波动加分）
+            if len(hist_series) >= 10:
+                vol = hist_series.std()
+                score3 = max(-1, min(1, -vol / 20))  # 波动越低分越高
+            else:
+                score3 = 0
+
+            # 综合打分
+            scores[sym] = 0.4 * score1 + 0.4 * score2 + 0.2 * score3
+
+        if not scores:
+            return
+
+        # 选前 3 名
+        sorted_syms = sorted(scores, key=scores.get, reverse=True)
+        buy_list = sorted_syms[:3]
+
+        # 卖出不在名单里的
+        for sym in list(self.broker.positions.keys()):
+            if sym not in buy_list:
+                pos = self.broker.positions[sym]
+                price = float(close[sym])
+                if price > 0:
+                    self.broker.sell(sym, price, pos['size'])
+
+        # 买入名单里的新标的
+        cash_per_sym = self.broker.cash / len(buy_list)
+        for sym in buy_list:
+            if sym in self.broker.positions:
+                continue
+            price = float(close[sym])
+            if price > 0:
+                size = self.sizing.fixed_amount(cash_per_sym, price)
+                if size > 0:
+                    self.broker.buy(sym, price, size)
+
+
+if __name__ == '__main__':
+    data = Data(
+        symbols=['000001.SZ', '600000.SH', '000002.SZ',
+                 '600036.SH', '601166.SH', '600519.SH',
+                 '000858.SZ', '002415.SZ', '300750.SZ'],
+        indicators={
+            'rsi_14': ('rsi', 14),
+        },
+    )
+    bt = Backtest(data, MultiFactor())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='多因子打分选股')
+```

qka-1.6.2.dev2/docs/examples/rsi_atr.md

@@ -0,0 +1,60 @@
+# RSI + ATR 风控
+
+RSI 判断超买超卖，ATR 控制仓位大小。比固定股数更贴近实战。
+
+---
+
+```python
+"""RSI 超卖买入 + ATR 仓位控制"""
+from qka import Data, Strategy, Broker, Backtest
+
+
+class RsiAtrStrategy(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=1_000_000)
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+
+        rsi = self.get('rsi_14')
+        atr = self.get('atr_14')
+
+        for sym in close.index:
+            price = float(close[sym])
+            if price <= 0:
+                continue
+            if sym not in rsi.index or sym not in atr.index:
+                continue
+
+            rsi_val = float(rsi[sym])
+            atr_val = float(atr[sym])
+
+            # 超卖（RSI < 30）且没有持仓 → 买入
+            if rsi_val < 30 and sym not in self.broker.positions:
+                # ATR 控制仓位：每笔风险不超总资金 2%
+                size = self.sizing.atr_risk(0.02, price, atr_val)
+                if size > 0:
+                    self.broker.buy(sym, price, size)
+
+            # 超买（RSI > 70）且有持仓 → 卖出
+            elif rsi_val > 70 and sym in self.broker.positions:
+                pos = self.broker.positions[sym]
+                self.broker.sell(sym, price, pos['size'])
+
+
+if __name__ == '__main__':
+    data = Data(
+        symbols=['000001.SZ', '600000.SH', '000002.SZ'],
+        indicators={
+            'rsi_14': ('rsi', 14),
+            'atr_14': ('atr', 14),
+        },
+    )
+    bt = Backtest(data, RsiAtrStrategy())
+    bt.run(benchmark='000300.SH')
+    bt.summary()
+    bt.report(title='RSI + ATR 风控')
+```