hqbacktest 0.1.4__py3-none-any.whl

hqbacktest/__init__.py

@@ -0,0 +1,104 @@
+"""hqbacktest - A-share quantitative strategy backtest and trading simulation engine."""
+
+from importlib.metadata import version
+
+from hqbacktest.data import (
+    CacheKey,
+    DataCache,
+    DataVersion,
+    DataView,
+    HqDataCsvPortal,
+    InMemoryDataPortal,
+    MarketDataPortal,
+    resolve_source_location,
+)
+from hqbacktest.domain import (
+    AccountSnapshot,
+    AdjustmentPolicy,
+    Bar,
+    CorporateActionAdjustment,
+    EventType,
+    Fill,
+    Order,
+    OrderStatus,
+    OrderType,
+    Portfolio,
+    Position,
+    PositionSnapshot,
+    PriceMode,
+    RejectReason,
+    Side,
+)
+from hqbacktest.engine import (
+    BacktestConfig,
+    BacktestEngine,
+    BacktestResult,
+    BaseStrategy,
+    Context,
+    CorporateAction,
+    CorporateActionProvider,
+    CostModel,
+    DefaultCostModel,
+    EngineEvent,
+    EquityPoint,
+    EventLog,
+    FactorDiagnostic,
+    FactorDiagnosticCollector,
+    MetricsConfig,
+    NullStrategy,
+    PerformanceMetrics,
+    SimulatedBroker,
+    Strategy,
+    TradingDayIterator,
+    TradingRuleSet,
+)
+
+__version__ = version("hqbacktest")
+
+__all__ = [
+    "__version__",
+    "AccountSnapshot",
+    "AdjustmentPolicy",
+    "BacktestConfig",
+    "BacktestEngine",
+    "BacktestResult",
+    "Bar",
+    "BaseStrategy",
+    "CacheKey",
+    "Context",
+    "CorporateAction",
+    "CorporateActionAdjustment",
+    "CorporateActionProvider",
+    "CostModel",
+    "DataCache",
+    "DataVersion",
+    "DataView",
+    "DefaultCostModel",
+    "EngineEvent",
+    "EquityPoint",
+    "EventLog",
+    "EventType",
+    "FactorDiagnostic",
+    "FactorDiagnosticCollector",
+    "Fill",
+    "HqDataCsvPortal",
+    "InMemoryDataPortal",
+    "MarketDataPortal",
+    "MetricsConfig",
+    "NullStrategy",
+    "Order",
+    "OrderStatus",
+    "OrderType",
+    "PerformanceMetrics",
+    "Portfolio",
+    "Position",
+    "PositionSnapshot",
+    "PriceMode",
+    "RejectReason",
+    "Side",
+    "SimulatedBroker",
+    "Strategy",
+    "TradingDayIterator",
+    "TradingRuleSet",
+    "resolve_source_location",
+]

hqbacktest/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point so `python -m hqbacktest run --config ...` works.
+
+Delegates to `hqbacktest.cli.__main__:main` and re-raises SystemExit so
+argparse error codes propagate.
+"""
+
+import sys
+
+from hqbacktest.cli.__main__ import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hqbacktest/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface for hqbacktest.
+
+The CLI is intentionally tiny: it loads a TOML config file, validates it,
+constructs a `BacktestConfig` and a strategy class, runs the backtest, and
+writes the result to an output directory. Heavy lifting lives in
+`engine` / `data` / `domain`; this package only orchestrates.
+"""

hqbacktest/cli/__main__.py

