chan.py: open chanlun analysis in Python, and the gap between the design and the public code

Four levels of depth in one Python framework

chan.py is a Python implementation of chanlun, a Chinese technical analysis method built on the idea that price movement decomposes hierarchically: raw candles contain fractals, fractals combine into strokes, strokes carry feature sequences that build segments, and overlapping segments form central zones where supply and demand balance. The project's own description calls it an open implementation covering morphological and dynamical buy/sell point analysis, multi-timeframe K-line linkage, nested interval strategies, plotting, several data sources, strategy development and trading system integration.

The README organises the framework into four usage levels, and that list is the fastest way to understand its intended shape:

- Level 1, chanlun basic element calculation: fractals, strokes, segments, central zones and buy/sell points, with parent-level calculation, multi-level linkage, nested interval buy/sell point calculation, configurable indicators (MACD, moving averages, Bollinger bands, Demark), data reads from futu, akshare and baostock plus local files, matplotlib plotting with global or step-by-step replay, and deployment as an API service. - Level 2, strategy buy/sell point development: morphological buy/sell points, custom strategies for dynamical buy/sell points, and configurable divergence algorithms. - Level 3, machine learning: more than 500 features per buy/sell point, XGB, LightGBM and MLP models, backtesting and evaluation, and an AutoML hyperparameter search. - Level 4, live trading: online and offline feature consistency checks, a Futu trading engine covering paper and live accounts, real-time quotes from sina, pytdx, futu and akshare, and mysql or sqlite backends with a dedicated API for the chanlun database.

The repository is MIT licensed with 2,181 stars and 815 forks, and the last push was 2026-09-24. A fork count near 37 percent of stars is worth noting on its own, because it is the pattern you see when people clone a framework intending to modify it rather than read it. The topic tags list automl, chanlun, machinelearning, plot, python, quant, stock and one that reads stragety, a misspelling of strategy that has been left in place.

The documentation describes 22,000 lines, the public tree holds about 5,300

This is the first thing to establish before planning any work, and the README is unusually direct about it. A first special note states that the currently public code contains only basic static calculation capability, and that strategy classes, features, models, the AutoML framework and trading engine integration are not included. It puts numbers on the gap: the complete code is around 22,000 lines, the public version around 5,300.

The same note then says the README corresponds to the complete version and may therefore be inconsistent with the public code in certain places, and points readers to a separate quick start guide, quick_guide.md, as the reference to prefer. A second note sets Python 3.11 as the minimum dependency version.

Both halves of that split are visible in the repository root, which holds Chan.py, ChanConfig.py, main.py, quick_guide.md and the element packages Bi, Seg, ZS, KLine, BuySellPoint, Combiner, Common, Math, Plot, ChanModel, DataAPI, App, Debug, Script and Image. Directories that the README's own file listing describes in detail, among them Config, CustomBuySellPoint, ModelStrategy and OfflineData, are not present at that root.

So read the README as a design document for the finished framework and quick_guide.md as the guide to the code you can actually clone. If a README section describes a module you cannot find on disk, that is the documented public and full split rather than a broken checkout, and it is worth confirming before you spend a day on level 3 or level 4.

Three segment algorithms in one directory

The Seg directory is where the design gets interesting, because chanlun segment calculation is disputed among practitioners and this project ships three interpretations rather than picking one for you:

- SegListChan.py computes segments following the original text of the theory. - SegListDef.py computes segments from a formal definition. - SegListDYH.py follows a named practitioner's approach, described in the file listing as a 1+1 breakthrough.

The supporting files explain how they fit together. Eigen.py and EigenFX.py hold the feature sequence and its fractals, SegConfig.py carries configuration, SegListComm.py is the shared parent class for the segment calculation framework, and Seg.py is the segment type itself. In the Bi directory the same pattern appears with BiConfig.py, BiList.py and Bi.py.

That layout implies the segment algorithm is a swappable component rather than a fixed decision baked into the library. It also explains the README's claim that basic elements support inheritance from base classes with multiple configuration options: you are expected to subclass strokes, segments and buy/sell points whenever the built-in behaviour does not match how you read the theory. The Common package reinforces that reading, with a cache decorator described as substantially improving compute performance, an enum module covering K-line type, direction, stroke type and central zone type, and a time class built to handle multi-level linkage.

