jcback 0.1.1__py3-none-any.whl

jcback/__init__.py

@@ -0,0 +1,89 @@
+"""
+jcback — 事件驱动 A 股回测框架。
+
+函数式策略（推荐，与几策平台 init / on_bar 写法一致）::
+
+    def init(context): ...
+    def on_bar(context, bars): ...
+
+    def run_main():
+        run(
+            strategy_id="demo",
+            mode=MODE_BACKTEST,
+            symbols="600000.SH",
+            backtest_start_time="2025-01-02",
+            backtest_end_time="2025-03-31",
+            backtest_match_mode=MATCH_NEXT_OPEN,
+            init_func=init,
+            on_bar=on_bar,
+            use_mock=True,
+        )
+
+类式策略（jcback.Strategy 子类）::
+
+    from jcback import run_backtest, Strategy
+    result = run_backtest(MyStrategy, use_mock=True, symbols="600000.SH", start_date="2025-01-02", ...)
+"""
+from __future__ import annotations
+
+from .sim.facade import Backtest, Strategy
+from .runtime import (
+    ADJUST_NONE,
+    ADJUST_POST,
+    ADJUST_PREV,
+    Bar,
+    BacktestConfig,
+    BacktestEvent,
+    BacktestResult,
+    Context,
+    EventBacktest,
+    EventBus,
+    FunctionStrategy,
+    MATCH_CURRENT_CLOSE,
+    MATCH_NEXT_OPEN,
+    MODE_BACKTEST,
+    infer_asset_type,
+    jcdata_to_ohlcv,
+    load_from_jcdata,
+    load_multi_ohlcv,
+    make_mock_jcdata,
+    parse_symbols,
+    resolve_config,
+)
+from .runtime.export import emit_report_marker, get_last_result, serialize_for_ui
+from .runtime.report import print_backtest_report, setup_logger
+from .entry import default_backtest_window, run, run_backtest
+
+__all__ = [
+    "ADJUST_NONE",
+    "ADJUST_POST",
+    "ADJUST_PREV",
+    "Backtest",
+    "BacktestConfig",
+    "BacktestEvent",
+    "BacktestResult",
+    "Bar",
+    "Context",
+    "EventBacktest",
+    "EventBus",
+    "FunctionStrategy",
+    "MATCH_CURRENT_CLOSE",
+    "MATCH_NEXT_OPEN",
+    "MODE_BACKTEST",
+    "Strategy",
+    "default_backtest_window",
+    "infer_asset_type",
+    "jcdata_to_ohlcv",
+    "load_from_jcdata",
+    "load_multi_ohlcv",
+    "make_mock_jcdata",
+    "parse_symbols",
+    "emit_report_marker",
+    "get_last_result",
+    "print_backtest_report",
+    "resolve_config",
+    "run",
+    "run_backtest",
+    "serialize_for_ui",
+    "setup_logger",
+]

jcback/config.yaml

@@ -0,0 +1,56 @@
+# jcback 回测默认配置
+# 手续费规则：按品种区分买卖、期货平昨/平今；支持固定费 + 成交额比例
+
+commission:
+  # 未命中品种规则时的兜底
+  default:
+    buy_ratio: 0.0001
+    sell_ratio: 0.0001
+    fixed: 0.0
+    min_commission: 0.0
+    stamp_tax_ratio: 0.0
+
+  by_asset:
+    # A 股：买卖佣金不同，卖出另收印花税
+    stock:
+      buy_ratio: 0.00025
+      sell_ratio: 0.00025
+      fixed: 0.0
+      min_commission: 5.0
+      stamp_tax_ratio: 0.001
+
+    etf:
+      buy_ratio: 0.00025
+      sell_ratio: 0.00025
+      fixed: 0.0
+      min_commission: 5.0
+      stamp_tax_ratio: 0.0
+
+    # 可转债：买卖费率通常一致，无印花税
+    convertible_bond:
+      buy_ratio: 0.00005
+      sell_ratio: 0.00005
+      fixed: 0.0
+      min_commission: 0.0
+      stamp_tax_ratio: 0.0
+
+    bond:
+      buy_ratio: 0.00005
+      sell_ratio: 0.00005
+      fixed: 0.0
+      min_commission: 0.0
+      stamp_tax_ratio: 0.0
+
+    # 期货：通用兜底（未在 product_fees.yaml 列出的品种使用）
+    future:
+      multiplier: 1.0
+      open_ratio: 0.000023
+      open_fixed: 0.0
+      close_yesterday_ratio: 0.000023
+      close_yesterday_fixed: 0.0
+      close_today_ratio: 0.00023
+      close_today_fixed: 0.0
+      min_commission: 0.0
+
+  # 中国期货各品种交易所标准费率表（按品种代码 IF/RB/MA 等匹配）
+  future_fee_table: product_fees.yaml

