docs 目录代码验证报告¶
验证日期:2026-06-28 验证环境:conda 环境
lean(Python 3.11.13) 验证范围:docs/目录下全部 11 个 Python 示例文件 验证方式:字节码编译(语法)+ AST / pyflakes 静态分析 + 运行时导入探测
一、结论速览(TL;DR)¶
| 维度 | 结果 |
|---|---|
| 语法编译(py_compile) | 11 通过 / 0 失败 ✅(4 文件、5 处 f-string Bug 已于 2026-06-28 修复) |
| 静态分析(pyflakes) | 原 4 个硬错误已全部修复;仅余若干低优先级风格提示(见第四节) |
| 运行时导入(数据科学依赖) | ✅ pandas / numpy / scipy / matplotlib 均可导入 |
| 运行时导入(Lean 符号) | ⚠️ AlgorithmImports 在本环境为空命名空间包,QCAlgorithm 等符号不可用 |
| 完整回测执行 | ⛔ 未执行(需 Lean 引擎 + Docker + 行情数据,见第六节) |
关键发现(✅ 已修复):原 4 个文件存在多行 f-string SyntaxError(其中 06-indicators-demo.py 有 2 处,共 5 处编辑),已于 2026-06-28 全部修复,现 11/11 通过编译。 详见第三节。
二、环境搭建(可复现)¶
2.1 创建 conda 环境¶
conda create -y -n lean python=3.11
选用 Python 3.11:与教程大纲(
docs/tutorial-outline.md第 81-94 行「Python 环境配置」)以及 QuantConnect Lean 运行时所使用的 Python 版本一致。
2.2 安装验证依赖¶
# 激活环境后,或直接用环境内 pip:
/Users/henrylin/anaconda3/envs/lean/bin/python -m pip install \
pandas numpy scipy matplotlib quantconnect-stubs pyflakes
已安装版本:
| 包 | 版本 | 用途 |
|---|---|---|
| pandas | 3.0.3 | 10-research-demo.py 数据处理 |
| numpy | 2.4.6 | 10-research-demo.py 数值计算 |
| scipy | 1.17.1 | 10-research-demo.py 概率图 |
| matplotlib | 3.11.0 | 10-research-demo.py 可视化 |
| quantconnect-stubs | 17877 | Lean API 类型存根(仅 IDE/类型检查用) |
| pyflakes | 3.4.0 | 静态分析 |
2.3 验证命令¶
LEAN_PY=/Users/henrylin/anaconda3/envs/lean/bin/python
# 语法编译
$LEAN_PY -m py_compile docs/**/*.py
# 静态分析(过滤来自 star import 的 F403/F405 噪音)
$LEAN_PY -m pyflakes docs/**/*.py
三、语法验证详情(py_compile / AST)¶
3.1 逐文件结果¶
| # | 文件 | 行数 | 语法 | 说明 |
|---|---|---|---|---|
| 1 | 01-introduction/01-hello-world.py |
84 | ✅ PASS | Hello World 买持策略 |
| 2 | 01-introduction/03-sma-cross.py |
250 | ✅ PASS | SMA 金叉/死叉 + 止损变体 |
| 3 | 02-strategy-basics/04-qcalgorithm-demo.py |
397 | ✅ PASS | QCAlgorithm 生命周期 |
| 4 | 02-strategy-basics/05-order-management-demo.py |
505 | ✅ PASS | 各类订单 / OrderTicket |
| 5 | 02-strategy-basics/06-indicators-demo.py |
512 | ✅ PASS(已修复, 原 364 / 471) | 多指标 + 自定义指标 |
| 6 | 02-strategy-basics/07-data-demo.py |
503 | ✅ PASS(已修复, 原 449) | History / Universe / 自定义数据 |
| 7 | 03-advanced/08-framework-demo.py |
702 | ✅ PASS | Alpha/组合/执行/风险 五模型 |
| 8 | 03-advanced/09-advanced-features-demo.py |
622 | ✅ PASS(已修复, 原 621) | 期权 / 期货 / 自定义模型 |
| 9 | 03-advanced/10-research-demo.py |
515 | ✅ PASS | QuantBook 研究脚本(notebook 风格) |
| 10 | 04-backtesting-optimization/12-optimization-demo.py |
470 | ✅ PASS(已修复, 原 468) | 可优化策略 / 滚动优化 |
| 11 | 06-data-management/15-data-demo.py |
541 | ✅ PASS | 自定义数据 / 数据质量校验 |
3.2 失败根因:多行 f-string 替换字段被拆断¶
4 个失败文件全部是同一类错误:把一个 f-string 的 {...} 替换字段拆到了两个隐式拼接的字符串字面量之间。例如 06-indicators-demo.py:363-364:
# ❌ 错误写法:{ 在第一个字面量里打开,} 却在第二个字面量里关闭
self.Debug(f" BB Position: {(price - self.bb_20_2.LowerBand.Current.Value) / "
f"(self.bb_20_2.UpperBand.Current.Value - self.bb_20_2.LowerBand.Current.Value) * 100:.1f}%")
为什么是 Bug(与 Python 版本无关):
- Python ≤ 3.11(即 Lean 运行时所用的版本):解析阶段即抛
SyntaxError: f-string: expecting '}',文件根本无法被加载。 - Python 3.12+(PEP 701 重写了 f-string tokenizer):虽能编译,但运行时抛
TypeError: 'str' object is not callable(已实测复现),语义仍错误。
结论:无论哪个 Python 版本,这都是确定的运行期/加载期 Bug。由于 Lean 使用 Python 3.11,原代码在 Lean 中加载就会失败。
✅ 状态:上述全部错误已于 2026-06-28 修复(共 5 处编辑,
06-indicators-demo.py含 2 处),4 个文件现均通过py_compile,详见 3.3。
3.3 错误定位与修复(✅ 已于 2026-06-28 应用)¶
共 5 处编辑、涉及 4 个文件。注意
06-indicators-demo.py有 2 处(363-364 与 470-471,后者此前被首个语法错误遮挡,修复前者后才暴露)。修复方式统一为「先求值到局部变量,再放入 f-string」。
① 06-indicators-demo.py:363-364(EnterLong 内的 BB 位置)
# 已应用:先算出值再格式化(可读性最好)
bb_pos = ((price - self.bb_20_2.LowerBand.Current.Value) /
(self.bb_20_2.UpperBand.Current.Value - self.bb_20_2.LowerBand.Current.Value)) * 100
self.Debug(f" BB Position: {bb_pos:.1f}%")
② 06-indicators-demo.py:470-471(OnEndOfAlgorithm 内的总收益)
# 已应用
total_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Total Return: {total_return:.2f}%")
③ 07-data-demo.py:448-449
# 已应用
total_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Total Return: {total_return:.2f}%")
④ 09-advanced-features-demo.py:620-621
# 已应用
final_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Final Return: {final_return:.2f}%")
⑤ 12-optimization-demo.py:467-468
# 已应用
total_return = self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1
self.Debug(f"Total Return: {total_return:.2%}")
通用修复原则:f-string 的
{...}替换字段必须在同一个字符串字面量内闭合;若表达式过长,先赋值给局部变量再放进 f-string,或用括号在单行内换行。
四、静态分析详情(pyflakes)¶
已过滤
from AlgorithmImports import *带来的 F403/F405(star import)噪音——这是 Lean 算法的标准写法,非问题。
4.1 低优先级风格提示(不影响运行)¶
(a) F541 — f-string 无占位符(f"..." 里没有 {},f 前缀多余)
出现文件:03-sma-cross.py、04-qcalgorithm-demo.py、05-order-management-demo.py、10-research-demo.py、15-data-demo.py。
示例:self.Debug(f"Fast MA: 50 days") → 去掉 f 即可。纯风格问题,运行无碍。
(b) F401 — 导入未使用
- 04-qcalgorithm-demo.py:13、08-framework-demo.py:13:from datetime import timedelta, datetime 未使用。
- 10-research-demo.py:22:timedelta 未使用。
(c) F841 — 局部变量赋值后未使用
- 04-qcalgorithm-demo.py:spy_volume、spy_bid、spy_ask、is_invested、spy_quantity、spy_total_cost、total_margin_used、atr_value、price 等。
- 05-order-management-demo.py:ticket、order。
- 15-data-demo.py:513:risk_on。
说明:教学示例中这类「取了值但没用」的写法多为刻意演示 API 访问方式(展示「如何拿到成交量/买卖价」),属正常教学代码;若要消除告警,可在
Debug中输出这些变量,或加# noqa。
4.2 结构摘要(AST)¶
| 文件 | 导入 | 定义的类(基类) |
|---|---|---|
| 01-hello-world | AlgorithmImports.* |
HelloWorldAlgorithm(QCAlgorithm) |
| 03-sma-cross | AlgorithmImports.* |
SimpleMovingAverageCrossAlgorithm、SMAWithStopLossAlgorithm(均 QCAlgorithm) |
| 04-qcalgorithm-demo | AlgorithmImports.* |
QCAlgorithmBasicsAlgorithm、SimpleQCAlgorithmExample(QCAlgorithm) |
| 05-order-management-demo | AlgorithmImports.* |
OrderManagementDemoAlgorithm(QCAlgorithm)、OrderManager |
| 06-indicators-demo | AlgorithmImports.* |
TechnicalIndicatorsDemoAlgorithm、SimpleMultiIndicatorStrategy(QCAlgorithm)+ 2 个 PythonIndicator |
| 07-data-demo | AlgorithmImports.* |
DataAndHistoryDemoAlgorithm、SimpleHistoryExample(QCAlgorithm)+ SentimentData(PythonData) |
| 08-framework-demo | AlgorithmImports.* |
12 个类:覆盖 AlphaModel/PortfolioConstructionModel/ExecutionModel/RiskManagementModel/QCAlgorithm |
| 09-advanced-features-demo | AlgorithmImports.* |
期权/期货策略 5 个 + AdvancedFeaturesDemo(QCAlgorithm)+ FeeModel/SlippageModel |
| 10-research-demo | QuantConnect.*、pandas、numpy、matplotlib |
notebook 风格脚本,无类定义 |
| 12-optimization-demo | AlgorithmImports.*、numpy |
OptimizableMovingAverageStrategy、RobustOptimizationStrategy、WalkForwardOptimizationStrategy(QCAlgorithm) |
| 15-data-demo | AlgorithmImports.* |
PythonData×2 + 3 个 QCAlgorithm |
所有 10 个算法文件均正确 from AlgorithmImports import *;10-research-demo.py 正确使用 QuantConnect + 数据科学库。导入写法全部正确。
五、运行时导入探测¶
5.1 数据科学依赖:✅ 全部可用¶
import pandas, numpy, scipy, matplotlib # 均成功
# pandas 3.0.3 | numpy 2.4.6 | scipy 1.17.1 | matplotlib 3.11.0
因此
10-research-demo.py中纯 pandas/numpy 的部分(指标计算、收益统计、参数网格搜索)在该环境可独立运行;但其QuantBook()、qb.History()等 Lean 调用仍需研究环境。
5.2 Lean 符号:⚠️ AlgorithmImports 是「空壳」¶
在安装了 quantconnect-stubs 的 lean 环境中:
from AlgorithmImports import * # 不报错
'QCAlgorithm' in dir() # False —— 没绑定任何名字!
import AlgorithmImports as ai
dir(ai) # [] 空
ai.__file__ # None(namespace package)
原因:quantconnect-stubs 在 site-packages 下放置了一个空的 AlgorithmImports 命名空间包目录(仅含 .pyi 类型存根,供 IDE 补全/类型检查),不含真实运行时符号。
后果:若直接 python 01-hello-world.py 执行,class HelloWorldAlgorithm(QCAlgorithm) 会抛 NameError: name 'QCAlgorithm' is not defined。这些文件不能脱离 Lean 引擎单独运行——这是设计使然,不是 Bug。
换言之:本 conda 环境适合做语法 + 静态 + 类型层面的验证(已覆盖),但不能直接运行策略。直接运行需要下一节的完整 Lean 运行时。
六、如何完成「完整运行验证」(回测)¶
当前静态验证已覆盖「代码本身是否正确」。若要进一步验证策略真能回测出结果,需 Lean 运行时,二选一:
方式 A:Lean CLI + Docker(官方推荐,最省事)¶
# 1. 安装 Lean CLI
pip install lean
# 2. 初始化(会拉取 quantconnect/lean 镜像,需要 Docker)
lean init
# 3. 把示例复制进一个项目目录,配置 main.py / config.json 指定 algorithm-type-name
# 4. 本地回测(示例)
lean backtest --project MyStrategy
- 依赖:本机已有 Docker 27.4.0 ✅、dotnet 10.0.201 ✅;缺
leanCLI(pip install lean即可)。 - 数据:默认用 QuantConnect 云端数据;本地数据需
lean data download。
方式 B:本地编译 Lean Engine(Pythonnet)¶
dotnet build QuantConnect.Lean.sln
# 配置 PYTHONNET_PYDLL 指向 libpython3.11,运行 Launcher
- 适合深度二次开发;配置较繁琐。
✅ 第三节列出的 5 处
SyntaxError已全部修复,11/11 文件通过编译,可直接进入回测。回测仍需 Lean 运行时本身(Docker / 编译引擎)。
七、建议与后续行动¶
| 优先级 | 行动 | 涉及文件 |
|---|---|---|
| ✅ 已完成 | 修复多行 f-string SyntaxError(共 5 处编辑,06 含 2 处) |
06、07、09、12 |
| 🟡 中 | 清理无占位符 f-string、未用导入(可选) | 03、04、05、08、10、15 |
| 🟢 低 | 修复后用 lean backtest 跑一次 Hello World / SMA 交叉,确认端到端可运行 |
全部 |
附录:本次验证未覆盖的内容¶
- 真实行情回测结果(收益、夏普、回撤等)——需 Lean 引擎 + 数据。
- Lean API 用法的语义正确性(如某指标参数是否合理、订单逻辑是否符合预期)——需在运行时结合实际数据人工复核。
- C# 示例代码(
tutorial-outline.md等文档中内嵌的 C# 代码片段)——本次仅验证docs/下的.py文件。
本报告由 lean conda 环境(Python 3.11.13)下的 py_compile / pyflakes / ast 自动生成并人工核对。