wbt Python Package

Python API for the wbt Rust backtesting engine.

Development Objectives

This Python subproject aims to provide a practical research-facing interface for weight-based backtesting while keeping the heavy computation in Rust.

Design priorities:

Keep data input flexible for common research formats.
Return analysis-friendly outputs as pandas objects.
Preserve one consistent metric schema across stats outputs.
Provide plotting utilities that work directly on backtest outputs.

Project Layout

This directory is an independent Python subproject.

python/
|-- pyproject.toml
|-- README.md
|-- scripts/
|-- tests/
`-- wbt/

The Rust crate remains one level up at ../Cargo.toml. maturin builds the extension module from there.

Installation And Local Setup

Requirements:

Rust toolchain
Python 3.10+
uv

Setup:

cd python
uv sync --extra dev
uv run maturin develop --release

Quick Start

import pandas as pd
from wbt import WeightBacktest

df = pd.DataFrame(
    {
        "dt": [
            "2024-01-02 09:01:00",
            "2024-01-02 09:02:00",
            "2024-01-02 09:03:00",
            "2024-01-02 09:04:00",
        ],
        "symbol": ["AAPL", "AAPL", "AAPL", "AAPL"],
        "weight": [0.5, 0.2, 0.0, -0.3],
        "price": [185.0, 186.0, 186.5, 184.5],
    }
)

wb = WeightBacktest(
    df,
    digits=2,
    fee_rate=0.0002,
    n_jobs=4,
    weight_type="ts",   # "ts" or "cs"
    yearly_days=252,
)

print("all:", wb.stats)
print("long:", wb.long_stats)
print("short:", wb.short_stats)

print(wb.daily_return.head())
print(wb.dailys.head())
print(wb.pairs.head())

print(wb.segment_stats("2024-01-01", "2024-12-31", kind="多空"))
print(wb.long_alpha_stats)

Accepted Inputs

The data argument accepts:

pandas.DataFrame
polars.DataFrame
polars.LazyFrame
file path as str or Path

Supported file formats from path input:

csv
parquet
feather
arrow

Required columns:

Column	Type	Meaning
dt	datetime-like	Bar end time
symbol	str	Instrument code
weight	float	Target position weight
price	float	Price used for return calculation

Notes:

Null values are not allowed.
weight is rounded by digits before backtest.

Main API Surface

Top-level imports (all reachable from import wbt):

from wbt import (
    # Backtest engine
    WeightBacktest, backtest,
    # Performance metrics (Rust-backed)
    daily_performance,
    top_drawdowns,
    rolling_daily_performance,
    cal_yearly_days,
    # Strategy utilities (pure Python)
    weights_simple_ensemble,
    cal_trade_price,
    log_strategy_info,
    # Reporting
    generate_backtest_report,
    # Test data
    mock_symbol_kline, mock_weights,
)

Primary class and helpers:

WeightBacktest(...): main backtest engine entry.
backtest(...): convenience wrapper returning a WeightBacktest.
daily_performance(returns, yearly_days=252): standalone metric utility on a daily-return array.
top_drawdowns(returns, top=10): top-N drawdown windows.
rolling_daily_performance(df, ret_col, window=252, min_periods=100, yearly_days=None): rolling-window daily performance.
cal_yearly_days(dts): infer yearly trading-day count from a date series.
weights_simple_ensemble(df, weight_cols, method="mean", only_long=False, **kwargs): ensemble multiple strategy weights (mean / vote / sum_clip).
cal_trade_price(df, digits=None, windows=(5, 10, 15, 20, 30, 60)): TWAP / VWAP and next-bar trade-price table grouped by symbol.
log_strategy_info(strategy, df): pretty-print per-symbol weight summaries via loguru.
generate_backtest_report(wb, output_path): render a self-contained HTML report.
mock_symbol_kline(...) / mock_weights(...): generators for quick experiments.

Core WeightBacktest properties and methods:

stats, long_stats, short_stats
daily_return, long_daily_return, short_daily_return
dailys, pairs
alpha, alpha_stats, bench_stats
segment_stats(sdt, edt, kind)
long_alpha_stats
get_symbol_daily(symbol), get_symbol_pairs(symbol)

Logging Note

cal_yearly_days and rolling_daily_performance emit warnings from Rust (e.g. short-span fallback) via the log crate. The package initializes pyo3-log at module load, so those warnings show up through Python's standard logging. If you use loguru, install an InterceptHandler once to route them into your loguru sinks.

Plotting Utilities

All plotting functions are single-purpose figures that consume a BacktestResult (from wb.to_result()) with zero data transformation — each field maps straight to a plotly trace. There are no composite (subplot) charts; the HTML report composes single figures into a CSS grid instead.

from wbt.plotting import (
    plot_colored_table,        # stats as a colored table
    plot_cumulative_returns,   # cumulative curves (voladj=True for vol-normalized)
    plot_daily_return_dist,    # daily-return histogram
    plot_drawdown,             # drawdown + cumulative (dual-axis single figure)
    plot_drawdowns_table,      # top-drawdowns detail table
    plot_key_trades,           # yearly best/worst key trades
    plot_monthly_heatmap,      # monthly-return heatmap
    plot_pairs_hold_dist,      # holding-bars distribution by direction
    plot_pairs_pnl_dist,       # pnl-ratio distribution by direction
    plot_rolling_metrics,      # rolling sharpe/return/vol over time (252d window)
    plot_segment_comparison,   # recent-1y vs full-sample metric table
    plot_stats_comparison,     # 多空/多头/空头/基准/超额 metric comparison table
    plot_symbol_returns,       # per-symbol cumulative returns
    plot_verdict,              # is_good_strategy verdict + yearly metrics
    plot_yearly_returns,       # yearly absolute vs excess returns (grouped bars)
)

Typical usage:

result = wb.to_result()

fig1 = plot_cumulative_returns(result, keys=["多空", "多头", "空头", "基准"])
fig2 = plot_cumulative_returns(result, voladj=True)   # vol-normalized
fig3 = plot_drawdown(result)
fig4 = plot_pairs_pnl_dist(result)

# Optional HTML export
html = plot_cumulative_returns(result, to_html=True)

# Full HTML report file (composes single figures into a tabbed CSS grid)
generate_backtest_report(df, "report.html")

Quality And Testing

Run checks from python/:

uv run pytest -v
uv run ruff format --check .
uv run ruff check . --no-fix
uv run basedpyright

Architecture Snapshot

repo-root/
|-- Cargo.toml
|-- src/
|   |-- lib.rs                       # pure Rust crate entry; Python bindings are off by default
|   |-- python.rs                    # PyO3 bindings (enabled by the python feature)
|   `-- core/
|       |-- cal_yearly_days.rs       # Rust core for cal_yearly_days
|       |-- daily_performance.rs
|       |-- rolling_daily_performance.rs
|       |-- top_drawdowns.rs
|       `-- ...                      # backtest engine internals
`-- python/
    `-- wbt/
        |-- __init__.py              # top-level exports
        |-- _df_convert.py           # pandas <-> Arrow IPC helpers
        |-- _wbt.pyi                 # Rust extension stubs
        |-- backtest.py              # WeightBacktest class
        |-- mock.py                  # mock_symbol_kline / mock_weights
        |-- top_drawdowns.py         # adapter for _wbt.top_drawdowns
        |-- utils/                   # adapters + pure-Python utilities
        |   |-- __init__.py
        |   |-- cal_yearly_days.py
        |   |-- rolling_daily_performance.py
        |   |-- weights_simple_ensemble.py
        |   |-- cal_trade_price.py
        |   `-- log_strategy_info.py
        |-- plotting/                # single-purpose plotly charts
        |   |-- __init__.py
        |   |-- _common.py
        |   |-- returns.py
        |   |-- risk.py
        |   |-- trades.py
        |   `-- overview.py
        `-- report/                  # HTML report + composite charts
            |-- __init__.py
            |-- _generator.py
            |-- _plot_backtest.py
            `-- html_builder.py

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wbt-0.4.2.tar.gz (2.2 MB view details)

Uploaded Jul 6, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

wbt-0.4.2-cp310-abi3-win_amd64.whl (21.3 MB view details)

Uploaded Jul 6, 2026 CPython 3.10+Windows x86-64

wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl (19.6 MB view details)

Uploaded Jul 6, 2026 CPython 3.10+manylinux: glibc 2.28+ x86-64

wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl (18.0 MB view details)

Uploaded Jul 6, 2026 CPython 3.10+manylinux: glibc 2.28+ ARM64

wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl (17.3 MB view details)

Uploaded Jul 6, 2026 CPython 3.10+macOS 11.0+ ARM64

wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl (19.0 MB view details)

Uploaded Jul 6, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file wbt-0.4.2.tar.gz.

File metadata

Download URL: wbt-0.4.2.tar.gz
Upload date: Jul 6, 2026
Size: 2.2 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2.tar.gz
Algorithm	Hash digest
SHA256	`000c0d2ad881384276ee523fcb76167ec481abf96132bd56e159cf2e32cf4934`
MD5	`f472745d3d188245c03c4655bb601245`
BLAKE2b-256	`0f0711f6d61c8899604934b133b311bdb69c2912b862c2538368fc218d795d2c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2.tar.gz:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2.tar.gz
- Subject digest: 000c0d2ad881384276ee523fcb76167ec481abf96132bd56e159cf2e32cf4934
- Sigstore transparency entry: 2084816343
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

