ctplite 0.1.4

Python SDK for pq-futures CTP trading system

ctplite

Python SDK for CTPLite. 提供 gRPC 和 REST 两种客户端接口，方便开发人员在其他 Python 项目中使用。

安装

pip install ctplite

pip install -U ctplite -i https://pypi.org/simple

包结构设计

sdk/
├── ctplite/
│   ├── __init__.py              # 包初始化，导出主要类
│   ├── config.py                # 配置管理（从 examples/python/config.py 重构）
│   ├── grpc_client.py           # gRPC 客户端（从 examples/python/grpc_client.py 重构）
│   ├── rest_client.py           # REST 客户端（从 examples/python/rest_client.py 重构）
│   └── proto/                   # protobuf 生成的代码
│       ├── __init__.py
│       ├── common_pb2.py
│       ├── common_pb2_grpc.py
│       ├── auth_pb2.py
│       ├── auth_pb2_grpc.py
│       ├── market_data_pb2.py
│       ├── market_data_pb2_grpc.py
│       ├── trading_pb2.py
│       └── trading_pb2_grpc.py
├── setup.py                      # 包安装配置（使用 setuptools）
├── pyproject.toml                # 现代 Python 包配置
├── MANIFEST.in                   # 包含额外文件
├── README.md                     # 包说明文档
├── LICENSE                       # 许可证文件
└── requirements.txt              # 依赖列表（用于开发）

快速开始

配置环境变量

推荐使用 .env 文件来管理配置，避免在代码中硬编码敏感信息。

使用 .env 文件配置

1. 安装 python-dotenv（如果尚未安装）：

pip install python-dotenv

2. 创建 .env 文件：

.env 文件应该放在运行 Python 脚本的目录（当前工作目录）。load_dotenv() 会自动从当前工作目录向上查找 .env 文件。

推荐位置：项目根目录

my_project/
├── .env              # 放在这里（推荐）
├── main.py           # 运行: python main.py
└── src/
    └── app.py        # 运行: python src/app.py（也会找到根目录的 .env）

.env 文件内容示例：

# gRPC 服务器配置
CTPLITE_GRPC_HOST=localhost
CTPLITE_GRPC_PORT=50051

# REST 服务器配置
CTPLITE_REST_HOST=localhost
CTPLITE_REST_PORT=8080

# CTP 认证信息
CTP_BROKER_ID=9999
CTP_USER_ID=your_user_id
CTP_PASSWORD=your_password
CTP_APP_ID=simnow_client_test
CTP_AUTH_CODE=0000000000000000
CTP_INVESTOR_ID=244753

# Token 认证（如果使用token认证，可替代密码认证）
CTPLITE_TOKEN=your_token

注意：

• .env 文件应该放在你的项目目录，而不是 CTPLite SDK 的安装目录
• 如果从不同目录运行脚本，确保 .env 文件在运行脚本时的当前工作目录或其父目录中
• 建议将 .env 添加到 .gitignore 中，避免提交敏感信息

3. 在代码中使用客户端：

from ctplite import GrpcClient

# config.py 会自动尝试加载 .env 文件（如果 python-dotenv 已安装）
# 默认会在当前工作目录及其父目录查找 .env 文件
# 现在可以直接使用客户端，配置会自动从环境变量读取
client = GrpcClient()
client.connect()

注意：config.py 会在初始化时自动尝试加载 .env 文件，无需手动调用 load_dotenv()。如果 .env 文件不在当前工作目录，可以手动调用 load_dotenv() 指定路径：

from dotenv import load_dotenv
from ctplite import GrpcClient

# 如果需要指定 .env 文件的路径，可以在导入 ctplite 之前调用
load_dotenv(dotenv_path='path/to/.env')  # 相对路径或绝对路径

# 或者
load_dotenv('.env')  # 指定文件名

# 然后使用客户端
client = GrpcClient()
client.connect()

使用 gRPC 客户端

from ctplite import GrpcClient

# 创建客户端并连接（配置会自动从环境变量或 .env 文件读取）
client = GrpcClient()
client.connect()

# 登录（可选，如果使用token认证）
client.login()

# 订阅行情
for stream_msg in client.subscribe_market_data(['IF2512', 'IF2601']):
    if stream_msg.error_code == 0:
        tick = stream_msg.tick
        print(f"{tick.symbol}: {tick.last_price}")

