TA-Lib Python 形态识别 61 个蜡烛图 CDL 函数实战：从行情数组到买卖信号

【免费下载链接】ta-lib-pythonPython wrapper for TA-Lib (http://ta-lib.org/).项目地址: https://gitcode.com/gh_mirrors/ta/ta-lib-python

用 TA-Lib 的 Python 封装做 Python 形态识别：61 个CDL蜡烛图函数、Function / Abstract / Stream 三种调用方式一次讲透。读完即可在真实 K 线上提取吞没、晨星等信号。

🚀 快速上手：拿到第一个形态信号

假设你手里有一段日线行情，想批量扫描"三只乌鸦"这个经典看跌组合。Function API 一行搞定：

import numpy as np import talib # 任意等长的 open / high / low / close 一维浮点数组 o = np.random.random(120) h = o + 0.05 l = o - 0.05 c = o + np.random.random(120) * 0.1 result = talib.CDL3BLACKCROWS(o, h, l, c) signals = np.where(result == -100)[0] # 所有触发看跌形态的 K 线位置

result与输入等长，每个位置是一个整数：-100表示该根 K 线触发了看跌形态，100是看涨，0是未触发。对信号数组做一次np.where过滤，就得到了可直接用于回测的买卖点位。

读懂输出：-100 / 0 / 100 三值信号体系

形态识别是 TA-Lib 十类函数组中输出最特殊的一组：均线输出连续价格序列，而 形态识别函数参考 里的 61 个函数输出的是一列离散信号。

三点补充：

• 返回类型是np.int32数组，talib/_ta_lib.pyi 中 61 个函数的返回类型统一声明为NDArray[np.int32]。
• 三值约定写在每个函数的 docstring 里：Cython 实现 约第 919 行可见integer (values are -100, 0 or 100)；抽象层则由 talib/_abstract.pxi 约第 754 行的'Output is a candlestick'标志统一渲染出同样的说明。
• 方向语义有测试背书：tests/test_func.py 约第 288 行的test_CDL3BLACKCROWS断言，三只乌鸦触发位置输出-100。

输入约定与 lookback 机制

输入侧只有四个数组，且必须等长。所有形态函数的签名都是CDLxxxx(open, high, low, close)，四个一维float64数组长度一致，否则 talib/_func.pxi 中check_length4直接报错。任一数组长度为 0 时返回空数组。

为什么没有timeperiod参数？均线类函数需要用户指定窗口长度，而形态的判定周期由形态本身决定——十字星只看 1 根，吞没看 2 根，晨星看 3 根——所以签名里没有可配参数（7 个形态函数多出的penetration例外，见后文）。

lookback 之前的位置填 0，不是 NaN。与其他函数把前段设为 NaN 不同，形态函数把"历史不足、无法判定"的位置统一填 0，含义是"未触发"，下游无需做 NaN 处理。机制在 talib/_func.pxi 约第 937 行：

• check_begidx4先跳过输入前部的 NaN，得到begidx；
• lookback = begidx + lib.TA_CDL2CROWS_Lookback()，lookback 值由底层 C 库决定；
• make_int_array(length, lookback)分配输出并令前段为 0。

仓库测试给出了直观例子：20 根 K 线输入CDL3BLACKCROWS，输出前 17 位全 0、第 17 位（索引从 0 计）为-100，与三只乌鸦"需要 3 根 K 线"的直觉吻合。

61 个形态全景

以下按构成 K 线数量把 61 个函数分成三组，与 talib/_ta_lib.pyi 中的声明一一对应。"信号方向"指形态出现时的典型语义，多数形态随所处趋势双向成立。

单根 K 线形态（17 个）

双根 K 线组合（16 个）

三根及以上复合形态（28 个）

penetration：7 个函数的灵敏度开关

61 个函数中有且仅有7 个额外接受一个penetration浮点参数（默认0，见 talib/_ta_lib.pyi 约第 701 行penetration: float = 0）。它控制形态判定中对 K 线实体穿透/重叠比例的宽容程度：

调参建议：penetration=0是最严格的零容忍判定；若目标品种波动大、实体比例经常差一点而漏触发，可以调高取值（例如penetration=0.2）放宽重叠要求。注意具体阈值定义在底层 C 库 TA-Lib 中，Python 封装层只是透传，不同版本间行为以 C 库为准。

三种调用方式怎么选

Abstract 方式——输入是字典时直接运行，接 pandas DataFrame 也只需同一套入口（docs/abstract.md）：

import numpy as np import pandas as pd from talib import abstract # 方式一：dict of arrays data = {'open': np.random.random(100), 'high': np.random.random(100), 'low': np.random.random(100), 'close': np.random.random(100)} sig = abstract.Function('CDLDOJI').run(data) # 方式二：pandas DataFrame（列为 open/high/low/close） df = pd.DataFrame(data) sig2 = abstract.CDLDOJI(df) print(sig2[-5:]) # 与 Function API 结果一致

tests/test_abstract.py 约第 114 行直接验证了两种入口的等价性：func.CDLDOJI(...)与abstract.Function('CDLDOJI').run(...)输出完全相同。

Stream 方式——打开句柄后用update逐根推进，无需重算历史：

from talib import stream handle = stream.CDLDOJI(o, h, l, c) # 用历史 K 线建立句柄 print(handle.value) # 最新一根的信号：-100 / 0 / 100 的 int 标量 signal = handle.update(o_new, h_new, l_new, c_new) # 新 K 线收盘后增量计算

句柄底层是 talib/_stream.pxi 为每个形态封装的OpenAndFill / Open / Update / Peek / Value / Clone / Close / OutRange / Advance一组 C 流式函数（约第 280 行起）；handle.value与 Function API 数组末位逐位一致，且结果可 pickle 序列化（见 tests/test_stream.py 约第 311 行）。

实现细节与测试验证

• Cython 模板：talib/_func.pxi 中 61 个形态函数按同一模板生成（以CDL2CROWS约第 911 行为例）：check_array校验四个数组 →check_length4校验等长 →check_begidx4跳过 NaN 前段 → 调lib.TA_CDL2CROWS_Lookback()与lib.TA_CDL2CROWS→make_int_array产出前段填 0 的int32输出。
• 类型桩：talib/_ta_lib.pyi 收录 61 个函数签名（约第 650 行起），返回类型统一NDArray[np.int32]，IDE 补全与静态检查以此为准。
• 函数清单：talib/_func.pxi 约第 7054 行的__TA_FUNCTION_NAMES__与 talib/init.py 的导出列表（约第 269 行起）完整收录全部CDL*名称，talib.get_functions()亦与其一致。
• 批量测试：tests/test_func.py 用 20 根样例 K 线逐位断言CDL3BLACKCROWS输出，精确验证"前段填 0 + 触发位 -100"。
• 流式测试：tests/test_stream.py 通过'Output is a candlestick'标志自动收集全部形态函数做参数化测试，覆盖句柄创建、增量update与批量结果的一致性。

相关文档

• 形态识别函数参考
• 全部函数列表
• 函数 API 使用指南
• 抽象 API 快速上手
• 文档索引

【免费下载链接】ta-lib-pythonPython wrapper for TA-Lib (http://ta-lib.org/).项目地址: https://gitcode.com/gh_mirrors/ta/ta-lib-python