jcback/entry.py

@@ -0,0 +1,355 @@
+"""
+jcback 主入口：统一 run() 风格（与几策策略脚本一致）。
+
+策略文件定义 init / on_bar / on_backtest_finished，在 run_main() 中调用 run()。
+支持单标的与多标的组合回测。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Callable
+
+import pandas as pd
+from loguru import logger
+
+from .sim.facade import Strategy
+from .runtime.constants import (
+    ADJUST_NONE,
+    ADJUST_POST,
+    ADJUST_PREV,
+    MATCH_CURRENT_CLOSE,
+    MATCH_NEXT_OPEN,
+    MODE_BACKTEST,
+)
+from .runtime.data import jcdata_to_ohlcv, load_multi_ohlcv, parse_symbols
+from .runtime.driver import EventBacktest, _configure_logging, _load_ohlcv
+from .runtime.config import resolve_config
+from .runtime.multi_runner import run_portfolio_backtest
+from .runtime.export import finish_run
+from .runtime.result import BacktestResult
+from .runtime.strategy import FunctionStrategy
+
+__all__ = [
+    "MODE_BACKTEST",
+    "ADJUST_NONE",
+    "ADJUST_PREV",
+    "ADJUST_POST",
+    "MATCH_NEXT_OPEN",
+    "MATCH_CURRENT_CLOSE",
+    "run",
+    "run_backtest",
+    "default_backtest_window",
+]
+
+
+def _parse_dates(
+    backtest_start_time: str | None,
+    backtest_end_time: str | None,
+    start_date: str | None,
+    end_date: str | None,
+) -> tuple[str | None, str | None]:
+    """统一日期参数：backtest_* 与 start_date/end_date 互为别名。"""
+    start = (backtest_start_time or start_date or "")[:10] or None
+    end = (backtest_end_time or end_date or "")[:10] or None
+    return start, end
+
+
+def _resolve_capital(
+    backtest_initial_cash: float | None,
+    initial_capital: float,
+    cash: float | None,
+) -> float:
+    if cash is not None:
+        return cash
+    if backtest_initial_cash is not None:
+        return backtest_initial_cash
+    return initial_capital
+
+
+def _resolve_data(
+    data: pd.DataFrame | dict[str, pd.DataFrame] | None,
+    jcdata_df: pd.DataFrame | None,
+    sym_list: list[str],
+) -> tuple[pd.DataFrame | None, dict[str, pd.DataFrame] | None, list[str]]:
+    """
+    统一数据入口：data 可为单标的 DataFrame 或多标的 dict。
+    jcdata_df 为 jcdata 原始格式，按 sym_list 转换。
+    """
+    if isinstance(data, dict):
+        if not sym_list:
+            sym_list = list(data.keys())
+        return None, data, sym_list
+    if data is not None:
+        return data, None, sym_list
+    if jcdata_df is not None:
+        if len(sym_list) > 1:
+            ohlcv_map = {sym: jcdata_to_ohlcv(jcdata_df, symbol=sym) for sym in sym_list}
+            return None, ohlcv_map, sym_list
+        sym = sym_list[0] if sym_list else None
+        return jcdata_to_ohlcv(jcdata_df, symbol=sym), None, sym_list
+    return None, None, sym_list
+
+
+def run(
+    *,
+    mode: str = MODE_BACKTEST,
+    strategy_id: str | None = None,
+    symbols: str | list[str] | None = None,
+    backtest_start_time: str | None = None,
+    backtest_end_time: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    backtest_adjust: str = ADJUST_PREV,
+    backtest_initial_cash: float | None = None,
+    initial_capital: float = 1_000_000,
+    cash: float | None = None,
+    backtest_commission_ratio: float | None = None,
+    commission: float | None = None,
+    backtest_slippage_ratio: float = 0.0001,
+    slippage: float | None = None,
+    backtest_match_mode: int = MATCH_NEXT_OPEN,
+    backtest_leverage_ratio: float = 1.0,
+    backtest_max_position_ratio: float | None = None,
+    backtest_max_single_position_ratio: float | None = None,
+    settlement_rule: str | None = None,
+    asset_type: str | None = None,
+    data: pd.DataFrame | dict[str, pd.DataFrame] | None = None,
+    jcdata_df: pd.DataFrame | None = None,
+    use_jcdata: bool = False,
+    use_mock: bool = False,
+    mock_seed: int = 42,
+    init_func: Callable | None = None,
+    on_bar: Callable | None = None,
+    on_backtest_finished: Callable | None = None,
+    on_error: Callable | None = None,
+    strategy_class: type[Strategy] | None = None,
+    strategy_params: dict | None = None,
+    debug_level: int = 0,
+    deposit: float = 0.0,
+    withdrawal: float = 0.0,
+    transaction_cost: float = 0.0,
+    margin: float | None = None,
+    **backtest_kwargs,
+) -> BacktestResult:
+    """
+    统一回测入口。
+
+    symbols: 单标的 str、多标的 list 或逗号分隔字符串，自动选择单标的/组合引擎。
+    data: 单标的 OHLCV DataFrame，或多标的 {symbol: DataFrame} dict。
+    日期/资金/佣金：backtest_* 与 start_date、initial_capital、commission 等互为别名。
+    未传 commission 时使用包内 config.yaml 品种手续费规则。
+
+    组合仓位：context.get_position(symbol)、order_target_percent(symbol, w)。
+    """
+    if mode != MODE_BACKTEST:
+        raise ValueError(f"暂不支持 mode={mode}")
+
+    _configure_logging(debug_level)
+    start, end = _parse_dates(backtest_start_time, backtest_end_time, start_date, end_date)
+    capital = _resolve_capital(backtest_initial_cash, initial_capital, cash)
+    comm = commission if commission is not None else backtest_commission_ratio
+    slip = slippage if slippage is not None else backtest_slippage_ratio
+    execution_price = "close" if backtest_match_mode == MATCH_CURRENT_CLOSE else "open"
+
+    sym_list = parse_symbols(symbols)
+    single_data, ohlcv_map, sym_list = _resolve_data(data, jcdata_df, sym_list)
+    is_portfolio = len(sym_list) > 1 or ohlcv_map is not None
+
+    config = resolve_config(
+        symbol=sym_list[0] if sym_list else None,
+        asset_type=asset_type,
+        execution_price=execution_price,
+        settlement_rule=settlement_rule,
+        adjust=backtest_adjust,
+        match_mode=backtest_match_mode,
+        initial_capital=capital,
+        deposit=deposit,
+        withdrawal=withdrawal,
+        commission=comm,
+        slippage=slip,
+        transaction_cost=transaction_cost,
+        leverage_ratio=backtest_leverage_ratio,
+        max_position_ratio=backtest_max_position_ratio,
+        max_single_position_ratio=backtest_max_single_position_ratio,
+        margin=margin,
+    )
+    config.trading_pair = ",".join(sym_list) if sym_list else None
+
+    if is_portfolio:
+        if strategy_class is not None:
+            raise ValueError("多标的组合模式暂仅支持 init_func/on_bar 函数式策略")
+        try:
+            if ohlcv_map is None:
+                ohlcv_map = load_multi_ohlcv(
+                    sym_list,
+                    start or "",
+                    end or "",
+                    use_jcdata=use_jcdata,
+                    use_mock=use_mock,
+                    mock_seed=mock_seed,
+                    jcdata_df=jcdata_df,
+                    adjust=backtest_adjust,
+                )
+        except Exception as exc:
+            if on_error:
+                on_error(None, -1, str(exc))
+            raise
+
+        if debug_level >= 1:
+            logger.info(
+                "jcback portfolio id={} n={} exec={} bars~={}",
+                strategy_id,
+                len(sym_list),
+                config.execution_price,
+                len(next(iter(ohlcv_map.values()))) if ohlcv_map else 0,
+            )
+
+        return run_portfolio_backtest(
+            symbols=sym_list,
+            config=config,
+            ohlcv_map=ohlcv_map,
+            init_func=init_func,
+            on_bar=on_bar,
+            on_backtest_finished=on_backtest_finished,
+            debug_level=debug_level,
+        )
+
+    # 单标的
+    try:
+        if single_data is not None:
+            ohlcv, sym = single_data, (sym_list[0] if sym_list else None)
+        else:
+            ohlcv, sym = _load_ohlcv(
+                data=None,
+                jcdata_df=jcdata_df,
+                symbol=sym_list[0] if sym_list else None,
+                start_date=start,
+                end_date=end,
+                use_jcdata=use_jcdata,
+                use_mock=use_mock,
+                mock_seed=mock_seed,
+                adjust=backtest_adjust,
+            )
+    except Exception as exc:
+        if on_error:
+            on_error(None, -1, str(exc))
+        raise
+
+    if not sym:
+        sym = sym_list[0] if sym_list else None
+
+    if strategy_class is not None:
+        strat_cls = strategy_class
+    elif init_func is not None or on_bar is not None:
+        if not sym:
+            raise ValueError("函数式策略须指定 symbols")
+        strat_cls = FunctionStrategy.attach_callbacks(
+            symbol=sym,
+            init_func=init_func,
+            on_bar_func=on_bar,
+        )
+    else:
+        raise ValueError("须提供 init_func/on_bar 或 strategy_class")
+
+    if debug_level >= 1:
+        logger.info(
+            "jcback run id={} pair={} asset={} exec={} settle={} bars={}",
+            strategy_id, sym, config.asset_type,
+            config.execution_price, config.settlement_rule, len(ohlcv),
+        )
+
+    bt = EventBacktest(ohlcv, strat_cls, config=config, debug_level=debug_level, **backtest_kwargs)
+    try:
+        stats = bt.run(**(strategy_params or {}))
+        result = bt.build_result(stats)
+    except Exception as exc:
+        if on_error:
+            on_error(getattr(strat_cls, "_context", None), -2, str(exc))
+        raise
+
+    ctx = getattr(strat_cls, "_context", None)
+    if on_backtest_finished:
+        on_backtest_finished(ctx, result.indicator)
+
+    if debug_level >= 1:
+        logger.info(
+            "jcback done return={:.2f}% trades={}",
+            result.indicator.get("return_pct", 0),
+            result.indicator.get("num_trades", 0),
+        )
+    return finish_run(result, strategy_id=strategy_id)
+
+
+def run_backtest(
+    strategy: type[Strategy],
+    *,
+    data: pd.DataFrame | dict[str, pd.DataFrame] | None = None,
+    jcdata_df: pd.DataFrame | None = None,
+    symbols: str | list[str] | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    use_jcdata: bool = False,
+    use_mock: bool = False,
+    mock_seed: int = 42,
+    cash: float | None = None,
+    initial_capital: float = 100_000,
+    deposit: float = 0.0,
+    withdrawal: float = 0.0,
+    commission: float | None = None,
+    slippage: float = 0.0,
+    transaction_cost: float = 0.0,
+    leverage_ratio: float = 1.0,
+    max_position_ratio: float | None = None,
+    max_single_position_ratio: float | None = None,
+    margin: float | None = None,
+    asset_type: str | None = None,
+    execution_price: str = "open",
+    settlement_rule: str | None = None,
+    adjust: str | None = None,
+    match_mode: int | None = None,
+    debug_level: int = 0,
+    event_handlers: list | None = None,
+    finalize_trades: bool = True,
+    strategy_params: dict | None = None,
+    **backtest_kwargs,
+) -> BacktestResult:
+    """类式策略入口（jcback.Strategy 子类），委托 run() 执行。"""
+    if match_mode is None:
+        match_mode = MATCH_CURRENT_CLOSE if execution_price.lower() == "close" else MATCH_NEXT_OPEN
+    return run(
+        strategy_class=strategy,
+        symbols=symbols,
+        data=data,
+        jcdata_df=jcdata_df,
+        start_date=start_date,
+        end_date=end_date,
+        use_jcdata=use_jcdata,
+        use_mock=use_mock,
+        mock_seed=mock_seed,
+        cash=cash,
+        initial_capital=initial_capital,
+        deposit=deposit,
+        withdrawal=withdrawal,
+        commission=commission,
+        slippage=slippage,
+        transaction_cost=transaction_cost,
+        backtest_leverage_ratio=leverage_ratio,
+        backtest_max_position_ratio=max_position_ratio,
+        backtest_max_single_position_ratio=max_single_position_ratio,
+        backtest_match_mode=match_mode,
+        backtest_adjust=adjust or ADJUST_PREV,
+        settlement_rule=settlement_rule,
+        asset_type=asset_type,
+        debug_level=debug_level,
+        strategy_params=strategy_params,
+        margin=margin,
+        event_handlers=event_handlers,
+        finalize_trades=finalize_trades,
+        **backtest_kwargs,
+    )
+
+
+def default_backtest_window(days: int = 60) -> tuple[str, str]:
+    end = datetime.now()
+    start = end - timedelta(days=days)
+    return start.strftime("%Y-%m-%d %H:%M:%S"), end.strftime("%Y-%m-%d %H:%M:%S")