File details

Details for the file wbt-0.4.2-cp310-abi3-win_amd64.whl.

File metadata

Download URL: wbt-0.4.2-cp310-abi3-win_amd64.whl
Upload date: Jul 6, 2026
Size: 21.3 MB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`e9d76f2542869e54670474aba05bd9645b1e5cfe3b5e25dd9ca9fc1a3515aaa4`
MD5	`d0420ab59960576b4978c837d720b3dd`
BLAKE2b-256	`da9c3b161b30750d21cc34db4c99e3bf526b8e0cbde0540a6333cca76283603b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2-cp310-abi3-win_amd64.whl:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2-cp310-abi3-win_amd64.whl
- Subject digest: e9d76f2542869e54670474aba05bd9645b1e5cfe3b5e25dd9ca9fc1a3515aaa4
- Sigstore transparency entry: 2084816361
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

File details

Details for the file wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl
Upload date: Jul 6, 2026
Size: 19.6 MB
Tags: CPython 3.10+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`ea3df8c8c806f71828183c68e1d57fc31aca12c0542515fec19eee20b2dd0200`
MD5	`0e2581c745663efe71fd5f147077b79e`
BLAKE2b-256	`e8799ccc38facc132992c619a7b28eba64e571add8f364d21e06d6ac8d7d9389`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2-cp310-abi3-manylinux_2_28_x86_64.whl
- Subject digest: ea3df8c8c806f71828183c68e1d57fc31aca12c0542515fec19eee20b2dd0200
- Sigstore transparency entry: 2084816366
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

File details

Details for the file wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

Download URL: wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl
Upload date: Jul 6, 2026
Size: 18.0 MB
Tags: CPython 3.10+, manylinux: glibc 2.28+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`ba60d170cdcc29e073d3007e51ca83539fcfe4dd23393140158618f14134585d`
MD5	`fe0d66e8b06e2335557adaada32e9083`
BLAKE2b-256	`ceab7514b01fc70df7699416a4627ce164c257b772e3f0aa0a75b97bf8d8e974`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2-cp310-abi3-manylinux_2_28_aarch64.whl
- Subject digest: ba60d170cdcc29e073d3007e51ca83539fcfe4dd23393140158618f14134585d
- Sigstore transparency entry: 2084816356
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

File details

Details for the file wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Jul 6, 2026
Size: 17.3 MB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`082241d0b1267682d7911aade027c2735fdaac899f387d73b6f637ad90cb7937`
MD5	`d0f7ab8100c3dbf536c8f25a5dba245f`
BLAKE2b-256	`0148704bbabaa95ca1089e978c29e1f0360a6377a2badb6b1871cbd1dd70c2a5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: 082241d0b1267682d7911aade027c2735fdaac899f387d73b6f637ad90cb7937
- Sigstore transparency entry: 2084816375
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

