tdxrs: Rust-Powered TDX Market Data Parser with Python Bindings

The Problem tdxrs Solves: TDX Parsing Speed at Scale

TongDaXin (TDX) is a widely used stock trading platform in China that stores historical market data in proprietary binary formats: .day for daily bars, .lc5 and .lc1 for minute bars, .dat for sector data, and gpcw*.dat for financial statements. The original Python library tdxpy (also known as pytdx) parses these files but performs the work in pure Python, making bulk processing of large historical datasets slow.

tdxrs addresses this by rewriting the parsing core in Rust and exposing the result through PyO3 bindings. The library maintains API compatibility with tdxpy, so existing code that calls tdxpy can switch to tdxrs by changing the import. The README reports local file parse speeds of 9 to 11 times faster than tdxpy across daily bars, minute bars, sector data, and financial data. The project targets Python developers, quantitative analysts, and data engineers working with Chinese A-share market data who want faster throughput without abandoning their Python workflows.

Architecture: Rust Core, PyO3 Bindings, and Four Client Modes

The library is built with Rust 2021 edition and uses zero lines of unsafe code, according to the repository metadata. The Rust crate compiles as both a cdylib (for the Python extension module) and an rlib (for Rust unit tests). PyO3 provides the binding layer; maturin handles the build and packaging. The codebase includes 139 unit and integration tests and six core crate dependencies: pyo3, flate2, tokio, serde, thiserror, and encoding_rs. The encoding_rs crate handles GBK and GB2312 encoding in sector and financial data that contains Chinese names.

For network access the library provides four client types suited to different workloads. TdxHqClient is the default: it uses a connection pool of five connections with heartbeats, retry logic, and caching, suited for sequential requests. TdxDirectClient creates a fresh TCP connection per request and the README states it shows no performance degradation at 60 concurrent threads, making it the choice for high-concurrency workloads. AsyncTdxHqClient uses tokio for integration with async Python ecosystems. TdxHqFundClient shares the connection pool and adds fund code validation for ETF, LOF, REITs, and graded fund data.

For local file parsing the library provides DailyBarReader, MinBarReader, LcMinBarReader, BlockReader, and FinancialReader, each accepting raw file bytes and returning either a dict, a tuple, or a pandas DataFrame.

Installing tdxrs and Running a First Market Data Query

Installation from PyPI requires Python 3.11 or newer:

pip install tdxrs

For optional DataFrame output, install pandas separately. The README notes that pandas is not a hard dependency; DataFrame methods are available only when it is present.

To build from source, clone the repository and use maturin:

git clone https://github.com/jiangtaovan/tdxrs && cd tdxrs
pip install maturin
maturin develop --release

Once installed, connecting to a TDX server and fetching daily candlestick data for a single stock looks like the example in the README:

from tdxrs import TdxHqClient
from tdxrs.constants import MARKET_SH, KLINE_DAILY, FQ_QFQ

client = TdxHqClient()
client.connect_to_any()
df = client.get_security_bars_dataframe(KLINE_DAILY, MARKET_SH, "600519", 0, 500)

The client selects a TDX server automatically. The third argument is the stock code, the fourth is the offset from the most recent bar, and the fifth is the count. The result is a pandas DataFrame when pandas is installed.

Local File Parsing: Where the Speed Advantage Is Largest

Network API calls improve by 1.3 to 1.5 times compared to tdxpy, a gain that is bounded by round-trip latency. Local file parsing is where the Rust core makes the largest difference. The README benchmarks show parsing 1,000 daily bars taking 0.3 ms in tdxrs versus 2.8 ms in tdxpy (a 9x improvement), and financial data for 500 entries taking 0.8 ms versus 8.5 ms (11x).

The README documents that local file parsing accepts raw bytes from any file-like object. A minimal example for daily bars is:

from tdxrs import DailyBarReader

reader = DailyBarReader(coefficient=0.01)
df = reader.to_dataframe(open("600519.day", "rb").read())

The output DataFrame has columns for date, open, high, low, close, amount, and volume, plus year, month, and day components. The coefficient parameter scales the raw integer price values.