@@ -0,0 +1,109 @@
+"""Command-line entry point: `hqbacktest run --config FILE --output DIR`.
+
+Uses stdlib `argparse` (no new dependency). On any user-facing problem
+we print a single readable line on stderr and exit with a non-zero code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import sys
+from typing import Optional, Sequence
+
+from .config import ConfigError
+from .runner import RunResult, _prepare_sys_path, run_from_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hqbacktest",
+        description=("Run an A-share backtest from a TOML config file."),
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    run = sub.add_parser("run", help="Execute a backtest from a TOML config")
+    run.add_argument(
+        "--config",
+        required=True,
+        help="Path to the TOML config file (required).",
+    )
+    run.add_argument(
+        "--output",
+        required=False,
+        default=None,
+        help=(
+            "Output directory. When given, overrides [output].directory from "
+            "the config. Created if missing; receives config.toml, "
+            "run_metadata.json, events.jsonl, equity_curve.csv, orders.csv, "
+            "fills.csv, positions.csv, costs.csv and summary.json."
+        ),
+    )
+    run.add_argument(
+        "--force",
+        action="store_true",
+        help=(
+            "Overwrite an output directory that already contains " "prior-run files."
+        ),
+    )
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+
+    if args.command is None:
+        parser.print_help(sys.stderr)
+        return 1
+
+    if args.command == "run":
+        return _run(args)
+
+
+def _run(args: argparse.Namespace) -> int:
+    # Prepend the config file's directory and the current working directory
+    # to `sys.path` so the strategy module can be resolved by name alone,
+    # matching the documented "first-mile" workflow. This mirrors what
+    # `python -m` would do for an in-tree import and makes the console
+    # script behave the same way as `python -m hqbacktest run`.
+    _prepare_sys_path(args.config)
+    # Honor a test-only env hook so the CLI can be driven against an
+    # in-memory portal in subprocess tests without touching the real
+    # `~/.hqdata` snapshot.
+    _maybe_load_test_bootstrap()
+    try:
+        result: RunResult = run_from_file(
+            args.config, output_dir=args.output, force=args.force
+        )
+    except ConfigError as exc:
+        print(f"hqbacktest: {exc}", file=sys.stderr)
+        return 2
+
+    if result.exit_code != 0:
+        print(
+            f"hqbacktest: {result.message or 'run failed'}",
+            file=sys.stderr,
+        )
+        return result.exit_code
+
+    print(f"hqbacktest: wrote results to {result.output_dir}")
+    return 0
+
+
+def _maybe_load_test_bootstrap() -> None:
+    """If `HQBACKTEST_CLI_BOOTSTRAP` is set, import that module by name.
+
+    Test-only hook used by `tests/cli/test_cli_validation.py` to swap
+    the portal builder in a subprocess without writing to the real
+    `~/.hqdata` snapshot. Production users never set this.
+    """
+    name = os.environ.get("HQBACKTEST_CLI_BOOTSTRAP")
+    if not name:
+        return
+    importlib.import_module(name)
+
+
+__all__ = ["build_parser", "main"]

hqbacktest/cli/config.py

@@ -0,0 +1,380 @@
+"""Config file loading and validation.
+
+The TOML schema (one example):
+
+    [start]
+    start_date = "20240102"   # YYYYMMDD, required
+    end_date   = "20240104"   # YYYYMMDD, required
+
+    [capital]
+    initial_cash = "100000"   # Decimal-string, required
+
+    [data]
+    source = "tushare"        # name or absolute path, required
+    data_root = "~/.hqdata"   # optional, defaults to ~/.hqdata
+
+    [strategy]
+    module = "examples.buy_and_hold"  # importable Python module, required
+    class_name = "BuyAndHold"           # optional, defaults to first subclass
+    kwargs = {}                          # optional, passed to constructor
+
+    [cost_model]
+    commission_rate = "0.00025"          # optional
+    min_commission  = "5.00"             # optional
+    stamp_tax_rate  = "0.001"            # optional
+    transfer_fee_rate = "0.0"            # optional
+
+    [output]
+    directory = "results/run-1"         # required, will be created
+
+Validation rules are deliberately strict: any unknown key is rejected so
+typos surface immediately. The CLI re-emits every user-facing error as
+`ConfigError` which becomes a non-zero exit code with a single readable
+message on stderr.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from dataclasses import dataclass, field
+from decimal import Decimal
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Type
+
+import tomli
+
+from ..data.hqdata_portal import DEFAULT_DATA_ROOT
+from ..data.validators import validate_yyyymmdd
+from ..domain.enums import OrderType
+from ..engine.cost_model import DefaultCostModel
+from ..engine.rule_set import DEFAULT_V01_RULES, TradingRuleSet
+from ..engine.strategy import BaseStrategy
+
+
+# Hard-coded allowed top-level sections. Anything else is rejected.
+_ALLOWED_SECTIONS: tuple[str, ...] = (
+    "start",
+    "capital",
+    "data",
+    "strategy",
+    "cost_model",
+    "output",
+)
+
+
+class ConfigError(ValueError):
+    """Raised on any user-facing configuration problem.
+
+    The CLI catches this and prints a single readable line on stderr
+    before exiting with a non-zero status.
+    """
+
+
+@dataclass(frozen=True)
+class ConfigFile:
+    """Validated view of the TOML config the user passed on the CLI.
+
+    All fields are required; defaults live in `BacktestConfig`.
+    """
+
+    start_date: str
+    end_date: str
+    initial_cash: Decimal
+    source: str
+    strategy_module: str
+    output_directory: str
+    data_root: str = DEFAULT_DATA_ROOT
+    strategy_class: Optional[str] = None
+    strategy_kwargs: Dict[str, Any] = field(default_factory=dict)
+    cost_overrides: Dict[str, Decimal] = field(default_factory=dict)
+    raw_text: str = ""  # exact bytes the user provided (for the audit trail)
+
+
+# --------------------------------------------------------------------- #
+# Loading
+# --------------------------------------------------------------------- #
+
+
+def load_config_file(path: str) -> ConfigFile:
+    """Load and validate a TOML config. Raises `ConfigError` on any issue."""
+    file_path = Path(path)
+    if not file_path.exists():
+        raise ConfigError(f"config file not found: {path}")
+    if not file_path.is_file():
+        raise ConfigError(f"config path is not a regular file: {path}")
+    try:
+        raw = file_path.read_bytes()
+    except OSError as exc:
+        raise ConfigError(f"cannot read config file {path}: {exc}") from exc
+    try:
+        data = tomli.loads(raw.decode("utf-8"))
+    except tomli.TOMLDecodeError as exc:
+        raise ConfigError(f"config file {path} is not valid TOML: {exc}") from exc
+    return _validate(data, raw_text=raw.decode("utf-8"))
+
+
+def _validate(data: Dict[str, Any], *, raw_text: str) -> ConfigFile:
+    """Validate the parsed TOML dict and build a `ConfigFile`.
+
+    All section names must be from `_ALLOWED_SECTIONS`; every required key
+    must be present and of the right type.
+    """
+    unknown_sections = sorted(set(data) - set(_ALLOWED_SECTIONS))
+    if unknown_sections:
+        raise ConfigError(
+            f"unknown config sections: {unknown_sections}; "
+            f"allowed: {list(_ALLOWED_SECTIONS)}"
+        )
+
+    # ---- [start] ----
+    start = data.get("start", {})
+    if not isinstance(start, dict):
+        raise ConfigError("[start] must be a table")
+    start_date = _require_str(start, "start", "start_date")
+    end_date = _require_str(start, "end", "end_date")
+    try:
+        validate_yyyymmdd(start_date, name="start.start_date")
+    except Exception as exc:
+        raise ConfigError(f"[start].start_date: {exc}") from exc
+    try:
+        validate_yyyymmdd(end_date, name="start.end_date")
+    except Exception as exc:
+        raise ConfigError(f"[start].end_date: {exc}") from exc
+    if start_date > end_date:
+        raise ConfigError(
+            f"[start] start_date {start_date} is after end_date {end_date}"
+        )
+
+    # ---- [capital] ----
+    capital = data.get("capital", {})
+    if not isinstance(capital, dict):
+        raise ConfigError("[capital] must be a table")
+    initial_cash = _require_decimal(
+        capital, "capital", "initial_cash", min_value=Decimal("0")
+    )
+
+    # ---- [data] ----
+    data_sec = data.get("data", {})
+    if not isinstance(data_sec, dict):
+        raise ConfigError("[data] must be a table")
+    source = _require_str(data_sec, "data", "source")
+    data_root = data_sec.get("data_root")
+    if data_root is None:
+        data_root = DEFAULT_DATA_ROOT
+    elif not isinstance(data_root, str) or not data_root:
+        raise ConfigError("[data].data_root must be a non-empty string")
+
+    # ---- [strategy] ----
+    strat = data.get("strategy", {})
+    if not isinstance(strat, dict):
+        raise ConfigError("[strategy] must be a table")
+    strategy_module = _require_str(strat, "strategy", "module")
+    strategy_class = strat.get("class_name")
+    if strategy_class is not None and not isinstance(strategy_class, str):
+        raise ConfigError("[strategy].class_name must be a string")
+    strategy_kwargs = strat.get("kwargs", {})
+    if strategy_kwargs is None:
+        strategy_kwargs = {}
+    if not isinstance(strategy_kwargs, dict):
+        raise ConfigError("[strategy].kwargs must be a table")
+
+    # ---- [cost_model] (optional) ----
+    cost_sec = data.get("cost_model", {})
+    if not isinstance(cost_sec, dict):
+        raise ConfigError("[cost_model] must be a table")
+    cost_overrides: Dict[str, Decimal] = {}
+    for key, attr in (
+        ("commission_rate", "commission_rate"),
+        ("min_commission", "min_commission"),
+        ("stamp_tax_rate", "stamp_tax_rate"),
+        ("transfer_fee_rate", "transfer_fee_rate"),
+    ):
+        if key in cost_sec:
+            cost_overrides[attr] = _require_decimal(
+                cost_sec, "cost_model", key, min_value=Decimal("0")
+            )
+
+    # ---- [output] ----
+    out = data.get("output", {})
+    if not isinstance(out, dict):
+        raise ConfigError("[output] must be a table")
+    output_directory = _require_str(out, "output", "directory")
+
+    return ConfigFile(
+        start_date=start_date,
+        end_date=end_date,
+        initial_cash=initial_cash,
+        source=source,
+        strategy_module=strategy_module,
+        strategy_class=strategy_class,
+        strategy_kwargs=strategy_kwargs,
+        cost_overrides=cost_overrides,
+        output_directory=output_directory,
+        data_root=data_root,
+        raw_text=raw_text,
+    )
+
+
+def _require_str(section: Dict[str, Any], section_name: str, key: str) -> str:
+    if key not in section:
+        raise ConfigError(f"[{section_name}] missing required key {key!r}")
+    value = section[key]
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"[{section_name}].{key} must be a non-empty string")
+    return value
+
+
+def _require_decimal(
+    section: Dict[str, Any],
+    section_name: str,
+    key: str,
+    *,
+    min_value: Optional[Decimal] = None,
+) -> Decimal:
+    if key not in section:
+        raise ConfigError(f"[{section_name}] missing required key {key!r}")
+    value = section[key]
+    if isinstance(value, bool):
+        raise ConfigError(f"[{section_name}].{key} must be a number, not bool")
+    # Float is forbidden at the CLI layer too, matching the engine's
+    # contract rule 5. Without this check a TOML like
+    # `initial_cash = 100000.0` would silently convert to a Decimal via
+    # `Decimal(str(float))`, masking the precision concern.
+    if isinstance(value, float):
+        raise ConfigError(
+            f"[{section_name}].{key} must be int/str/Decimal; float is "
+            "forbidden (contract rule 5)"
+        )
+    if isinstance(value, (int, str)):
+        try:
+            d = Decimal(str(value))
+        except Exception as exc:
+            raise ConfigError(
+                f"[{section_name}].{key}={value!r} is not a valid number: {exc}"
+            ) from exc
+    elif isinstance(value, Decimal):
+        d = value
+    else:
+        raise ConfigError(
+            f"[{section_name}].{key} must be a number, got {type(value).__name__}"
+        )
+    # NaN / +Inf / -Inf are technically parseable by `Decimal(str('nan'))`
+    # but break every downstream comparison (e.g. `nan < 0` raises
+    # InvalidOperation). Reject them here so the user gets a clean
+    # single-line ConfigError instead of a traceback.
+    if not d.is_finite():
+        raise ConfigError(
+            f"[{section_name}].{key}={d} must be a finite number "
+            "(NaN / +Inf / -Inf are not allowed)"
+        )
+    if min_value is not None and d < min_value:
+        raise ConfigError(f"[{section_name}].{key}={d} must be >= {min_value}")
+    return d
+
+
+# --------------------------------------------------------------------- #
+# Resolving strategy + BacktestConfig
+# --------------------------------------------------------------------- #
+
+
+def resolve_strategy(config_file: ConfigFile) -> BaseStrategy:
+    """Import the user-supplied module and instantiate the strategy class.
+
+    `class_name` is optional; when omitted we use the first `BaseStrategy`
+    subclass exported by the module.
+    """
+    try:
+        module = importlib.import_module(config_file.strategy_module)
+    except ImportError as exc:
+        raise ConfigError(
+            f"could not import strategy module {config_file.strategy_module!r}: {exc}"
+        ) from exc
+
+    cls: Optional[Type[BaseStrategy]] = None
+    if config_file.strategy_class is not None:
+        candidate = getattr(module, config_file.strategy_class, None)
+        if candidate is None:
+            raise ConfigError(
+                f"module {config_file.strategy_module!r} has no attribute "
+                f"{config_file.strategy_class!r}"
+            )
+        if not (inspect.isclass(candidate) and issubclass(candidate, BaseStrategy)):
+            raise ConfigError(
+                f"{config_file.strategy_class!r} is not a BaseStrategy subclass"
+            )
+        cls = candidate
+    else:
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if obj is BaseStrategy:
+                continue
+            if issubclass(obj, BaseStrategy):
+                cls = obj
+                break
+        if cls is None:
+            raise ConfigError(
+                f"no BaseStrategy subclass found in {config_file.strategy_module!r}; "
+                "either define one or set [strategy].class_name"
+            )
+
+    # Constructor kwargs come straight from the user. We do NOT inspect
+    # the constructor signature; users are responsible for matching it.
+    try:
+        return cls(**config_file.strategy_kwargs)
+    except TypeError as exc:
+        raise ConfigError(
+            f"failed to construct {cls.__name__} with kwargs "
+            f"{config_file.strategy_kwargs}: {exc}"
+        ) from exc
+    except Exception as exc:  # pragma: no cover - defensive
+        raise ConfigError(
+            f"unexpected error constructing {cls.__name__}: {exc}"
+        ) from exc
+
+
+def build_backtest_config(
+    config_file: ConfigFile,
+) -> "BacktestConfig":  # type: ignore[name-defined]
+    """Translate the validated config file into a runtime `BacktestConfig`."""
+    from ..engine.config import BacktestConfig  # local to break circular import
+
+    cost_model = DefaultCostModel()
+    if config_file.cost_overrides:
+        cost_model = DefaultCostModel(
+            commission_rate=config_file.cost_overrides.get(
+                "commission_rate", cost_model.commission_rate
+            ),
+            min_commission=config_file.cost_overrides.get(
+                "min_commission", cost_model.min_commission
+            ),
+            stamp_tax_rate=config_file.cost_overrides.get(
+                "stamp_tax_rate", cost_model.stamp_tax_rate
+            ),
+            transfer_fee_rate=config_file.cost_overrides.get(
+                "transfer_fee_rate", cost_model.transfer_fee_rate
+            ),
+        )
+
+    return BacktestConfig(
+        start_date=config_file.start_date,
+        end_date=config_file.end_date,
+        initial_cash=config_file.initial_cash,
+        source=config_file.source,
+        data_root=config_file.data_root,
+        rule_set=TradingRuleSet(DEFAULT_V01_RULES),
+        cost_model=cost_model,
+    )
+
+
+# Re-export for convenience; `OrderType` import keeps linters happy in
+# downstream code that imports from this module.
+__all__ = [
+    "ConfigError",
+    "ConfigFile",
+    "build_backtest_config",
+    "load_config_file",
+    "resolve_strategy",
+]
+# `OrderType` is intentionally imported above to keep the public-API
+# surface in sync with the rest of the engine layer.
+_ = OrderType