Data sources, offline storage and real-time quotes

Level 1 already needs a data layer before any chanlun arithmetic runs, and the DataAPI package is the widest part of the public tree. It defines an abstract parent class for general stock data, concrete implementations for akshare, baostock, Futu and ETF data, an offline data interface, a market value filter, and a SnapshotAPI subdirectory for real-time quotes.

The snapshot layer has a unified calling interface over four implementations, and the file listing is specific about market coverage: akshare covers A-shares, ETFs, Hong Kong and US markets; Futu covers A-shares, Hong Kong and US; pytdx covers A-shares and ETFs; Sina covers A-shares, ETFs, Hong Kong and US. The README describes this as high performance local offline data update and storage, and says you can supply your own data reader and parser, which matters if your bars come from a broker or a database nobody here has written an adapter for.

The indicator set sits in Math: MACD, Bollinger bands, Demark, an outlier detection class, a trend model supporting moving average, maximum and minimum, and a trend line. The README notes that several different indicators can be configured to participate in the calculation at once, naming turnover rate and volume alongside MACD, moving averages, Bollinger bands and Demark. The Combiner package merges K-lines with feature sequences, and KLine holds the bar types plus a TradeInfo class for turnover rate, volume and turnover value.

Plotting, replay and an API boundary

Plotting is treated as an extraction problem rather than a rendering one. The README says the default is matplotlib, supporting both global drawing and step-by-step replay, and that plot elements can be extracted as information so that any drawing engine, bokeh named as an example, can be plugged in behind it. Configuration is split into plot_config and plot_para, which is the arrangement you would expect if the intent is to drive charts from a service rather than a notebook.

Level 1 also claims the framework can be conveniently deployed as an API service. Taken together with the four-tier design, that suggests the intended production shape: a static calculation core sitting behind an HTTP boundary, with plotting and trading as separate layers above it. That is a different architecture from a script you run once per symbol, and it is the reason main.py sits at the repository root next to Chan.py and ChanConfig.py.

For anyone reading the framework's central zone logic, the README's table of contents splits it into within-segment central zones and cross-segment central zones, and lists dedicated sections for CChan usage, CChanConfig configuration, features, models, the trading system and custom development. Much of that list maps onto the modules the README itself marks as not public, so the table of contents is a map of the full design rather than of the clone you will have.

Python 3.11 is a floor, and the reason given is performance

The second special note in the README sets Python 3.11 as the minimum dependency version, on the stated grounds that the project is heavily compute intensive and that Python 3.11 brought a large speed improvement. The author reports that compute time is shortened by roughly 16 percent compared with Python 3.8.5, and says subsequent development is based on 3.11.

That figure is the author's own measurement rather than something independently documented, so treat it as a reason to use 3.11 or newer instead of as a benchmark to plan around. The practical consequence is firmer than the number itself: if you are on Python 3.8 through 3.10, the repository will not run as documented, and the cache decorator in Common plus the segment and central zone calculations are exactly the kind of repeated arithmetic where interpreter overhead shows up.

The version floor also tells you something about the audience. This is a framework for people who intend to run chanlun calculation over many symbols and many timeframes at once, which is consistent with the emphasis on offline storage, parent-level calculation and multi-level linkage rather than with a charting script.

Editorial conclusion

chan.py is worth using for its static chanlun calculation core: the Bi, Seg, ZS, KLine, Combiner and Math packages are laid out the way the theory actually decomposes, and the three segment implementations sitting side by side in Seg/ is the clearest signal that you are meant to pick an interpretation rather than accept one. Start from quick_guide.md, not from the README table of contents, because the README describes the complete framework and the repository publishes about 5,300 of its roughly 22,000 lines. Set Python 3.11 or newer before anything else, since that floor is not negotiable according to the author. Judge scope by what imports: level 1 of the four documented tiers is present, and strategy classes, features, models, AutoML and trading engine integration are described but not in the public tree. If your goal is a production signal pipeline, budget for writing those three layers yourself on top of Chan.py and ChanConfig.py, and there is no release to fall back on, so work from a clone.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Vespa314/chan.py on GitHub