File details

Details for the file wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl
Upload date: Jul 6, 2026
Size: 19.0 MB
Tags: CPython 3.10+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`933f19cbfeaa1a7219d58d2ce737784eb90fece7052fd0a97e2250c521f80980`
MD5	`9f760de3b3ea4a4207a864cebabc1cff`
BLAKE2b-256	`08a90317945cc680b8324ac4a3fa279f92c8be02713553507824fc5917ea62c7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on zengbin93/wbt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wbt-0.4.2-cp310-abi3-macosx_10_12_x86_64.whl
- Subject digest: 933f19cbfeaa1a7219d58d2ce737784eb90fece7052fd0a97e2250c521f80980
- Sigstore transparency entry: 2084816348
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: zengbin93/wbt@baeda53c6419748227975846e296703186a4657e
- Branch / Tag: refs/tags/v0.4.2
- Owner: https://github.com/zengbin93
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baeda53c6419748227975846e296703186a4657e
- Trigger Event: push

Release history Release notifications | RSS feed

0.7.1

Aug 6, 2026

0.7.0

Jul 29, 2026

0.6.0

Jul 17, 2026

0.5.0

Jul 15, 2026

0.4.3

Jul 8, 2026

This release

0.4.2

Jul 6, 2026

0.4.1

Jun 26, 2026

0.4.0

Jun 25, 2026

0.3.2

May 30, 2026

0.3.1

May 30, 2026

0.3.0

May 29, 2026

0.2.3

May 23, 2026

0.2.2

May 23, 2026

0.2.1

May 17, 2026

0.2.0

May 17, 2026

0.1.8

May 14, 2026

0.1.7

May 6, 2026

0.1.6

Apr 23, 2026

0.1.5

Apr 20, 2026

0.1.4

Apr 20, 2026

0.1.3

Apr 3, 2026

0.1.2

Apr 2, 2026

0.1.1

Apr 2, 2026

wbt 0.4.2

wbt Python Package

Development Objectives

Project Layout

Installation And Local Setup

Quick Start

Accepted Inputs

Main API Surface

Logging Note

Plotting Utilities

Quality And Testing

Architecture Snapshot

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed