jcback 0.1.4

Event-driven bar replay backtest engine for China A-share, ETF, bond and futures

jcback

事件驱动、逐 K 线推进的 A 股 / ETF / 可转债 / 期货回测库。

支持函数式策略（init / on_bar）与类式策略（Strategy 子类），可自带 OHLCV、使用内置模拟数据，或通过 jcdata 拉取行情。

安装

pip install jcback

需要 jcdata 行情时（要求 jcdata >= 0.1.4）：

pip install jcback[jcdata]

或单独安装：

pip install "jcdata>=0.1.4"

要求 Python >= 3.10。

快速开始

函数式策略 + 模拟数据

无需外部行情，适合本地验证逻辑：

from jcback import run, MODE_BACKTEST, MATCH_NEXT_OPEN, ADJUST_PREV


def init(context):
    context.subscribe(context.symbols, frequency="1d", wait_group=True)


def on_bar(context, bars):
    for bar in bars:
        context.order_target_percent(bar.symbol, 0.5)


result = run(
    strategy_id="demo",
    mode=MODE_BACKTEST,
    symbols="600000.SH",
    backtest_start_time="2025-01-02",
    backtest_end_time="2025-03-31",
    backtest_adjust=ADJUST_PREV,
    backtest_match_mode=MATCH_NEXT_OPEN,
    init_func=init,
    on_bar=on_bar,
    use_mock=True,
)

print(result.indicator["return_pct"], "%")

对接 jcdata 历史行情

import jcdata
from jcback import run, MODE_BACKTEST, MATCH_NEXT_OPEN, print_backtest_report, setup_logger

jcdata.login(token="YOUR_TOKEN")

setup_logger()

result = run(
    strategy_id="demo",
    mode=MODE_BACKTEST,
    symbols=["600000.SH", "601318.SH"],
    backtest_start_time="2025-01-02",
    backtest_end_time="2025-06-30",
    backtest_match_mode=MATCH_NEXT_OPEN,
    init_func=init,
    on_bar=on_bar,
    use_jcdata=True,
)

print_backtest_report(result, "demo")

类式策略

from jcback import Strategy, run_backtest


class SmaCross(Strategy):
    n_short, n_long = 5, 20

    def init(self):
        c = self.data.Close
        self.ma_s = self.I(lambda x, n: x.rolling(n).mean(), c, self.n_short)
        self.ma_l = self.I(lambda x, n: x.rolling(n).mean(), c, self.n_long)

    def next(self):
        if self.ma_s[-2] < self.ma_l[-2] and self.ma_s[-1] > self.ma_l[-1]:
            self.buy()
        elif self.ma_s[-2] > self.ma_l[-2] and self.ma_s[-1] < self.ma_l[-1]:
            self.position.close()


result = run_backtest(
    SmaCross,
    symbols="600000.SH",
    start_date="2025-01-02",
    end_date="2025-06-30",
    use_mock=True,
)

自备 OHLCV

data 列为 Open / High / Low / Close / Volume（可选 Amount），索引为时间：

run(..., data=ohlcv_df, symbols="600000.SH")
# 多标的：data={"600000.SH": df1, "601318.SH": df2}

常用常量

常量	含义
MODE_BACKTEST	回测模式
ADJUST_NONE / ADJUST_PREV / ADJUST_POST	不复权 / 前复权 / 后复权
MATCH_NEXT_OPEN	下一根 K 线开盘价撮合
MATCH_CURRENT_CLOSE	当前 K 线收盘价撮合

手续费、交割与交易单位

未显式传入 commission 时，按包内 config.yaml 及 product_fees.yaml 的品类规则计算（股票、ETF、转债、期货等），含最低 5 元佣金、买卖不同费率、卖出印花税等。

交割规则与最小交易单位按标的自动匹配，无需手动配置：

品种	交割	最小单位
股票 / ETF	T+1	100 股（1 手）
可转债	T+0	10 张
期货	T+0	1 手

策略信号追踪（track_vars）

函数式策略可在 init(context) 中声明 context.track_vars（dict），在 on_bar 中更新；引擎每个交易日结束后自动快照，结果写入 BacktestResult.daily_signals；也可经 serialize_for_ui 得到 signals_daily / signals_schema。

def init(context):
    context.track_vars = {"ma5": 0.0, "signal": 0, "weights": {}, "top3": [None, None, None]}

def on_bar(context, bars):
    tv = context.track_vars
    tv["ma5"] = ...
    tv["signal"] = 1

展平规则：scalar → 单列；dict → {name}_{key}；list → {name}_{index}。

主要导出

run、run_backtest、Strategy、Backtest、Context、Bar、resolve_config、
load_from_jcdata、load_multi_ohlcv、jcdata_to_ohlcv、ohlcv_map_from_jcdata_raw、
make_mock_jcdata、get_last_result、serialize_for_ui、print_backtest_report、setup_logger

完整 API 见 jcback.__all__。

许可证

MIT