# 查询持仓
position_resp = client.query_position()
print(f"持仓数量: {len(position_resp.positions)}")

# 关闭连接
client.close()

使用 REST 客户端

from ctplite import RestClient

# 创建客户端（配置会自动从环境变量或 .env 文件读取）
client = RestClient()

# 登录
result = client.login()
print(f"登录成功: {result['success']}")

# 订阅行情
result = client.subscribe_market_data(['IF2512', 'IF2601'])
print(f"订阅成功: {result['success']}")

# 查询持仓
result = client.query_position()
print(f"持仓: {result['data']}")

# 登出
client.logout()

配置

环境变量配置

可以通过环境变量配置连接信息和认证信息：

export CTPLITE_GRPC_HOST=localhost
export CTPLITE_GRPC_PORT=50051
export CTPLITE_REST_HOST=localhost
export CTPLITE_REST_PORT=8080
export CTP_BROKER_ID=9999
export CTP_USER_ID=your_user_id
export CTP_PASSWORD=your_password
export CTPLITE_TOKEN=your_token  # 如果使用token认证

代码配置

from ctplite import config

# gRPC 配置
config.GRPC_HOST = "localhost"
config.GRPC_PORT = 50051

# REST 配置
config.REST_HOST = "localhost"
config.REST_PORT = 8080

# CTP 认证信息
config.CTP_BROKER_ID = "9999"
config.CTP_USER_ID = "your_user_id"
config.CTP_PASSWORD = "your_password"
config.CTP_APP_ID = "simnow_client_test"  # 可选
config.CTP_AUTH_CODE = "0000000000000000"  # 可选
config.CTP_INVESTOR_ID = "244753"  # 可选

# Token 认证（如果已登录）
config.TOKEN = "your_token"

功能特性

gRPC 客户端

• 认证服务：登录、登出、刷新token
• 行情服务：订阅/取消订阅行情数据（流式）
• 交易服务：
  • 下单、撤单
  • 查询持仓、资金账户、订单、成交
  • 流式接收订单状态更新
  • 查询合约信息、保证金率、手续费率
  • 结算确认、查询结算信息
  • 查询交易所、投资者信息
  • 查询最大报单量

REST 客户端

• 认证服务：登录、登出
• 行情服务：订阅/取消订阅行情数据（支持Kafka topic）
• 交易服务：与 gRPC 客户端相同的功能，通过 REST API 调用

API 文档

详细的 API 文档请参考：

• gRPC 客户端 API
• REST 客户端 API

依赖

• Python >= 3.8
• grpcio >= 1.70.0
• grpcio-tools >= 1.70.0
• protobuf >= 5.29.5
• requests >= 2.31.0

许可证

MIT License

打包和发布

前置准备

1. 安装构建工具：

pip install build twine

2. 注册 PyPI 账户：

   • 访问 PyPI 注册账户
   • 如需发布到测试仓库，访问 TestPyPI 注册账户

3. 配置认证信息（可选）：

   • 创建 ~/.pypirc 文件配置 PyPI 凭证
   • 或使用环境变量 TWINE_USERNAME 和 TWINE_PASSWORD

本地开发安装

在开发过程中，可以使用可编辑模式安装包：

cd sdk
pip install -e .

构建分发包

在 sdk/ 目录下执行：

# 清理之前的构建文件
rm -rf dist/ build/ *.egg-info

# 构建源码分发包和 wheel 包
python setup.py sdist build

构建完成后，会在 dist/ 目录下生成：

• ctplite-x.x.x.tar.gz - 源码分发包
• ctplite-x.x.x-py3-none-any.whl - wheel 分发包

发布到 PyPI

发布到正式 PyPI：

# 上传到 PyPI
twine upload dist/*.tar.gz

版本管理

发布新版本前，需要更新版本号：

1. 更新 setup.py 或 pyproject.toml 中的版本号
2. 更新 ctplite/__init__.py 中的 __version__
3. 提交版本变更：

git add .
git commit -m "Bump version to x.x.x"
git tag vx.x.x
git push origin main --tags

发布检查清单

• 更新版本号
• 更新 CHANGELOG（如有）
• 构建分发包并本地测试安装
• 发布到正式 PyPI

贡献

欢迎提交 Issue 和 Pull Request。

联系方式

如有问题，请通过 GitHub Issues 联系。