akquant-lwc 0.1.0__tar.gz

akquant_lwc-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Byte-compiled / build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Local test artifacts
+tmp_test/

akquant_lwc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AKQuant developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

akquant_lwc-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: akquant-lwc
+Version: 0.1.0
+Summary: TradingView Lightweight Charts backtest report & trade review plugin for AKQuant (plotly-free)
+Project-URL: Homepage, https://github.com/neoblackxt/akquant-lwc
+Project-URL: Repository, https://github.com/neoblackxt/akquant-lwc
+Project-URL: Issues, https://github.com/neoblackxt/akquant-lwc/issues
+Author-email: Neo Black <neoblackxt@outlook.com>
+License: MIT License
+License-File: LICENSE
+Keywords: akquant,backtest,lightweight-charts,quant,report,tradingview
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0.0
+Provides-Extra: dev
+Requires-Dist: akquant>=0.3.16; extra == 'dev'
+Requires-Dist: hatchling>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# akquant-lwc
+
+基于 **TradingView Lightweight Charts** 的 [AKQuant](https://github.com/akfamily/akquant) 回测报告与交易复盘插件（plotly 替代方案）。
+
+图表库已 vendored 进包内，生成的报告为**单文件 HTML，离线可开**；复盘标的支持**网页内热切换**。
+
+![报告总览](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/report-overview.png)
+
+## 为什么不用 plotly
+
+原版 plotly 报告在交易复盘（K线买卖点）场景下的痛点：
+
+- 买卖点标记与 K 线图案区分度不够，难以快速定位开平仓；
+- 鼠标左键拖拽平移、滚轮缩放交互不友好；
+- 缩放平移时 y 轴不自动贴合可视区数据，图像经常在垂直方向上偏出合理区域；
+- plotly.js ~3.5MB 且走 CDN，离线/弱网环境报告无法打开。
+
+Lightweight Charts 是 TradingView 开源的金融图表库：拖拽平移、以鼠标为中心的滚轮缩放、可视区 y 轴自动缩放均为原生行为，体积仅 ~160KB。
+
+## 安装
+
+```bash
+pip install akquant-lwc
+```
+
+或从源码安装：
+
+```bash
+pip install git+https://github.com/neoblackxt/akquant-lwc.git
+```
+
+## 快速开始
+
+```python
+import akquant_lwc  # 导入即自动给 BacktestResult 注入 report_lwc / serve_review
+from akquant import run_backtest
+
+result = run_backtest(...)
+
+# 1) 静态单文件报告（含交易复盘，页面内可热切换标的）
+result.report_lwc(
+    market_data={"600000": df1, "600004": df2},  # {symbol: DataFrame}
+    filename="akquant_lwc_report.html",
+    show=True,
+)
+
+# 2) 交互式复盘服务：页面输入任意代码，服务端按需加载
+result.serve_review(
+    market_data={"600000": df1},
+    data_provider=lambda code: load_df(code),  # 可选，解析未预载的代码
+    port=8765,
+)
+```
+
+也可以不依赖注入，直接调用模块级函数（对任何带 `trades_df` /
+`equity_curve` / `metrics` / `trade_metrics` 属性的结果对象都可用）：
+
+```python
+from akquant_lwc import plot_report, serve_review
+
+plot_report(result, market_data={"600000": df1}, filename="report.html")
+serve_review(result, market_data={"600000": df1})
+```
+
+## 功能
+
+**报告区块（全面对齐原版 plotly 报告）**
+
+- 报告概要（回测区间、初始/期末资金、持续天数）
+- 绩效指标卡（收益/回撤/夏普/索提诺/卡玛/波动率/胜率/盈亏比/SQN 等）
+- 净值曲线 + 回撤曲线（时间轴联动）
+- 滚动指标（滚动夏普/波动率）、日收益分布、年度收益、月度收益热力图
+- 基准对比（累计收益/超额收益曲线，年化超额、跟踪误差、信息比率、Beta、Alpha）
+- 交易分析：盈亏分布、盈亏 vs 持仓时长散点（悬停显示完整交易卡片，
+  **点击散点直接联动下方 K 线复盘图切换标的**）
+- 风控拒单分析（策略级占比、原因占比、按日趋势、强平审计）
+- 明细表：交易/委托/成交/持仓/风险敞口/归因/容量分析
+- 自定义指标预览区块（`include_indicators=True`）
+
+**交易复盘（K线买卖点）**
+
+- 代码输入框 + 自动补全，回车即热切换复盘标的，无需重新生成报告
+- B/S 箭头标记开平仓（A股红涨绿跌配色），悬停显示开平仓时间/价格/收益率/净利润
+- 交易明细表点击行自动缩放到该笔交易区间
+- 服务模式支持 `data_provider` 回调，页面可解析任意新代码
+
+![买卖点复盘](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/trade-review-markers.png)
+
+![悬停交易详情](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/trade-tooltip.png)
+
+## API
+
+### `plot_report(result, market_data=None, title=..., filename=..., symbols=None, plot_symbol=None, show=False, benchmark=None, compact_currency=True, include_indicators=False, curve_freq="D") -> str`
+
+生成静态单文件报告，返回文件绝对路径。
+
+- `market_data`: `{symbol: DataFrame}` 字典、单只 DataFrame，或带 symbol 列的长表（OHLCV 列容忍中英文命名）
+- `symbols`: 仅内嵌指定标的子集
+- `benchmark`: 基准收益率序列（`pd.Series`）
+
+### `serve_review(result, market_data=None, data_provider=None, host="127.0.0.1", port=8765, title=..., open_browser=True)`
+
+启动交互式复盘服务（阻塞，Ctrl+C 停止）。
+
+- `data_provider`: `(code) -> DataFrame` 回调，解析 `market_data` 中不存在的代码
+
+### `BacktestResult.report_lwc(...) / .serve_review(...)`
+
+导入 `akquant_lwc` 后自动注入，参数同上。未安装 akquant 时注入自动跳过，模块级函数不受影响。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+ruff check src/
+```
+
+## License
+
+MIT。内嵌的 [Lightweight Charts](https://github.com/tradingview/lightweight-charts)
+遵循 Apache License 2.0。

akquant_lwc-0.1.0/README.md

@@ -0,0 +1,122 @@
+# akquant-lwc
+
+基于 **TradingView Lightweight Charts** 的 [AKQuant](https://github.com/akfamily/akquant) 回测报告与交易复盘插件（plotly 替代方案）。
+
+图表库已 vendored 进包内，生成的报告为**单文件 HTML，离线可开**；复盘标的支持**网页内热切换**。
+
+![报告总览](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/report-overview.png)
+
+## 为什么不用 plotly
+
+原版 plotly 报告在交易复盘（K线买卖点）场景下的痛点：
+
+- 买卖点标记与 K 线图案区分度不够，难以快速定位开平仓；
+- 鼠标左键拖拽平移、滚轮缩放交互不友好；
+- 缩放平移时 y 轴不自动贴合可视区数据，图像经常在垂直方向上偏出合理区域；
+- plotly.js ~3.5MB 且走 CDN，离线/弱网环境报告无法打开。
+
+Lightweight Charts 是 TradingView 开源的金融图表库：拖拽平移、以鼠标为中心的滚轮缩放、可视区 y 轴自动缩放均为原生行为，体积仅 ~160KB。
+
+## 安装
+
+```bash
+pip install akquant-lwc
+```
+
+或从源码安装：
+
+```bash
+pip install git+https://github.com/neoblackxt/akquant-lwc.git
+```
+
+## 快速开始
+
+```python
+import akquant_lwc  # 导入即自动给 BacktestResult 注入 report_lwc / serve_review
+from akquant import run_backtest
+
+result = run_backtest(...)
+
+# 1) 静态单文件报告（含交易复盘，页面内可热切换标的）
+result.report_lwc(
+    market_data={"600000": df1, "600004": df2},  # {symbol: DataFrame}
+    filename="akquant_lwc_report.html",
+    show=True,
+)
+
+# 2) 交互式复盘服务：页面输入任意代码，服务端按需加载
+result.serve_review(
+    market_data={"600000": df1},
+    data_provider=lambda code: load_df(code),  # 可选，解析未预载的代码
+    port=8765,
+)
+```
+
+也可以不依赖注入，直接调用模块级函数（对任何带 `trades_df` /
+`equity_curve` / `metrics` / `trade_metrics` 属性的结果对象都可用）：
+
+```python
+from akquant_lwc import plot_report, serve_review
+
+plot_report(result, market_data={"600000": df1}, filename="report.html")
+serve_review(result, market_data={"600000": df1})
+```
+
+## 功能
+
+**报告区块（全面对齐原版 plotly 报告）**
+
+- 报告概要（回测区间、初始/期末资金、持续天数）
+- 绩效指标卡（收益/回撤/夏普/索提诺/卡玛/波动率/胜率/盈亏比/SQN 等）
+- 净值曲线 + 回撤曲线（时间轴联动）
+- 滚动指标（滚动夏普/波动率）、日收益分布、年度收益、月度收益热力图
+- 基准对比（累计收益/超额收益曲线，年化超额、跟踪误差、信息比率、Beta、Alpha）
+- 交易分析：盈亏分布、盈亏 vs 持仓时长散点（悬停显示完整交易卡片，
+  **点击散点直接联动下方 K 线复盘图切换标的**）
+- 风控拒单分析（策略级占比、原因占比、按日趋势、强平审计）
+- 明细表：交易/委托/成交/持仓/风险敞口/归因/容量分析
+- 自定义指标预览区块（`include_indicators=True`）
+
+**交易复盘（K线买卖点）**
+
+- 代码输入框 + 自动补全，回车即热切换复盘标的，无需重新生成报告
+- B/S 箭头标记开平仓（A股红涨绿跌配色），悬停显示开平仓时间/价格/收益率/净利润
+- 交易明细表点击行自动缩放到该笔交易区间
+- 服务模式支持 `data_provider` 回调，页面可解析任意新代码
+
+![买卖点复盘](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/trade-review-markers.png)
+
+![悬停交易详情](https://raw.githubusercontent.com/neoblackxt/akquant-lwc/main/docs/assets/trade-tooltip.png)
+
+## API
+
+### `plot_report(result, market_data=None, title=..., filename=..., symbols=None, plot_symbol=None, show=False, benchmark=None, compact_currency=True, include_indicators=False, curve_freq="D") -> str`
+
+生成静态单文件报告，返回文件绝对路径。
+
+- `market_data`: `{symbol: DataFrame}` 字典、单只 DataFrame，或带 symbol 列的长表（OHLCV 列容忍中英文命名）
+- `symbols`: 仅内嵌指定标的子集
+- `benchmark`: 基准收益率序列（`pd.Series`）
+
+### `serve_review(result, market_data=None, data_provider=None, host="127.0.0.1", port=8765, title=..., open_browser=True)`
+
+启动交互式复盘服务（阻塞，Ctrl+C 停止）。
+
+- `data_provider`: `(code) -> DataFrame` 回调，解析 `market_data` 中不存在的代码
+
+### `BacktestResult.report_lwc(...) / .serve_review(...)`
+
+导入 `akquant_lwc` 后自动注入，参数同上。未安装 akquant 时注入自动跳过，模块级函数不受影响。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+ruff check src/
+```
+
+## License
+
+MIT。内嵌的 [Lightweight Charts](https://github.com/tradingview/lightweight-charts)
+遵循 Apache License 2.0。

akquant_lwc-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "akquant-lwc"
+version = "0.1.0"
+description = "TradingView Lightweight Charts backtest report & trade review plugin for AKQuant (plotly-free)"
+readme = "README.md"
+license = { text = "MIT License" }
+authors = [{ name = "Neo Black", email = "neoblackxt@outlook.com" }]
+keywords = [
+    "akquant",
+    "lightweight-charts",
+    "tradingview",
+    "backtest",
+    "report",
+    "quant",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+]
+requires-python = ">=3.10"
+dependencies = ["pandas>=2.0.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "akquant>=0.3.16", "ruff>=0.1.0", "hatchling>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/neoblackxt/akquant-lwc"
+Repository = "https://github.com/neoblackxt/akquant-lwc"
+Issues = "https://github.com/neoblackxt/akquant-lwc/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/akquant_lwc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/akquant_lwc", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "D"]
+ignore = ["D100", "D104"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+# HTML/JS live inside string constants; long lines are unavoidable there.
+"src/akquant_lwc/_template.py" = ["E501"]
+"src/akquant_lwc/_app_js.py" = ["E501"]

akquant_lwc-0.1.0/src/akquant_lwc/__init__.py

@@ -0,0 +1,39 @@
+"""akquant-lwc: TradingView Lightweight Charts reporting plugin for AKQuant.
+
+A drop-in, plotly-free replacement of AKQuant's built-in HTML backtest
+report, powered by TradingView Lightweight Charts (vendored, works offline).
+
+Usage with AKQuant::
+
+    import akquant_lwc  # patches BacktestResult on import
+
+    result = run_backtest(...)
+    result.report_lwc(market_data={"600000": df}, show=True)
+    result.serve_review(market_data={"600000": df}, port=8765)
+
+The module-level functions accept any duck-typed result object (anything
+exposing ``trades_df`` / ``equity_curve`` / ``metrics`` / ``trade_metrics``),
+so the plugin also works without the patch or with akquant not installed::
+
+    from akquant_lwc import plot_report, serve_review
+
+    plot_report(result, market_data={"600000": df}, filename="report.html")
+    serve_review(result, market_data={"600000": df})
+"""
+
+from ._patch import patch_result_methods
+from .report import build_app_data, plot_report, render_html
+from .server import serve_review
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "build_app_data",
+    "patch_result_methods",
+    "plot_report",
+    "render_html",
+    "serve_review",
+]
+
+# Auto-patch BacktestResult on import (idempotent, skipped without akquant).
+patch_result_methods()