homalos-ctp 6.7.11.2

CTP Python API extension module construction.

English | 简体中文

Project Description

This project automatically generates Python APIs based on the CTP C++ API, making it easier for CTP Python developers to maintain the latest CTP interfaces and quickly upgrade CTP versions.

Note: This project has only been tested under CTP v6.7.11. Other versions have not been tested. The project CTP version number is configured in the ctp/__init__.py file.

1. Compilation Environment

This project is compiled using the following environment. If you use other tool versions, please make appropriate adjustments.

• Windows 11 + MSVC 2022

• Python 3.13.6 virtual environment, installed by UV.

• CTP v6.7.11: CTP official download link

• Meson + Ninja: A modern C++ extension build system.

• Pybind11: Python C++ bindings

• UV: A modern Python package manager with faster installation and smarter dependency resolution.

2. Project Structure

ctp/
├── 📂 assets/		# Resource files
├── 📂 ctp/		# CTP interface module
│   ├── 📂 api/		# CTP API module
│   │   ├── 📂 generator/		# C++ and Python binding generation script
│   │   ├── 📂 include/		# CTP API header files
│   │   ├── 📂 libs/		# CTP API static library files
│   │   ├── 📂 src/		# CTP and Python binding code files
│   │   ├── 📁 __init__.py		# MdApi and TdApi initialization imports
│   │   ├── 📁 ctpmd.cp313-win_amd64.pyd		# Market extension module compiled from C++ to Python
│   │   ├── 📁 ctpmd.pyi		# Stub file for the market extension module
│   │   ├── 📁 ctptd.cp313-win_amd64.pyd		# Trading extension module compiled from C++ to Python
│   │   ├── 📁 ctptd.pyi		# Stub file for the trading extension module
│   │   ├── 📁 thostmduserapi_se.dll		# Windows CTP market API dynamic link library
│   │   ├── 📁 thostmduserapi_se.so		# Linux CTP market API dynamic link library
│   │   ├── 📁 thosttraderapi_se.dll		# Windows CTP trading API dynamic link library
│   │   ├── 📁 thosttraderapi_se.so		# Linux CTP trading API dynamic link library
│   ├── 📁 __init__.py		# CTP version configuration file
│   ├── 📁 ctp.h		# Task processing and encoding conversion
├── 📂 docs/		# Project documentation
├── 📁 .gitignore		# Git commit ignore files, automatically generated by UV
├── 📁 .python-version	# Project Python version file, automatically generated by UV
├── 📁 LICENSE		# Project license file
├── 📁 README.md		# Project description file in Chinese
├── 📁 README_CN.md		# Project description file in English
├── 📁 build.py		# Extension module automated compilation script, assembling Meson commands
├── 📁 demo.py		# Extension module usage examples
├── 📁 hatch_build.py		# Hatch hook, set the platform identifier when packaging with hatch
├── 📁 meson.build		# Meson build configuration file
├── 📁 pyproject.toml		# Python project management configuration file, automatically generated by uv
└── 📁 uv.lock		# uv lock file, automatically generated by uv

3. Install the Basic Environment (skip if already installed)

1. Install UV

On Windows

Method 1: Global Installation (Recommended, choose one)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Method 2: Install in a Single Python Environment (Choose one)

pip install uv

On Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install Python (Perform this step with Method 1, skip this with Method 2). I use 3.13.6; you can install your preferred version.

uv python install 3.13

4. Usage

1. Install a Python virtual environment and dependencies (execute from the root directory)

# Use uv to create a Python virtual environment with a specified version in the current project.

uv venv --python 3.13 .venv

# Install dependent libraries

uv add meson-python

uv add pybind11

uv add pybind11-stubgen

2. Execute the one-click build script in the generator directory (to generate Python bindings for the CTP C++ API)

# Activate the Python virtual environment and enter the generator.

.venv\Scripts\activate

cd homalos-ctp\api\generator

# Generate binding files with one click.

python generate_onekey.py

3. Execute the following build script in the root directory to generate the CTP C++ API and encapsulate it into a Python-callable interface.

# Compile the CTP Python API with one click.

python build.py

5. Demo test

Fill in the CTP environment information in demo.py in the project root directory and run

6. Script Function Details

The generator script is located in ctp/api/generator/

1. generator_function_const.py

• Purpose: Generates basic function constant files
• Function:
• Reads the CTP header files ThostFtdcMdApi.h and ThostFtdcTraderApi.h.h
• Parses the functions therein and generates ctp_function_const.py (function constant definitions)

2. generate_data_type.py

• Purpose: Generates data type definition files
• Function:
• Reads the CTP header file ThostFtdcUserApiDataType.h
• Parses the #define constant definitions and typedef type definitions therein
• Generates ctp_function_const.py

