YuWuKunCheng
247 lines
8.0 KiB
Markdown
247 lines
8.0 KiB
Markdown
# chanlun — 缠论技术分析 Python 绑定
|
||
|
||
[](https://pypi.org/project/chanlun/)
|
||
[](LICENSE)
|
||
|
||
基于 [chanlun](./chanlun/) Rust 核心库的 PyO3 高性能 Python 绑定，API 参考 `chan.py` 设计，高度兼容。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pip install chanlun
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```python
|
||
import chanlun
|
||
|
||
# 创建配置（全部默认值）
|
||
config = chanlun.缠论配置()
|
||
|
||
# 读取 K 线数据文件（文件名需遵循 `符号-周期-起始时间戳-结束时间戳.nb` 格式）
|
||
obs = chanlun.观察者.读取数据文件("path/to/btcusd-300-1631772074-1632222374.nb", config)
|
||
|
||
# 查看各层级序列
|
||
print(f"K线数量: {len(obs.普通K线序列)}")
|
||
print(f"笔数量: {len(obs.笔序列)}")
|
||
print(f"线段数量: {len(obs.线段序列)}")
|
||
print(f"中枢数量: {len(obs.中枢序列)}")
|
||
|
||
# 或使用立体分析器进行多周期分析
|
||
analyzer = chanlun.立体分析器("BTCUSD", [60, 60*5, 60*5*6], config)
|
||
# 逐根投喂 K 线...
|
||
```
|
||
|
||
## 信号计算 (Rust 核心)
|
||
|
||
信号框架（Signal/Factor/Event/Position/Operate）已全部迁移到 Rust 核心，通过 PyO3 暴露给 Python。
|
||
|
||
### 调用信号函数
|
||
|
||
```python
|
||
from chanlun._chanlun import 信号引擎, call_signal, list_signals, get_signal_template
|
||
|
||
# 准备数据
|
||
analyzer = chanlun.立体分析器("btcusd", [300, 900, 3600], chanlun.缠论配置())
|
||
for k in klines:
|
||
analyzer.投喂K线(k)
|
||
|
||
# ── 方式 1: 信号引擎（批量） ──
|
||
engine = 信号引擎(信号配置=[
|
||
{"name": "bar_zdt_V230331", "freq": "300"},
|
||
{"name": "macd_金叉_V260601", "freq": "300", "fast": "13", "slow": "31"},
|
||
])
|
||
engine.自动挂载指标(analyzer)
|
||
result = engine.更新(analyzer) # → {key: value}
|
||
full = engine.更新_完整(analyzer) # → {"signals": {...}, "market": {...}}
|
||
|
||
# ── 方式 2: call_signal（单函数） ──
|
||
obs = analyzer._单体分析器[300]
|
||
signals = call_signal("macd_金叉_V260601", obs, {"freq": "5分钟", "di": "1"})
|
||
for s in signals:
|
||
print(s.key, s.value)
|
||
|
||
# ── 方式 3: SignalOrchestrator（高级编排，含行情） ──
|
||
from chanlun.signal_orchestrator import SignalOrchestrator
|
||
orch = SignalOrchestrator(analyzer, 信号配置=[...])
|
||
orch.更新()
|
||
orch.信号字典 # → {信号..., "symbol": "btcusd", "close": 50050, ...}
|
||
|
||
# ── 方式 4: 注册表探索 ──
|
||
list_signals() # → ["bar_zdt_V230331", ...] (7个)
|
||
get_signal_template("bar_zdt_V230331") # → "{freq}_D{di}_涨跌停V230331"
|
||
```
|
||
|
||
### 已注册信号函数（8个）
|
||
|
||
| 信号名 | 模板 | 说明 |
|
||
|--------|------|------|
|
||
| `bar_zdt_V230331` | `{freq}_D{di}_涨跌停V230331` | 涨跌停检测 |
|
||
| `macd_金叉_V260601` | `{freq}_D{di}#MACD#{fast}#{slow}#{signal}_MACD交叉V260601` | MACD 金叉/死叉 |
|
||
| `tas_macd_direct_V221106` | `{freq}_D{di}#MACD#{fast}#{slow}#{signal}_MACD方向V221106` | MACD DIF 方向 |
|
||
| `tas_ma_base_V230313` | `{freq}_D{di}#{ma_type}#{timeperiod}MO{max_overlap}_BS辅助V230313` | MA 均线多空 |
|
||
| `cxt_停顿分型_V230106` | `{freq}_D{di}停顿分型_BE辅助V230106` | 停顿分型检测 |
|
||
| `cxt_bi_end_V230222` | `{freq}_D1MO{max_overlap}_BE辅助V230222` | 笔结束辅助 |
|
||
| `youwukuncheng_中枢第三买卖点_V230602` | `{freq}_D1MO{max_overlap}_中枢第三买卖点V230602` | 中枢第三买卖点 |
|
||
|
||
### Python 信号函数混合调用
|
||
|
||
编排器支持 Rust + Python 信号混合执行：
|
||
|
||
```python
|
||
orch = SignalOrchestrator(analyzer, 信号配置=[
|
||
{"name": "bar_zdt_V230331", "freq": 300}, # → Rust 路径
|
||
{"name": "chanlun.signals.demo.tas_ma_base_V230313", ...}, # → Python 回退
|
||
])
|
||
orch.更新() # 自动分类，Rust 批量 + Python 逐个
|
||
```
|
||
|
||
## 编写信号函数
|
||
|
||
### Rust 信号函数（推荐）
|
||
|
||
```rust
|
||
// chanlun/src/signal/functions/my_signals.rs
|
||
use chanlun_signal_macros::signal;
|
||
use chanlun::business::observer::观察者;
|
||
use chanlun::signal::Signal;
|
||
use std::collections::HashMap;
|
||
use serde_json::Value;
|
||
|
||
#[signal(
|
||
name = "my_signal_V000001",
|
||
template = "{freq}_D{di}_模板V000001"
|
||
)]
|
||
pub fn my_signal_V000001(obs: &观察者, params: &HashMap<String, Value>) -> Vec<Signal> {
|
||
obs.确保指标已计算();
|
||
|
||
let di = params.get("di").and_then(|v| v.as_i64()).unwrap_or(1) as usize;
|
||
let freq = params.get("freq").and_then(|v| v.as_str()).unwrap_or("日线");
|
||
|
||
let k1 = freq.to_string();
|
||
let k2 = format!("D{di}");
|
||
let k3 = "模板V000001";
|
||
|
||
let klines = &obs.普通K线序列;
|
||
if klines.len() < di + 1 {
|
||
return vec![Signal::new_empty(&k1, &k2, k3)];
|
||
}
|
||
|
||
let k线 = &klines[klines.len() - di];
|
||
if k线.收盘价 > k线.开盘价 {
|
||
vec![Signal::new(&k1, &k2, k3, "阳线", "任意", "任意", 0)]
|
||
} else {
|
||
vec![Signal::new_empty(&k1, &k2, k3)]
|
||
}
|
||
}
|
||
```
|
||
|
||
然后在 `chanlun/src/signal/functions/mod.rs` 中添加 `pub mod my_signals;`，重新编译即可自动注册。
|
||
|
||
### 动态加载 .so 插件
|
||
|
||
信号函数可以编译为独立 `.so` 动态库，运行时加载。支持两种注册方式。
|
||
|
||
**方式 A：手动 C-ABI 注册**
|
||
|
||
```rust
|
||
// 独立 crate (cdylib)
|
||
fn my_plugin_signal(obs: &观察者, params: &HashMap<String, Value>) -> Vec<Signal> { ... }
|
||
|
||
unsafe extern "C" {
|
||
fn chanlun_register_signal(name: *const c_char, template: *const c_char, func: SignalFn) -> i32;
|
||
fn chanlun_unregister_signal(name: *const c_char) -> i32;
|
||
}
|
||
|
||
#[unsafe(no_mangle)]
|
||
pub unsafe extern "C" fn init_plugin() -> i32 {
|
||
chanlun_register_signal(
|
||
c"my_plugin_signal_V000001".as_ptr(),
|
||
c"{freq}_D{di}_模板V000001".as_ptr(),
|
||
my_plugin_signal,
|
||
)
|
||
}
|
||
```
|
||
|
||
**方式 B：`#[signal]` 宏 + inventory 批量提交**
|
||
|
||
```rust
|
||
use chanlun_signal_macros::signal;
|
||
|
||
#[signal(name = "my_plugin_signal_V000001", template = "...", crate_path = "::chanlun")]
|
||
fn my_plugin_signal_V000001(obs: &观察者, params: &HashMap<String, Value>) -> Vec<Signal> { ... }
|
||
|
||
#[unsafe(no_mangle)]
|
||
pub unsafe extern "C" fn init_plugin() -> i32 {
|
||
for desc in inventory::iter::<SignalDescriptor> {
|
||
chanlun_register_signal(name_ptr, template_ptr, desc.func);
|
||
}
|
||
0
|
||
}
|
||
```
|
||
|
||
Python 加载：
|
||
|
||
```python
|
||
import ctypes, os, sys
|
||
sys.setdlopenflags(os.RTLD_LAZY | os.RTLD_GLOBAL)
|
||
import chanlun._chanlun # 先加载宿主
|
||
|
||
plugin = ctypes.CDLL("./libmy_plugin.so")
|
||
plugin.init_plugin()
|
||
|
||
# 插件信号现在可通过 call_signal / 信号引擎 调用
|
||
from chanlun._chanlun import call_signal
|
||
call_signal("my_plugin_signal_V000001", obs, params)
|
||
```
|
||
|
||
完整示例见 [examples/plugin-demo/](./examples/plugin-demo/)。
|
||
|
||
## 从源码构建
|
||
|
||
前置依赖: [Rust](https://www.rust-lang.org) + [maturin](https://www.maturin.rs)
|
||
|
||
```bash
|
||
pip install maturin
|
||
|
||
# 开发模式（直接安装到当前 venv）
|
||
cd chanlun-py && maturin develop
|
||
|
||
# 或构建 wheel
|
||
cd chanlun-py && maturin build --release
|
||
pip install target/wheels/chanlun-*.whl
|
||
```
|
||
|
||
也可使用项目内的 `build.sh`:
|
||
|
||
```bash
|
||
cd chanlun-py
|
||
./build.sh develop # 开发安装
|
||
./build.sh wheel # 构建 wheel
|
||
./build.sh test # 运行集成测试
|
||
```
|
||
|
||
## 导出类
|
||
|
||
| 类别 | 类名 | 说明 |
|
||
|------|------|------|
|
||
| 枚举 | `买卖点类型`, `相对方向`, `分型结构`, `Operate` | 缠论基础枚举 |
|
||
| 数据 | `缺口`, `K线`, `缠论K线` | K 线数据结构 |
|
||
| 结构 | `分型`, `虚线`, `线段特征`, `特征分型` | 分析层级结构 |
|
||
| 指标 | `平滑异同移动平均线`, `相对强弱指数`, `随机指标` | MACD/RSI/KDJ |
|
||
| 算法 | `笔`, `线段`, `中枢`, `背驰分析` | 识别算法 |
|
||
| 业务 | `缠论配置`, `观察者`, `K线合成器`, `立体分析器`, `买卖点` | 分析框架 |
|
||
| 信号 | `Signal`, `Factor`, `Event`, `Position`, `信号引擎` | 信号匹配+计算引擎 |
|
||
| 注册表 | `call_signal`, `list_signals`, `get_signal_template`, `register_signal`, `unregister_signal` | 信号发现+动态注册 |
|
||
|
||
## 兼容性
|
||
|
||
- Python 3.9+
|
||
- 类名 / 方法名 / 字段名与 `chan.py` 保持一致
|
||
- 支持 `.nb` 二进制文件格式（大端字节序）
|
||
|
||
## 许可
|
||
|
||
MIT
|