QUANTAXIS Python 代码规范完全指南:PEP 8、类型注解、命名规范与质量工具实战
QUANTAXIS Python 代码规范完全指南:PEP 8、类型注解、命名规范与质量工具实战
本文依据仓库文档 doc/development/code-standards.md 展开,是 QUANTAXIS 面向开发者的一线编码规范手册。QUANTAXIS 是一个支持任务调度与分布式部署的股票/期货/期权纯本地量化解决方案,代码横跨数据抓取、指标计算、回测、模拟交易、账户与风控等多个模块,规范的统一直接决定代码的可读性、可测试性与可维护性。读完本文,你将掌握 QUANTAXIS 的 Python 编码约定、命名体系、异常处理与代码组织方式,并学会用 pylint、black、mypy 等工具把代码质量检查接入日常开发与 CI 流程。
文档背景与适用范围
本文档(版本 2.1.0-alpha2,作者 @yutiansut @quantaxis,更新于 2025-10-25)规定 QUANTAXIS 项目的代码规范,目标是保证多开发者、多模块协作下的代码质量与一致性。其适用范围包括:
- QAFetch:股票/期货/期权等行情数据抓取模块;
- QAData / QAIndicator:数据结构封装与指标计算模块;
- QAStrategy / QAMarket / QIFI:策略开发、订单账户与协议模块;
- QAUtil / QAEngine / QASchedule:工具库、线程调度与任务调度模块。
与同目录下的 测试指南、最佳实践 以及 性能优化指南 互为补充:规范管"怎么写",测试管"怎么验证",性能指南管"怎么快"。
核心原则
规范的出发点不是束缚,而是五条被反复强调的工程原则:
| 原则 | 含义 | 在 QUANTAXIS 中的落点 |
|---|---|---|
| 可读性优先 | 代码是写给人看的,其次才是机器 | 命名自解释、避免晦涩缩写 |
| 一致性 | 遵循统一编码风格 | 全仓库统一的 QA_ 前缀与 snake_case |
| 简洁性 | 简单优于复杂,明确优于隐晦 | 优先向量化、列表推导而非复杂循环 |
| 文档化 | 代码即文档,命名与注释并重 | 公共 API 必须携带 docstring |
| 可测试性 | 代码应该易于测试 | 单一职责 + 依赖注入,配合 测试指南 |
Python 代码规范
PEP 8 基础规范
QUANTAXIS 全面遵循 PEP 8(Python 官方风格指南)。文档给出如下可直接对照的示例:
# ✅ 正确的导入顺序(标准库 → 第三方 → 项目内部)
import os
import sys
from typing import List, Dict, Optional
import pandas as pd
import numpy as np
import QUANTAXIS as QA
from QUANTAXIS.QAUtil import QA_util_log_info
from QUANTAXIS.QAData import QA_DataStruct_Stock_day
# ❌ 错误的导入:避免使用 * 通配符导入
from QUANTAXIS import * # 不推荐
命名规则速查:
class QADataStruct: # 类名:CapWords(大驼峰)
pass
def fetch_stock_data(): # 函数名:lowercase_with_underscores
pass
MARKET_STOCK = 'stock' # 常量:UPPER_CASE_WITH_UNDERSCORES
user_id = '123' # 变量:lowercase_with_underscores
空格使用:
result = calculate_value(a, b) # ✅ 函数调用括号后不加空格
x = 1 + 2 # ✅ 运算符两侧留空格
my_list = [1, 2, 3] # ✅ 逗号后留空格
result=calculate_value( a,b ) # ❌
x=1+2 # ❌
仓库的 .pylintrc 将 max-line-length 设为 100、indent-string 设为 4 空格,与 PEP 8 的"每行不超过 79 字符"相比更宽松,是 QUANTAXIS 针对量化代码(长参数、长表达式较多)的工程化取舍。
类型注解
类型注解让数据结构在数据层与策略层之间传递时意图清晰。文档推荐对函数签名与类属性全面标注:
from typing import List, Dict, Optional, Union
import pandas as pd
def fetch_stock_day(
code: str,
start: str,
end: str,
format: str = 'pd'
) -> pd.DataFrame:
"""获取股票日线数据
Args:
code: 股票代码
start: 开始日期
end: 结束日期
format: 返回格式,默认pandas
Returns:
股票日线数据DataFrame
"""
pass
class QAAccount:
def __init__(
self,
account_cookie: str,
init_cash: float = 1000000.0
) -> None:
self.account_cookie: str = account_cookie
self.init_cash: float = init_cash
self.balance: float = init_cash
self.positions: Dict[str, 'QAPosition'] = {}
def get_position(self, code: str) -> Optional['QAPosition']:
"""获取持仓"""
return self.positions.get(code)
这种风格在真实源码中大量可见。例如 qactabase.py 中 QAStrategyCtaBase.__init__ 声明了 code='rb2005'、frequence='1min'、init_cash=1000000、model='py' 等带默认值的参数,并在 docstring 中逐一解释,正是"类型注解 + 文档化"的落地样板。
文档字符串(docstring)
文档要求使用 Google 风格 docstring,并建议在函数与类级别都包含 Args、Returns、Raises、Examples 等小节:
def calculate_sharpe_ratio(
returns: pd.Series,
risk_free_rate: float = 0.03
) -> float:
"""计算夏普比率
夏普比率衡量每单位风险的超额收益。
Args:
returns: 收益率序列
risk_free_rate: 无风险利率,默认3%
Returns:
夏普比率
Raises:
ValueError: 如果收益率序列为空
Examples:
>>> returns = pd.Series([0.01, 0.02, -0.01, 0.03])
>>> sharpe = calculate_sharpe_ratio(returns)
>>> print(f"夏普比率: {sharpe:.2f}")
"""
if len(returns) == 0:
raise ValueError("收益率序列不能为空")
excess_returns = returns - risk_free_rate / 252
return excess_returns.mean() / excess_returns.std() * np.sqrt(252)
类级别示例(对应真实存在的 QAStrategyCtaBase):
class QAStrategyCtaBase:
"""CTA策略基类
提供CTA策略开发的基础框架,包括事件驱动、持仓管理等功能。
Attributes:
code: 交易标的代码
frequence: 数据频率('1min', '5min', '1day'等)
start: 回测开始日期
end: 回测结束日期
init_cash: 初始资金
Examples:
>>> class MyStrategy(QAStrategyCtaBase):
... def user_init(self):
... self.ma_period = 20
...
... def on_bar(self, bar):
... # 策略逻辑
... pass
"""
pass
仓库的 .pylintrc 在 [MESSAGES CONTROL] 中禁用了 missing-docstring、empty-docstring 与 fixme 三项提示,同时 no-docstring-rgx=^_ 表示以下划线开头的私有函数/类可豁免 docstring——即规范强制要求公共 API 文档化,私有实现可适度放宽。
错误处理
文档强调:捕获具体异常、记录日志、必要时重试或上抛,杜绝裸 except。
import time
import logging
logger = logging.getLogger(__name__)
def fetch_data_with_retry(code: str, max_retries: int = 3) -> pd.DataFrame:
"""带重试的数据获取"""
for attempt in range(max_retries):
try:
data = QA.QA_fetch_stock_day(code, '2024-01-01', '2024-12-31')
if data is None or len(data) == 0:
raise ValueError(f"未获取到数据: {code}")
return data
except ConnectionError as e:
if attempt == max_retries - 1:
raise
logger.warning(f"连接失败,重试 {attempt + 1}/{max_retries}: {e}")
time.sleep(2 ** attempt) # 指数退避
except ValueError:
logger.error(f"数据验证失败: {code}")
raise
except Exception as e:
logger.error(f"未知错误: {e}")
raise
raise RuntimeError(f"获取数据失败,已重试{max_retries}次")
# ❌ 避免裸 except
try:
data = fetch_data()
except: # 吞掉一切异常,无法调试
pass
# ✅ 捕获具体异常
try:
data = fetch_data()
except (ValueError, KeyError) as e:
logger.error(f"数据错误: {e}")
raise
QUANTAXIS 提供了一套日志工具(见 QALogs.py,包括 QA_util_log_info、QA_util_log_debug、QA_util_log_expection),默认写本地日志文件,因此规范中反复强调用 logger.warning/error 替代裸 print,与项目日志体系对齐。
代码组织
类内成员建议按"类变量 → 构造方法 → 公共方法 → 私有方法(按调用顺序)→ 魔术方法"组织:
class QAStrategy:
"""策略类"""
# 1. 类变量
DEFAULT_INIT_CASH = 1000000
# 2. 初始化方法
def __init__(self, code: str, init_cash: float = None):
"""初始化策略"""
self.code = code
self.init_cash = init_cash or self.DEFAULT_INIT_CASH
self._setup()
# 3. 公共方法
def run_backtest(self) -> None:
"""运行回测"""
self._prepare_data()
self._execute_strategy()
self._calculate_metrics()
def get_performance(self) -> Dict:
"""获取性能指标"""
return self._performance_metrics
# 4. 私有方法(按调用顺序)
def _setup(self) -> None:
"""设置策略"""
pass
def _prepare_data(self) -> None:
"""准备数据"""
pass
def _execute_strategy(self) -> None:
"""执行策略"""
pass
def _calculate_metrics(self) -> None:
"""计算指标"""
pass
# 5. 魔术方法
def __repr__(self) -> str:
return f"QAStrategy(code={self.code}, cash={self.init_cash})"
对照 qactabase.py:QAStrategyCtaBase 的 __init__ 内部依次初始化用户名/密码、行情与交易主机、起始日期、市场类型、订单方向缓存、K 线订单统计等属性,最后调用 self.user_init() 交给子类扩展——公共/私有边界清晰,正是上述组织方式的工程化体现。
命名规范
模块和包名
文档给出的目录命名范式与仓库实际结构一致:
QUANTAXIS/
├── QAFetch/ # 包名:短小,全小写
│ ├── __init__.py
│ ├── QAQuery.py # 模块名:QA前缀 + 功能
│ └── QATdx.py
├── QAData/
└── QAStrategy/
仓库根目录下 QAFetch、QAData、QADataBridge、QAEngine、QAFactor、QAIndicator、QAMarket、QAPubSub、QARSBridge、QASchedule、QASetting、QAStrategy、QAUtil、QAWebServer、QIFI 等一级包均遵循该约定,模块文件统一为 QA 前缀 + 功能描述(如 QAStrategy/qactabase.py、QAFetch/QAQuery.py)。
类和函数名
# ✅ 类名:大驼峰
class QADataStructStockDay:
pass
class QAStrategyCtaBase:
pass
# ✅ 函数名:小写+下划线
def fetch_stock_day():
pass
def calculate_sharpe_ratio():
pass
# ✅ 私有方法:单下划线前缀
def _internal_helper():
pass
# ✅ 魔术方法:双下划线
def __init__(self):
pass
# ❌ 避免
class qaStrategy: # 首字母应大写
pass
def FetchData(): # 函数名不应大写
pass
def __private_method(): # 非魔术方法避免双下划线前缀
pass
从源码结构看,QUANTAXIS 历史代码中函数名多采用 QA_indicator_MA、QA_indicator_MACD 这类 QA_ 前缀 + 下划线风格(见 indicators.py),新代码则建议直接使用简洁的 snake_case。仓库 .pylintrc 的 [BASIC] 段将 function-naming-style 设为 snake_case、class-naming-style 设为 PascalCase、method-naming-style 设为 snake_case,把命名要求固化为机器可检查的规则。
变量名
# ✅ 正确的变量命名
stock_code = '000001'
user_id = 'user123'
init_cash = 1000000
max_position_size = 5
# ✅ 常量:全大写
MAX_RETRY_TIMES = 3
DEFAULT_FREQUENCE = '1day'
MARKET_TYPE_STOCK = 'stock_cn'
# ✅ 私有变量:单下划线前缀
self._internal_state = None
self._cache = {}
# ❌ 避免
sc = '000001' # 太短,不清晰
stockCode = '000001' # Python不使用驼峰
temp = 123 # 避免temp/tmp等无意义名称
仓库 .pylintrc 用正则约束了变量命名:variable-rgx=[a-z][a-z0-9_]*、argument-rgx=[a-z][a-z0-9_]*、const-rgx=(([A-Z_][A-Za-z0-9_]*)|(__.*__))$,并列出 foo/bar/baz/toto/tutu/tata 为禁用 bad-names,i/j/k/ex/_ 为允许的 good-names。
最佳实践
函数设计
单一职责:一个函数只做一件事,文档以"获取数据"与"计算均线"拆分为例,反对把取数、算指标、落库、发通知揉进一个 fetch_and_calculate。
控制参数数量:文档推荐三种手法——关键字参数、默认值、* 强制关键字:
def create_strategy(
code: str,
start: str,
end: str,
*, # 强制后续参数使用关键字
init_cash: float = 1000000,
frequence: str = '1day',
commission: float = 0.0003
) -> 'QAStrategy':
"""使用默认值和关键字参数"""
pass
配置对象:参数过多时改用 dataclass 聚合:
from dataclasses import dataclass
@dataclass
class StrategyConfig:
code: str
start: str
end: str
init_cash: float = 1000000
frequence: str = '1day'
commission: float = 0.0003
def create_strategy(config: StrategyConfig) -> 'QAStrategy':
"""使用配置对象"""
pass
这与 最佳实践 中"使用 dataclass 做配置管理、禁止魔法数字硬编码"的建议一脉相承。
列表推导式与生成器
# ✅ 列表推导式(数据量小)
codes = ['000001', '000002', '600000']
stock_names = [get_stock_name(code) for code in codes]
# ✅ 生成器(数据量大,避免内存占用)
def fetch_all_stocks():
"""使用生成器避免内存占用"""
codes = QA.QA_fetch_stock_list()['code']
for code in codes:
yield QA.QA_fetch_stock_day(code, '2024-01-01', '2024-12-31')
# ✅ 条件推导
positive_returns = [r for r in returns if r > 0]
嵌套三层以上的复杂推导式应改写为普通循环,可读性优先:
# ❌ 过于复杂的推导
result = [
process(x, y, z)
for x in data1
for y in data2
if condition1(x)
for z in data3
if condition2(y, z)
]
# ✅ 普通循环更清晰
result = []
for x in data1:
if not condition1(x):
continue
for y in data2:
for z in data3:
if condition2(y, z):
result.append(process(x, y, z))
上下文管理器
# ✅ 使用with语句
with open('data.csv', 'r') as f:
data = f.read()
# ✅ 数据库连接
from pymongo import MongoClient
def fetch_from_mongodb(collection: str, query: dict):
with MongoClient('mongodb://localhost:27017') as client:
db = client.quantaxis
return list(db[collection].find(query))
# ✅ 自定义上下文管理器
from contextlib import contextmanager
@contextmanager
def timer(name: str):
"""计时上下文管理器"""
start = time.time()
try:
yield
finally:
elapsed = time.time() - start
logger.info(f"{name} 耗时: {elapsed:.2f}s")
# 使用
with timer("数据获取"):
data = fetch_stock_data('000001')
装饰器
装饰器用于横切关注点(缓存、重试、日志、鉴权):
import functools
import time
from typing import Callable
# ✅ 缓存装饰器
def cache(func: Callable) -> Callable:
"""简单缓存装饰器"""
_cache = {}
@functools.wraps(func)
def wrapper(*args, **kwargs):
key = str(args) + str(kwargs)
if key not in _cache:
_cache[key] = func(*args, **kwargs)
return _cache[key]
return wrapper
@cache
def fetch_stock_list():
"""获取股票列表(会被缓存)"""
return QA.QA_fetch_stock_list()
# ✅ 重试装饰器(指数退避)
def retry(max_attempts: int = 3, delay: float = 1.0):
"""重试装饰器"""
def decorator(func: Callable) -> Callable:
@functools.wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(max_attempts):
try:
return func(*args, **kwargs)
except Exception as e:
if attempt == max_attempts - 1:
raise
time.sleep(delay * (2 ** attempt))
return None
return wrapper
return decorator
@retry(max_attempts=3, delay=2.0)
def fetch_data_from_api(code: str):
"""从API获取数据(带重试)"""
pass
注意:
functools.wraps必不可少,否则装饰后的函数会丢失__name__、__doc__等元信息,破坏 docstring 与内省能力,也与本文档"代码即文档"的原则冲突。
代码质量检查
文档推荐三件套工具,且仓库 .pylintrc 已提供可直接使用的检查配置。
使用 pylint
# 安装pylint
pip install pylint
# 检查单个文件
pylint QUANTAXIS/QAStrategy/qactabase.py
# 检查整个包
pylint QUANTAXIS/
# 使用仓库提供的配置文件
pylint --rcfile=.pylintrc QUANTAXIS/
仓库 .pylintrc 的关键配置值得了解:
| 配置段 | 关键项 | 含义 |
|---|---|---|
[MASTER] |
jobs=1 |
单进程检查,避免并发输出混乱 |
[MESSAGES CONTROL] |
disable=empty-docstring, fixme, missing-docstring, unused-argument, no-self-use, bare-except |
放宽部分提示,例如项目允许裸 except 兜底 |
[BASIC] |
variable-rgx/argument-rgx、class-naming-style=PascalCase、function-naming-style=snake_case |
把命名规范固化为规则 |
[FORMAT] |
max-line-length=100、indent-string=' ' |
行宽 100、4 空格缩进 |
[DESIGN] |
max-args=10、max-attributes=20、max-locals=15、max-nested-blocks=5 |
复杂度红线 |
[SIMILARITIES] |
min-similarity-lines=4 |
相似代码(重复)检测阈值 |
使用 black 格式化
# 安装black
pip install black
# 格式化代码
black QUANTAXIS/
# 检查但不修改(CI 中常用)
black --check QUANTAXIS/
black 是"不可争辩的格式化器",与 pylint 的职责互补:black 保证格式统一,pylint 负责风格与潜在 bug 检查。建议按"先 black 格式化 → 再 pylint 检查"的顺序执行。
使用 mypy 类型检查
# 安装mypy
pip install mypy
# 类型检查
mypy QUANTAXIS/
文档给出的 mypy.ini 模板:
[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_configs = True
其中 warn_return_any 强制函数返回类型不能隐式退化为 Any,与本文档"类型注解"一节的要求配套。需要说明:mypy 是严格模式下的静态类型检查,对以动态数据(DataFrame、行情 dict)为主的 QUANTAXIS 业务代码,建议先在核心模块试点,再逐步推广,避免一次性引入大量类型错误干扰迭代。
在 CI 与预提交中落地
规范的最终价值在于"可执行"。可在本地安装 pre-commit 钩子(配置示例见 测试指南 的 .pre-commit-config.yaml:black + pylint + 空白符检查),并在 CI 流水线中执行 black --check、pylint --rcfile=.pylintrc、mypy 三条命令,把代码规范变成合并请求的硬门槛。
性能优化规范
性能优化与代码规范并不冲突——规范约束结构,性能关注效率。文档给出三条最直接的优化守则:
使用局部变量,避免重复属性访问
# ✅ 缓存属性访问
def calculate_total(data: pd.DataFrame) -> float:
values = data['close'].values
total = 0
for value in values:
total += value
return total
# ❌ 每次都访问
def calculate_total_slow(data: pd.DataFrame) -> float:
total = 0
for i in range(len(data)):
total += data['close'].iloc[i]
return total
使用向量化替代循环
import numpy as np
# ✅ 向量化计算收益率
def calculate_returns_fast(prices: np.ndarray) -> np.ndarray:
"""向量化计算收益率"""
return np.diff(prices) / prices[:-1]
# ❌ 循环计算(慢)
def calculate_returns_slow(prices: list) -> list:
"""循环计算(慢)"""
returns = []
for i in range(1, len(prices)):
returns.append((prices[i] - prices[i-1]) / prices[i-1])
return returns
这正是 QUANTAXIS 指标库的默认做法:例如 QAIndicator/base.py 中的 MACD(Series, FAST, SLOW, MID) 与 indicators.py 中的 QA_indicator_MACD(DataFrame, short=12, long=26, mid=9) 均基于 pandas/numpy 的向量化运算实现。更进一步的性能手段(Rust 组件、零拷贝数据桥、共享内存)见 性能优化指南 与 最佳实践。
规范要点速查表
| 主题 | 规范 | 可验证依据 |
|---|---|---|
| 导入 | 标准库 → 第三方 → 项目内部,禁 * 导入 |
.pylintrc [IMPORTS] |
| 类名 | PascalCase(大驼峰) | .pylintrc class-naming-style |
| 函数/方法名 | snake_case | .pylintrc function/method-naming-style |
| 常量 | UPPER_CASE | .pylintrc const-rgx |
| 类型注解 | 函数签名与类属性全面标注 | qactabase.py |
| docstring | Google 风格,公共 API 必写 | .pylintrc no-docstring-rgx=^_ |
| 异常 | 捕获具体异常、日志记录、指数退避重试 | QALogs.py |
| 函数职责 | 单一职责、控制参数数量、可配置对象 | 最佳实践 |
| 行宽/缩进 | 100 字符 / 4 空格 | .pylintrc [FORMAT] |
| 复杂度红线 | max-args=10、max-nested-blocks=5 等 | .pylintrc [DESIGN] |
| 质量工具 | pylint / black / mypy 三件套 | .pylintrc |
相关资源
- 测试指南: doc/development/testing.md —— 与规范配套的单元/集成/策略测试体系
- 最佳实践: doc/development/best-practices.md —— 性能优化、架构设计与安全建议
- 性能优化指南: doc/advanced/performance-tuning.md —— 向量化、Rust 加速与零拷贝
- 贡献指南: doc/development/contributing.md —— 提 PR 前的流程与检查项
- PEP 8: Python 官方风格指南(
peps.python.org/pep-0008)
总结
QUANTAXIS 代码规范的核心可以浓缩为五句话:
- ✅ 遵循 PEP 8:统一的行宽、缩进、空格与导入顺序;
- ✅ 类型注解:让数据流与接口契约在策略、数据、账户模块间清晰可见;
- ✅ 清晰命名:
QA_前缀体系 + snake_case 变量 + PascalCase 类名,见名知义; - ✅ 文档完善:Google 风格 docstring,公共 API 强制书写;
- ✅ 工具检查:pylint / black / mypy 三件套 + CI 预提交钩子,让规范自动执行。
对任何向 QUANTAXIS 提交代码或在其上做二次开发的工程师而言,把本文的规范内化为习惯,是让代码在数据抓取、指标计算、策略回测与实盘交易全链路中保持高质量、可测试、可维护的起点。