3. generate_struct.py

• Purpose: Generates structure definition files
• Function:
• Reads the CTP header file ThostFtdcUserApiStruct.h
• Relies on the type mappings in ctp_typedef.py
• Parses the C++ structure definition and generates the Python dictionary-formatted structure definition file ctp_struct.py

4. generate_api_functions.py

• Purpose: Generates API function binding code
• Function:
• Reads the CTP API header files (such as ThostFtdcTraderApi.h and ThostFtdcMdApi.h)
• Relies on the structure definitions in ctp_struct.py
• Generates a large number of C++ source code files for Python bindings

5. generate_dll_entry.py

• Purpose: Generates the C++ DLL entry point code file

• Function:

• Generates three files: dllmain.cpp, stdafx.cpp, and stdafx.h.

• dllmain.cpp: Contains the standard DLL entry point function, handling process and thread loading/unloading.

• stdafx.cpp: A simple precompiled header include file.

• stdafx.h: Contains the Windows API header files and common definitions.

6. generate_cpp.py

• Purpose: Generates cpp and h files
• Function: **Generates ctpmd.cpp, ctpmd.h, and ctptd.cpp, ctptd.h, for ctp.api.src.ctpmd and ctp.api.src.ctptd, respectively.
• The header file contains complete class declarations and function prototypes.
• The cpp file contains all implementation and bindings.

7. generate_onekey.py

• Purpose: One-click assembles all md and td header, source, and other files to generate cpp and h files
• Function:
• One-click assembles the files generated by the above files, as well as header, source, and other files, to generate four files: ctpmd.cpp, ctpmd.h, and ctptd.cpp, ctptd.h.

8. build.py

• Purpose: One-click compiles the CTP C++ API into a Python API
• Function:
• One-click compiles the Python-callable CTP API files, located in ctp/api/. These files include:
• ctpmd.cp313-win_amd64.pyd
• ctptd.cp313-win_amd64.pyd
• ctpmd.pyi
• ctptd.pyi

File Dependencies:

1. generator_function_const.py → Generate ctp_function_const.py
2. generate_data_type.py → Generate ctp_typedef.py and ctp_constant.py
3. generate_struct.py (depends on ctp_typedef.py) → Generate ctp_struct.py
4. generate_api_functions.py (depends on ctp_struct.py and ctp_function_const.py) → Generate multiple API header and source binding files for md and td
5. generate_dll_entry.py → Generate dllmain.cpp, stdafx.cpp, and stdafx.h
6. generate_cpp.py (depends on all the above files, as well as the generated header and source files) → Generates ctpmd.cpp, ctpmd.h, and ctptd.cpp and ctptd.h
7. generate_onekey.py → Assembles ctpmd.cpp, ctpmd.h, and ctptd.cpp and ctptd.h files with one click (equivalent to executing the above process with one click)
8. build.py (depends on the ctpmd and ctptd modules in ctp/api/src/) → Compiles ctpmd.cp313-win_amd64.pyd, ctptd.cp313-win_amd64.pyd, ctpmd.pyi, and ctptd.pyi with one click

7. Script Usage

The code generated by these scripts is used to:

• Encapsulate the CTP C++ API into a Python-callable interface
• Automatically handle data type conversion
• Generate Python bindings for callback functions
• Generate Python bindings for request functions

8. Advantages

• Use pybind to bind C++ to the Python CTP API, offering superior performance compared to SWIG conversion.
• Automatic synchronization: When the CTP official header files are updated, the latest h, dll, so, and lib files are replaced. After executing the generated script, the script will automatically reflect the latest virtual functions.
• Easy maintenance: No need to manually update a large number of hard-coded function declarations.
• Reduced errors: Avoid omissions or errors that may result from manual maintenance.
• Improved efficiency: Developers only need to focus on business logic, without worrying about changes to the underlying interfaces.

Summary: This is a complete code generation toolchain that automatically generates Python bindings for the CTP API, eliminating the need to manually write repetitive binding code and improving maintainability and robustness.

9. Community Support

• Technical Exchange (QQ Group): 446042777
• pypi.org

10. Disclaimer

Disclaimer content

11. 补充

Meson: Similar to Make and CMake, its main task is to configure the compilation environment, generate compilation instructions (for example, for Ninja), and manage the entire compilation process. It does not directly compile code, but rather drives tools like Ninja to do so.

Pybind11: A lightweight C++ library for exposing (binding) C++ code to the Python interpreter. It allows Python code to seamlessly call C++ functions and classes, just like calling regular Python modules. Its core goal is to provide an extremely simple, nearly boilerplate-free interface that easily combines the high-performance computing capabilities of C++ with the ease of use and vast Python ecosystem.