For high-performance tuple output, the README notes that tuple mode is 40 to 60 percent faster than dict mode, at the cost of positional rather than named access.

Client-Side Dividend Adjustment and the fq Parameter

TDX servers return unadjusted raw price data. The standard practice in Chinese A-share analysis is to apply forward adjustment (qian fuquan) or backward adjustment (hou fuquan) to correct historical prices for stock splits, dividends, and rights offerings. tdxrs performs this adjustment on the client side.

The README describes the adjustment algorithm as implementing the standard Chinese A-share dividend correction formula, supporting simultaneous handling of cash dividends, stock dividends, rights offers, and share consolidations. An automatic backfill mechanism using a context_bars parameter fills in early adjustment events that fall before the requested data window. When fq=0 (the default), no adjustment is applied and there is no additional overhead.

The adjustment happens entirely within the Rust parsing layer before returning data to Python. This means the DataFrame or tuple the caller receives already contains adjusted prices, with no need for a post-processing step. The README shows the three adjustment modes in a single code example using FQ_QFQ for forward adjustment, FQ_HFQ for backward adjustment, and FQ_NONE for raw unadjusted data passed as the fq keyword argument to get_security_bars.

Rate Limiting, CLI, and Batch Download

The library includes built-in rate limiting that adapts to market session phase. During trading hours (9:30 to 15:00) the default is 15 requests per second per connection; during pre- and post-market the limit is 30 per second, and during closed hours it is 60 per second. The README shows the rate limit auto-detection and manual override:

client.auto_detect_phase()
client.set_phase("trading")

The README notes that a connection pool of four connections multiplies the effective throughput fourfold. Bulk quote requests are capped at 60 symbols per call; the library truncates silently if that limit is exceeded. The set_phase method accepts the string values "trading", "prepost", and "closed" corresponding to the three session types.

The package also installs a command-line tool for ad-hoc queries:

tdxrs quote 600519,000858
tdxrs bars 600519 --count 30 --fq 1
tdxrs download --market sh --category daily
tdxrs servers

The downloader supports incremental updates and resume for interrupted downloads, distributing requests across multiple TDX servers automatically.

Limitations and How tdxrs Compares to tdxpy

tdxrs is a drop-in replacement only for code that imports from tdxpy. It does not extend the data sources beyond what TDX servers provide. Developers who need Shanghai Stock Exchange official feeds, Wind data, or international exchange data have to look elsewhere regardless of parsing speed.

Windows users targeting the x86_64-pc-windows-gnu toolchain must install MSYS2 dlltool before building from source. The README points to docs/INSTALL.md for the steps. The x86_64-pc-windows-msvc toolchain does not have this requirement, but the README directs Windows users to the install document without specifying which toolchain is preferred.

The library requires Python 3.11 or newer. Projects that must support Python 3.9 or 3.10 cannot use tdxrs at all and must stay on tdxpy.

The direct alternative is tdxpy (pytdx), the pure-Python library whose API tdxrs replicates. tdxpy runs on a wider range of Python versions and requires no compiled extension, which simplifies deployment on platforms where building native extensions is inconvenient. The trade-off is local file parsing speed: for small or infrequent queries the difference is immaterial, but bulk historical data processing is where tdxrs's speed advantage becomes significant.

tdxrs is licensed under MIT. The repository had its last push on 2026-09-15.

Editorial conclusion

tdxrs is the right choice for Python developers who already use tdxpy to parse large TDX local file datasets and need faster throughput without changing their code. The API compatibility means migration is largely a dependency swap. It is not the right choice for anyone who needs non-TDX data sources, real-time websocket feeds, or Python below 3.11. Windows users on x86_64-pc-windows-gnu targets must install MSYS2 dlltool before the build succeeds, as the README documents in docs/INSTALL.md. Verify that pip install tdxrs completes cleanly in your target environment before building any production pipeline around it.

Frequently asked questions

Official sources

1. Issues
2. jiangtaovan/tdxrs on GitHub
3. License: MIT
4. README