QUANTAXIS Python 代码规范完全指南:PEP 8、类型注解、命名规范与质量工具实战

原创2026-09-22 15:29:321,404 阅读
文章标签:金融科技后端数据分析

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

相关资源

总结

QUANTAXIS 代码规范的核心可以浓缩为五句话:

  • ✅ 遵循 PEP 8:统一的行宽、缩进、空格与导入顺序;
  • ✅ 类型注解:让数据流与接口契约在策略、数据、账户模块间清晰可见;
  • ✅ 清晰命名:QA_ 前缀体系 + snake_case 变量 + PascalCase 类名,见名知义;
  • ✅ 文档完善:Google 风格 docstring,公共 API 强制书写;
  • ✅ 工具检查:pylint / black / mypy 三件套 + CI 预提交钩子,让规范自动执行。

对任何向 QUANTAXIS 提交代码或在其上做二次开发的工程师而言,把本文的规范内化为习惯,是让代码在数据抓取、指标计算、策略回测与实盘交易全链路中保持高质量、可测试、可维护的起点。

登录后查看全文
QUANTAXIS