pytrade-mock-ohlcv 0.2.0

一个轻量、可复用、以 dataclass 明确输入输出契约的合成 OHLCV 行情数据生成器。

它适合用于：

• demo / example 数据；
• smoke test；
• 文档示例；
• 筹码分布、技术指标、行情处理管线的快速验证。

它不试图伪装成完整的真实市场仿真器。当前版本的核心目标是：生成结构自洽、字段清晰、可复现的合成行情数据。

---

安装

本地开发：

pip install -e .

包含测试工具：

pip install -e ".[dev]"

---

快速开始

from mock_ohlcv import OHLCVRequest, generate_ohlcv


dataset = generate_ohlcv(
    OHLCVRequest(
        symbol="MOCK001",
        days=250,
        seed=42,
        start_price=100.0,
        turnover=3.0,
    )
)

frame = dataset.frame

print(frame.head())
print(dataset.schema)

输出对象是 OHLCVDataset，包含三部分：

dataset.frame    # Polars DataFrame
dataset.request  # 本次生成使用的输入参数
dataset.columns  # 输出列名定义

---

Public API

0.2.0 版本只建议使用这四个公开入口：

from mock_ohlcv import (
    generate_ohlcv,
    OHLCVRequest,
    OHLCVColumns,
    OHLCVDataset,
)

名称	作用
generate_ohlcv()	生成合成行情数据
OHLCVRequest	输入 schema：描述要生成什么
OHLCVColumns	列 schema：描述输出 DataFrame 的列名
OHLCVDataset	输出 schema：数据 + 输入参数 + 列定义

---

输入 schema：OHLCVRequest

from mock_ohlcv import OHLCVRequest


request = OHLCVRequest(
    symbol="MOCK001",
    name="Synthetic Stock",
    market="A_SHARE",
    start="2023-01-01",
    days=200,
    seed=42,
    start_price=100.0,
    drift=0.0,
    volatility=0.02,
    turnover=3.0,
    total_shares=1_000_000_000.0,
    float_shares=800_000_000.0,
    price_limit=0.10,
    date_format="str",
)

字段说明：

字段	类型	默认值	说明
symbol	str	"MOCK001"	合成股票代码
name	str	"Synthetic Stock"	合成股票名称
market	"A_SHARE" | "GENERIC"	"A_SHARE"	市场类型标签
start	str	"2023-01-01"	起始日期
days	int	200	交易日数量
seed	int	42	随机种子
start_price	float	100.0	初始价格
drift	float	0.0	日收益漂移
volatility	float	0.02	日波动率
turnover	float	3.0	平均换手率，单位：%
total_shares	float	1_000_000_000.0	总股本
float_shares	float	800_000_000.0	流通股本
price_limit	float | None	0.10	日涨跌幅限制，None 表示关闭
date_format	"str" | "date"	"str"	日期输出格式

---

输出 schema：OHLCVDataset

dataset = generate_ohlcv()

dataset 包含：

dataset.frame

Polars DataFrame。

dataset.request

本次生成使用的 OHLCVRequest。

dataset.columns

本次生成使用的 OHLCVColumns。

dataset.schema

预期 Polars schema。

dataset.symbol

快捷获取 request.symbol。

---

列 schema：OHLCVColumns

默认输出列：

from mock_ohlcv import OHLCVColumns


columns = OHLCVColumns()

print(columns.names())

结果：

[
    "date",
    "open",
    "high",
    "low",
    "close",
    "volume",
    "turnover_rate",
    "total_shares",
    "float_shares",
]

可以自定义列名：

from mock_ohlcv import OHLCVColumns, generate_ohlcv


columns = OHLCVColumns(
    date="trade_date",
    turnover_rate="turnover",
)

dataset = generate_ohlcv(columns=columns)

---

数据质量保证

当前生成器保证：

open > 0
high > 0
low > 0
close > 0
volume >= 0
high >= max(open, close)
low <= min(open, close)
float_shares <= total_shares

如果 price_limit 不为 None，还保证：

low >= previous_close * (1 - price_limit)
high <= previous_close * (1 + price_limit)

成交量由换手率和流通股本派生：

base_volume = float_shares * turnover_rate / 100

随后加入少量噪声，因此它是“结构相关”，不是完全相等。

---

当前不是完整市场仿真器

0.2.0 暂不覆盖：

• 真实交易日历；
• 停牌；
• 复权因子；
• 分红送转；
• 板块差异化涨跌幅限制；
• 盘口、逐笔、分钟线；
• 牛熊震荡 regime；
• 多标的相关性；
• 基于真实分布校准的参数估计。

这些能力应该按 AGENTS.md 的 API 扩展规则逐步演进。

---

示例

运行：

python examples/demo.py

---

测试

pytest

---

版本

当前版本：0.2.0

这个版本的定位是：

合成 OHLCV 数据生成能力已经成为核心功能；后续扩展应优先保持 public API 简洁、输入输出 schema 清晰、数据质量约束稳定。