tdxlocal 0.1.0__tar.gz

tdxlocal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mengyiheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tdxlocal-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: tdxlocal
+Version: 0.1.0
+Summary: 通达信本地二进制行情数据（.day / .lc1 / .lc5）读写库，零依赖
+Author: mengyiheng
+License: MIT
+Keywords: tdx,tongdaxin,stock,kline,quant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Dynamic: license-file
+
+<p align="center"><img src="assets/cover.png" alt="tdxdata" width="720"/></p>
+
+# tdxdata — 通达信本地行情数据读写库
+
+读取和生成通达信（TDX）本地二进制 K 线文件：**`.day` 日线**、**`.lc1` 1 分钟线**、**`.lc5` 5 分钟线**。
+
+- 🪶 **零第三方依赖**（pandas 可选）
+- 📖 **读取**：一行代码解析为 Python 对象列表
+- ✍️ **生成 / 增量更新**：与通达信客户端落盘格式逐字节一致，可被客户端直接识别
+- 🗂 **vipdoc 目录约定**：按证券代码自动定位文件、自动推断市场（sh/sz/bj）
+- 🖥 **命令行**：`tdxdata day <vipdoc> 000001 out.csv` 一键导出 CSV
+
+## 安装
+
+```bash
+pip install tdxlocal          # 含 pandas 支持
+pip install tdxlocal --no-deps  # 纯标准库
+```
+
+## 文件格式
+
+两类文件均为 **每条记录 32 字节、小端 `<IIIIIfII>`**，但日期字段编码不同：
+
+| 字段 | 日线 `.day` | 分钟线 `.lc1/.lc5` |
+|---|---|---|
+| 0 | 日期 `YYYYMMDD` 明文 | 紧凑日期 `(year-2004)*2048 + month*100 + day` |
+| 4 | 开*100 | 时间 `hour*60 + minute` |
+| 8–20 | 高/低/收 *100 | 高/低/收/开 *100 |
+| 24 | 成交额 float32（元） | 成交额 float32（元） |
+| 28 | 成交量（手）+ 保留字段 | 成交量（手） |
+
+## 快速开始
+
+```python
+from tdxdata import read_day, read_minute, write_day, DayBar
+
+# 读取日线
+bars = read_day(r"D:\new_tdx64\vipdoc\sh\lday\sh000001.day")
+print(bars[-1])   # DayBar(date=20260116, open=..., high=..., ...)
+
+# 读取 1 分钟线
+mins = read_minute(r"D:\new_tdx\vipdoc\sh\minline\sh999999.lc1")
+
+# 生成日线文件（通达信可直接打开）
+write_day("my.day", [DayBar(20260116, 10.0, 10.5, 9.9, 10.2, 1.2e8, 123456)])
+
+# 增量更新（追加模式，与通达信盘中落盘一致）
+write_day(path, [DayBar(...)], append=True)
+```
+
+### vipdoc 便捷入口
+
+```python
+from tdxdata import VipdocStore
+
+store = VipdocStore(r"D:\new_tdx64\vipdoc")
+bars = store.read("600519", "day")    # 自动定位 sh/lday/sh600519.day
+store.update("600519", [DayBar(...)]) # 增量追加
+```
+
+### 可选：输出 pandas DataFrame
+
+```python
+import pandas as pd
+from dataclasses import asdict
+from tdxdata import read_day
+
+df = pd.DataFrame([asdict(b) for b in read_day(path)])
+```
+
+### 命令行
+
+```bash
+tdxdata day  D:\new_tdx64\vipdoc 000001 sh000001.csv
+tdxdata lc1  D:\new_tdx\vipdoc 999999 sh999999.csv
+python -m tdxdata day D:\new_tdx64\vipdoc\sh\lday\sh000001.day out.csv
+```
+
+## 运行测试
+
+```bash
+pip install -e . pytest
+pytest
+```
+
+测试自带合成数据做逐字节往返校验；若本机存在 `D:\new_tdx64\vipdoc`，会自动附加真实数据冒烟测试（缺失则跳过）。
+
+## 免责声明
+
+本项目仅读取/生成**本地已有**的通达信数据文件，不提供任何行情数据，不构成任何投资建议。数据仅供学习与量化研究使用，不作为实盘交易依据，使用前请[阅读完整免责声明](DISCLAIMER.md)。**投资有风险，入市需谨慎。**
+
+## 量化相关定制需求
+
+作者承接基于本库及量化研究场景的**定制开发**，包括但不限于：
+
+| 方向 | 示例 |
+|---|---|
+| 📈 数据扩展 | `.zst`/`.档位` 等其他 TDX 文件解析、盘中增量落盘监控、CSV/parquet/SQLite 批量导出 |
+| 🐍 量化工具链 | pandas/Polars 适配层、多周期重采样（1m→5m→30m→日线）、复权因子处理 |
+| 🤖 策略工程 | 回测框架对接、实盘信号监控脚本、通达信客户端联动（公式批量调用/行情订阅） |
+| 🛠 私有部署 | 数据管线搭建、性能优化（批量解析全市场文件）、CI/自动发版 |
+
+**联系合作**：[Gitee Issues](https://gitee.com/mengyiheng/tdxdata/issues) 提需求描述，或通过 [Gitee 私信](https://gitee.com/mengyiheng) 联系。复杂需求请附上：数据量级、时效要求（日终/盘中）、期望交付形式。
+
+## License
+
+MIT

tdxlocal-0.1.0/README.md

@@ -0,0 +1,107 @@
+<p align="center"><img src="assets/cover.png" alt="tdxdata" width="720"/></p>
+
+# tdxdata — 通达信本地行情数据读写库
+
+读取和生成通达信（TDX）本地二进制 K 线文件：**`.day` 日线**、**`.lc1` 1 分钟线**、**`.lc5` 5 分钟线**。
+
+- 🪶 **零第三方依赖**（pandas 可选）
+- 📖 **读取**：一行代码解析为 Python 对象列表
+- ✍️ **生成 / 增量更新**：与通达信客户端落盘格式逐字节一致，可被客户端直接识别
+- 🗂 **vipdoc 目录约定**：按证券代码自动定位文件、自动推断市场（sh/sz/bj）
+- 🖥 **命令行**：`tdxdata day <vipdoc> 000001 out.csv` 一键导出 CSV
+
+## 安装
+
+```bash
+pip install tdxlocal          # 含 pandas 支持
+pip install tdxlocal --no-deps  # 纯标准库
+```
+
+## 文件格式
+
+两类文件均为 **每条记录 32 字节、小端 `<IIIIIfII>`**，但日期字段编码不同：
+
+| 字段 | 日线 `.day` | 分钟线 `.lc1/.lc5` |
+|---|---|---|
+| 0 | 日期 `YYYYMMDD` 明文 | 紧凑日期 `(year-2004)*2048 + month*100 + day` |
+| 4 | 开*100 | 时间 `hour*60 + minute` |
+| 8–20 | 高/低/收 *100 | 高/低/收/开 *100 |
+| 24 | 成交额 float32（元） | 成交额 float32（元） |
+| 28 | 成交量（手）+ 保留字段 | 成交量（手） |
+
+## 快速开始
+
+```python
+from tdxdata import read_day, read_minute, write_day, DayBar
+
+# 读取日线
+bars = read_day(r"D:\new_tdx64\vipdoc\sh\lday\sh000001.day")
+print(bars[-1])   # DayBar(date=20260116, open=..., high=..., ...)
+
+# 读取 1 分钟线
+mins = read_minute(r"D:\new_tdx\vipdoc\sh\minline\sh999999.lc1")
+
+# 生成日线文件（通达信可直接打开）
+write_day("my.day", [DayBar(20260116, 10.0, 10.5, 9.9, 10.2, 1.2e8, 123456)])
+
+# 增量更新（追加模式，与通达信盘中落盘一致）
+write_day(path, [DayBar(...)], append=True)
+```
+
+### vipdoc 便捷入口
+
+```python
+from tdxdata import VipdocStore
+
+store = VipdocStore(r"D:\new_tdx64\vipdoc")
+bars = store.read("600519", "day")    # 自动定位 sh/lday/sh600519.day
+store.update("600519", [DayBar(...)]) # 增量追加
+```
+
+### 可选：输出 pandas DataFrame
+
+```python
+import pandas as pd
+from dataclasses import asdict
+from tdxdata import read_day
+
+df = pd.DataFrame([asdict(b) for b in read_day(path)])
+```
+
+### 命令行
+
+```bash
+tdxdata day  D:\new_tdx64\vipdoc 000001 sh000001.csv
+tdxdata lc1  D:\new_tdx\vipdoc 999999 sh999999.csv
+python -m tdxdata day D:\new_tdx64\vipdoc\sh\lday\sh000001.day out.csv
+```
+
+## 运行测试
+
+```bash
+pip install -e . pytest
+pytest
+```
+
+测试自带合成数据做逐字节往返校验；若本机存在 `D:\new_tdx64\vipdoc`，会自动附加真实数据冒烟测试（缺失则跳过）。
+
+## 免责声明
+
+本项目仅读取/生成**本地已有**的通达信数据文件，不提供任何行情数据，不构成任何投资建议。数据仅供学习与量化研究使用，不作为实盘交易依据，使用前请[阅读完整免责声明](DISCLAIMER.md)。**投资有风险，入市需谨慎。**
+
+## 量化相关定制需求
+
+作者承接基于本库及量化研究场景的**定制开发**，包括但不限于：
+
+| 方向 | 示例 |
+|---|---|
+| 📈 数据扩展 | `.zst`/`.档位` 等其他 TDX 文件解析、盘中增量落盘监控、CSV/parquet/SQLite 批量导出 |
+| 🐍 量化工具链 | pandas/Polars 适配层、多周期重采样（1m→5m→30m→日线）、复权因子处理 |
+| 🤖 策略工程 | 回测框架对接、实盘信号监控脚本、通达信客户端联动（公式批量调用/行情订阅） |
+| 🛠 私有部署 | 数据管线搭建、性能优化（批量解析全市场文件）、CI/自动发版 |
+
+**联系合作**：[Gitee Issues](https://gitee.com/mengyiheng/tdxdata/issues) 提需求描述，或通过 [Gitee 私信](https://gitee.com/mengyiheng) 联系。复杂需求请附上：数据量级、时效要求（日终/盘中）、期望交付形式。
+
+## License
+
+MIT

tdxlocal-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tdxlocal"
+version = "0.1.0"
+description = "通达信本地二进制行情数据（.day / .lc1 / .lc5）读写库，零依赖"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "mengyiheng" }]
+keywords = ["tdx", "tongdaxin", "stock", "kline", "quant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas"]
+
+[project.scripts]
+tdxdata = "tdxdata.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tdxlocal-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tdxlocal-0.1.0/src/tdxdata/__init__.py

@@ -0,0 +1,27 @@
+"""tdxdata — 读写通达信本地二进制行情数据（.day / .lc1 / .lc5）。
+
+零第三方依赖；提供 pandas 支持时可选输出 DataFrame。
+
+免责声明：本库仅处理本地已有数据文件，不提供任何行情数据，不构成投资建议。
+数据仅供学习与量化研究使用，详见项目根目录 DISCLAIMER.md。
+
+快速开始::
+
+    from tdxdata import read_day, read_minute
+
+    bars = read_day(r"D:\\new_tdx64\\vipdoc\\sh\\lday\\sh000001.day")
+    mins = read_minute(r"D:\\new_tdx\\vipdoc\\sh\\minline\\sh999999.lc1")
+"""
+
+from .day import DayBar, read_day, write_day
+from .minute import MinuteBar, read_minute, write_minute
+from .vipdoc import VipdocStore, find_bar_file
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DayBar", "read_day", "write_day",
+    "MinuteBar", "read_minute", "write_minute",
+    "VipdocStore", "find_bar_file",
+    "__version__",
+]

tdxlocal-0.1.0/src/tdxdata/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

tdxlocal-0.1.0/src/tdxdata/cli.py

@@ -0,0 +1,44 @@
+"""命令行工具：python -m tdxdata <day|lc1|lc5> <文件或数据目录> <代码> [输出.csv]"""
+
+from __future__ import annotations
+
+import csv
+import sys
+from pathlib import Path
+
+from .day import read_day
+from .minute import read_minute
+from .vipdoc import find_bar_file
+
+
+def _dump(rows, header, out_path: str) -> None:
+    with open(out_path, "w", newline="", encoding="utf-8-sig") as f:
+        w = csv.writer(f)
+        w.writerow(header)
+        w.writerows([getattr(r, k) for k in header] for r in rows)
+    print(f"[tdxdata] {len(rows)} 条 -> {out_path}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) < 2:
+        print(__doc__)
+        return 1
+    kind, target = argv[0].lower(), argv[1]
+    code = argv[2] if len(argv) > 2 else None
+    out = argv[3] if len(argv) > 3 else "tdx_export.csv"
+
+    if kind == "day":
+        path = Path(target) if Path(target).is_file() else find_bar_file(target, code or "", "day")
+        _dump(read_day(path), ["date", "open", "high", "low", "close", "amount", "vol"], out)
+    elif kind in ("lc1", "lc5"):
+        path = Path(target) if Path(target).is_file() else find_bar_file(target, code or "", kind)
+        _dump(read_minute(path), ["datetime", "open", "high", "low", "close", "amount", "vol"], out)
+    else:
+        print(f"未知类型: {kind}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tdxlocal-0.1.0/src/tdxdata/day.py

@@ -0,0 +1,60 @@
+"""通达信日线文件（vipdoc/<market>/lday/*.day）读写。
+
+文件格式：每条记录 32 字节，小端 ``<IIIIIfII>``：
+
+======  ========  ============================
+偏移    类型      含义
+======  ========  ============================
+0       uint32    日期 YYYYMMDD
+4       uint32    开盘价 * 100
+8       uint32    最高价 * 100
+12      uint32    最低价 * 100
+16      uint32    收盘价 * 100
+20      float32   成交额（元）
+24      uint32    成交量（手）
+28      uint32    保留字段（通常为 0）
+======  ========  ============================
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Iterable, List
+
+from .records import DayBar
+
+_STRUCT = struct.Struct("<IIIIIfII")
+_PRICE_SCALE = 100.0
+
+
+def read_day(path: str | Path) -> List[DayBar]:
+    """读取 .day 文件，按文件顺序返回 K 线列表。"""
+    data = Path(path).read_bytes()
+    n = len(data) // _STRUCT.size
+    bars: List[DayBar] = []
+    for i in range(n):
+        date, o, h, l, c, amount, vol, _ = _STRUCT.unpack_from(data, i * _STRUCT.size)
+        bars.append(DayBar(date, o / _PRICE_SCALE, h / _PRICE_SCALE,
+                           l / _PRICE_SCALE, c / _PRICE_SCALE,
+                           round(amount, 2), float(vol)))
+    return bars
+
+
+def write_day(path: str | Path, bars: Iterable[DayBar], *, append: bool = False) -> int:
+    """把 K 线序列写入 .day 文件，返回写入条数。
+
+    append=True 时追加到文件末尾（用于增量更新，与通达信自身行为一致）。
+    """
+    payload = bytearray()
+    count = 0
+    for b in bars:
+        payload += _STRUCT.pack(
+            int(b.date), round(b.open * _PRICE_SCALE), round(b.high * _PRICE_SCALE),
+            round(b.low * _PRICE_SCALE), round(b.close * _PRICE_SCALE),
+            float(b.amount), int(b.vol), 0)
+        count += 1
+    mode = "ab" if append else "wb"
+    with open(path, mode) as f:
+        f.write(payload)
+    return count

tdxlocal-0.1.0/src/tdxdata/minute.py

@@ -0,0 +1,83 @@
+"""通达信分钟线文件（vipdoc/<market>/minline/*.lc1 | *.lc5）读写。
+
+文件格式：每条记录 32 字节，小端 ``<IIIIIfII>``，但日期字段是**紧凑编码**：
+
+======  ========  ====================================================
+偏移    类型      含义
+======  ========  ====================================================
+0       uint32    紧凑日期：``year = d // 2048 + 2004``；
+                  ``month = (d % 2048) // 100``；``day = (d % 2048) % 100``
+4       uint32    时间：``hour = t // 60``；``minute = t % 60``
+8       uint32    开盘价 * 100
+12      uint32    最高价 * 100
+16      uint32    最低价 * 100
+20      uint32    收盘价 * 100
+24      float32   成交额（元）
+28      uint32    成交量（手）
+======  ========  ====================================================
+
+注意与日线不同：分钟线没有保留字段，最后一个 uint32 就是成交量。
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Iterable, List
+
+from .records import MinuteBar
+
+_STRUCT = struct.Struct("<IIIIIIfI")
+_PRICE_SCALE = 100.0
+_EPOCH_YEAR = 2004
+
+
+def _unpack_date(raw: int) -> tuple[int, int, int]:
+    rest = raw % 2048
+    return raw // 2048 + _EPOCH_YEAR, rest // 100, rest % 100
+
+
+def _pack_date(year: int, month: int, day: int) -> int:
+    return (year - _EPOCH_YEAR) * 2048 + month * 100 + day
+
+
+def read_minute(path: str | Path) -> List[MinuteBar]:
+    """读取 .lc1 / .lc5 文件，按文件顺序返回分钟 K 线列表。"""
+    data = Path(path).read_bytes()
+    n = len(data) // _STRUCT.size
+    bars: List[MinuteBar] = []
+    for i in range(n):
+        raw_date, raw_time, o, h, l, c, amount, vol = _STRUCT.unpack_from(data, i * _STRUCT.size)
+        year, month, day = _unpack_date(raw_date)
+        hour, minute = divmod(raw_time, 60)
+        bars.append(MinuteBar(
+            f"{year:04d}-{month:02d}-{day:02d} {hour:02d}:{minute:02d}",
+            o / _PRICE_SCALE, h / _PRICE_SCALE, l / _PRICE_SCALE, c / _PRICE_SCALE,
+            round(amount, 2), float(vol)))
+    return bars
+
+
+def write_minute(path: str | Path, bars: Iterable[MinuteBar], *, append: bool = False) -> int:
+    """把分钟 K 线序列写入 .lc1 / .lc5 文件，返回写入条数。
+
+    ``datetime`` 接受 ``"YYYY-MM-DD HH:MM"`` 或 ``"YYYYMMDD HHMM"`` 两种形式。
+    """
+    payload = bytearray()
+    count = 0
+    for b in bars:
+        parts = "".join(ch if ch.isdigit() else " " for ch in b.datetime).split()
+        if len(parts) >= 5:                      # "2026-01-15 09:31"
+            year, month, day, hour, minute = (int(x) for x in parts[:5])
+        else:                                    # "20260116 1405"
+            year, month, day = int(parts[0][:4]), int(parts[0][4:6]), int(parts[0][6:8])
+            hour, minute = int(parts[1][:2]), int(parts[1][2:4])
+        payload += _STRUCT.pack(
+            _pack_date(year, month, day), hour * 60 + minute,
+            round(b.open * _PRICE_SCALE), round(b.high * _PRICE_SCALE),
+            round(b.low * _PRICE_SCALE), round(b.close * _PRICE_SCALE),
+            float(b.amount), int(b.vol))
+        count += 1
+    mode = "ab" if append else "wb"
+    with open(path, mode) as f:
+        f.write(payload)
+    return count

tdxlocal-0.1.0/src/tdxdata/records.py

@@ -0,0 +1,37 @@
+"""基础 K 线记录结构。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class DayBar:
+    """日线一根 K 线。
+
+    amount 单位为元，vol 单位为手（与通达信原始文件一致）。
+    """
+
+    date: int        # YYYYMMDD
+    open: float
+    high: float
+    low: float
+    close: float
+    amount: float
+    vol: float
+
+
+@dataclass(frozen=True, slots=True)
+class MinuteBar:
+    """分钟线一根 K 线（lc1 = 1 分钟，lc5 = 5 分钟）。
+
+    amount 单位为元，vol 单位为手。
+    """
+
+    datetime: str    # "YYYY-MM-DD HH:MM"
+    open: float
+    high: float
+    low: float
+    close: float
+    amount: float
+    vol: float

tdxlocal-0.1.0/src/tdxdata/vipdoc.py

@@ -0,0 +1,57 @@
+"""按通达信 vipdoc 目录约定定位数据文件。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_MARKET_BY_PREFIX = {"sh": 1, "sz": 0, "bj": 2}
+
+
+def market_of(code: str) -> str:
+    """根据 6 位代码推断市场（sh/sz/bj）。"""
+    if code.startswith(("6", "5", "9")):
+        return "sh"
+    if code.startswith(("4", "8")):
+        return "bj"
+    return "sz"
+
+
+def find_bar_file(vipdoc: str | Path, code: str, kind: str) -> Path:
+    """在 vipdoc 目录中定位单个证券的数据文件。
+
+    kind: ``"day"`` -> lday/*.day；``"lc1"``/``"lc5"`` -> minline/*.lc1|*.lc5
+    """
+    kind = kind.lower()
+    market = market_of(code)
+    if kind == "day":
+        p = Path(vipdoc) / market / "lday" / f"{market}{code}.day"
+    elif kind in ("lc1", "lc5", "1", "5", "min1", "min5"):
+        suffix = "lc1" if kind in ("lc1", "1", "min1") else "lc5"
+        p = Path(vipdoc) / market / "minline" / f"{market}{code}.{suffix}"
+    else:
+        raise ValueError(f"未知类型: {kind!r}（支持 day / lc1 / lc5）")
+    if not p.exists():
+        raise FileNotFoundError(f"未找到数据文件: {p}")
+    return p
+
+
+class VipdocStore:
+    """vipdoc 目录的便捷入口，自动识别市场前缀并读写。"""
+
+    def __init__(self, vipdoc: str | Path):
+        self.vipdoc = Path(vipdoc)
+
+    def read(self, code: str, kind: str = "day"):
+        """按代码读取 K 线。kind: day / lc1 / lc5。"""
+        path = find_bar_file(self.vipdoc, code, kind)
+        from . import day as _day, minute as _minute
+
+        return _day.read_day(path) if kind.lower() == "day" else _minute.read_minute(path)
+
+    def update(self, code: str, bars, kind: str = "day") -> int:
+        """增量追加 K 线（与通达信盘中落盘方式一致）。"""
+        path = find_bar_file(self.vipdoc, code, kind)
+        from . import day as _day, minute as _minute
+
+        writer = _day.write_day if kind.lower() == "day" else _minute.write_minute
+        return writer(path, bars, append=True)

tdxlocal-0.1.0/src/tdxlocal.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: tdxlocal
+Version: 0.1.0
+Summary: 通达信本地二进制行情数据（.day / .lc1 / .lc5）读写库，零依赖
+Author: mengyiheng
+License: MIT
+Keywords: tdx,tongdaxin,stock,kline,quant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Dynamic: license-file
+
+<p align="center"><img src="assets/cover.png" alt="tdxdata" width="720"/></p>
+
+# tdxdata — 通达信本地行情数据读写库
+
+读取和生成通达信（TDX）本地二进制 K 线文件：**`.day` 日线**、**`.lc1` 1 分钟线**、**`.lc5` 5 分钟线**。
+
+- 🪶 **零第三方依赖**（pandas 可选）
+- 📖 **读取**：一行代码解析为 Python 对象列表
+- ✍️ **生成 / 增量更新**：与通达信客户端落盘格式逐字节一致，可被客户端直接识别
+- 🗂 **vipdoc 目录约定**：按证券代码自动定位文件、自动推断市场（sh/sz/bj）
+- 🖥 **命令行**：`tdxdata day <vipdoc> 000001 out.csv` 一键导出 CSV
+
+## 安装
+
+```bash
+pip install tdxlocal          # 含 pandas 支持
+pip install tdxlocal --no-deps  # 纯标准库
+```
+
+## 文件格式
+
+两类文件均为 **每条记录 32 字节、小端 `<IIIIIfII>`**，但日期字段编码不同：
+
+| 字段 | 日线 `.day` | 分钟线 `.lc1/.lc5` |
+|---|---|---|
+| 0 | 日期 `YYYYMMDD` 明文 | 紧凑日期 `(year-2004)*2048 + month*100 + day` |
+| 4 | 开*100 | 时间 `hour*60 + minute` |
+| 8–20 | 高/低/收 *100 | 高/低/收/开 *100 |
+| 24 | 成交额 float32（元） | 成交额 float32（元） |
+| 28 | 成交量（手）+ 保留字段 | 成交量（手） |
+
+## 快速开始
+
+```python
+from tdxdata import read_day, read_minute, write_day, DayBar
+
+# 读取日线
+bars = read_day(r"D:\new_tdx64\vipdoc\sh\lday\sh000001.day")
+print(bars[-1])   # DayBar(date=20260116, open=..., high=..., ...)
+
+# 读取 1 分钟线
+mins = read_minute(r"D:\new_tdx\vipdoc\sh\minline\sh999999.lc1")
+
+# 生成日线文件（通达信可直接打开）
+write_day("my.day", [DayBar(20260116, 10.0, 10.5, 9.9, 10.2, 1.2e8, 123456)])
+
+# 增量更新（追加模式，与通达信盘中落盘一致）
+write_day(path, [DayBar(...)], append=True)
+```
+
+### vipdoc 便捷入口
+
+```python
+from tdxdata import VipdocStore
+
+store = VipdocStore(r"D:\new_tdx64\vipdoc")
+bars = store.read("600519", "day")    # 自动定位 sh/lday/sh600519.day
+store.update("600519", [DayBar(...)]) # 增量追加
+```
+
+### 可选：输出 pandas DataFrame
+
+```python
+import pandas as pd
+from dataclasses import asdict
+from tdxdata import read_day
+
+df = pd.DataFrame([asdict(b) for b in read_day(path)])
+```
+
+### 命令行
+
+```bash
+tdxdata day  D:\new_tdx64\vipdoc 000001 sh000001.csv
+tdxdata lc1  D:\new_tdx\vipdoc 999999 sh999999.csv
+python -m tdxdata day D:\new_tdx64\vipdoc\sh\lday\sh000001.day out.csv
+```
+
+## 运行测试
+
+```bash
+pip install -e . pytest
+pytest
+```
+
+测试自带合成数据做逐字节往返校验；若本机存在 `D:\new_tdx64\vipdoc`，会自动附加真实数据冒烟测试（缺失则跳过）。
+
+## 免责声明
+
+本项目仅读取/生成**本地已有**的通达信数据文件，不提供任何行情数据，不构成任何投资建议。数据仅供学习与量化研究使用，不作为实盘交易依据，使用前请[阅读完整免责声明](DISCLAIMER.md)。**投资有风险，入市需谨慎。**
+
+## 量化相关定制需求
+
+作者承接基于本库及量化研究场景的**定制开发**，包括但不限于：
+
+| 方向 | 示例 |
+|---|---|
+| 📈 数据扩展 | `.zst`/`.档位` 等其他 TDX 文件解析、盘中增量落盘监控、CSV/parquet/SQLite 批量导出 |
+| 🐍 量化工具链 | pandas/Polars 适配层、多周期重采样（1m→5m→30m→日线）、复权因子处理 |
+| 🤖 策略工程 | 回测框架对接、实盘信号监控脚本、通达信客户端联动（公式批量调用/行情订阅） |
+| 🛠 私有部署 | 数据管线搭建、性能优化（批量解析全市场文件）、CI/自动发版 |
+
+**联系合作**：[Gitee Issues](https://gitee.com/mengyiheng/tdxdata/issues) 提需求描述，或通过 [Gitee 私信](https://gitee.com/mengyiheng) 联系。复杂需求请附上：数据量级、时效要求（日终/盘中）、期望交付形式。
+
+## License
+
+MIT

tdxlocal-0.1.0/src/tdxlocal.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/tdxdata/__init__.py
+src/tdxdata/__main__.py
+src/tdxdata/cli.py
+src/tdxdata/day.py
+src/tdxdata/minute.py
+src/tdxdata/records.py
+src/tdxdata/vipdoc.py
+src/tdxlocal.egg-info/PKG-INFO
+src/tdxlocal.egg-info/SOURCES.txt
+src/tdxlocal.egg-info/dependency_links.txt
+src/tdxlocal.egg-info/entry_points.txt
+src/tdxlocal.egg-info/requires.txt
+src/tdxlocal.egg-info/top_level.txt
+tests/test_tdxdata.py

tdxlocal-0.1.0/src/tdxlocal.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tdxlocal-0.1.0/src/tdxlocal.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tdxdata = tdxdata.cli:main

tdxlocal-0.1.0/src/tdxlocal.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[pandas]
+pandas

tdxlocal-0.1.0/src/tdxlocal.egg-info/top_level.txt

@@ -0,0 +1 @@
+tdxdata

tdxlocal-0.1.0/tests/test_tdxdata.py

@@ -0,0 +1,97 @@
+import io
+import struct
+from dataclasses import asdict
+from pathlib import Path
+
+import pytest
+
+from tdxdata import DayBar, MinuteBar, read_day, read_minute, write_day, write_minute
+from tdxdata.vipdoc import market_of
+
+# ---------- 合成数据：逐字节往返 ----------
+
+def test_day_roundtrip(tmp_path):
+    bars = [
+        DayBar(20260115, 10.0, 10.5, 9.9, 10.2, 1.234e8, 123456),
+        DayBar(20260116, 10.2, 10.8, 10.1, 10.6, 9.876e7, 98765),
+    ]
+    p = tmp_path / "test.day"
+    assert write_day(p, bars) == 2
+    assert p.stat().st_size == 64
+
+    # 手工核对原始字节：第一条
+    raw = struct.unpack("<IIIIIfII", p.read_bytes()[:32])
+    assert raw[0] == 20260115
+    assert raw[1] == 1000 and raw[2] == 1050 and raw[3] == 990 and raw[4] == 1020
+    assert raw[6] == 123456
+
+    back = read_day(p)
+    assert back[0].date == 20260115
+    assert back[0].open == pytest.approx(10.0)
+    assert back[1].close == pytest.approx(10.6)
+    assert [asdict(b) for b in back][1]["vol"] == 98765
+
+
+def test_day_append(tmp_path):
+    p = tmp_path / "a.day"
+    write_day(p, [DayBar(20260101, 1, 1, 1, 1, 0, 1)])
+    write_day(p, [DayBar(20260102, 1, 1, 1, 1, 0, 2)], append=True)
+    assert len(read_day(p)) == 2
+
+
+def test_minute_roundtrip(tmp_path):
+    bars = [
+        MinuteBar("2026-01-15 09:31", 3.45, 3.5, 3.4, 3.48, 5e6, 1500),
+        MinuteBar("2026-01-15 09:32", 3.48, 3.52, 3.47, 3.5, 6e6, 1800),
+    ]
+    p = tmp_path / "test.lc5"
+    assert write_minute(p, bars) == 2
+    assert p.stat().st_size == 64
+
+    # 紧凑日期字段核对: (2026-2004)*2048 + 1*100 + 15
+    raw = struct.unpack("<IIIIIfII", p.read_bytes()[:32])
+    assert raw[0] == (2026 - 2004) * 2048 + 115
+    assert raw[1] == 9 * 60 + 31
+
+    back = read_minute(p)
+    assert back[0].datetime == "2026-01-15 09:31"
+    assert back[0].open == pytest.approx(3.45)
+    assert back[1].high == pytest.approx(3.52)
+
+
+def test_minute_datetime_alt_format(tmp_path):
+    p = tmp_path / "b.lc1"
+    write_minute(p, [MinuteBar("20260116 1405", 1, 1, 1, 1, 0, 1)])
+    assert read_minute(p)[0].datetime == "2026-01-16 14:05"
+
+
+def test_market_of():
+    assert market_of("600519") == "sh"
+    assert market_of("510300") == "sh"
+    assert market_of("000001") == "sz"
+    assert market_of("300750") == "sz"
+    assert market_of("830799") == "bj"
+
+
+# ---------- 真实数据冒烟（本机有通达信数据时） ----------
+
+REAL = Path(r"D:\new_tdx64\vipdoc\sh\lday\sh000001.day")
+
+
+@pytest.mark.skipif(not REAL.exists(), reason="本机无通达信日线数据")
+def test_real_day_file():
+    bars = read_day(REAL)
+    assert len(bars) == REAL.stat().st_size // 32
+    assert bars == sorted(bars, key=lambda b: b.date)
+    last = bars[-1]
+    assert 1990 <= last.date // 10000 <= 2100
+    assert last.low <= last.open <= last.high
+    assert last.low <= last.close <= last.high
+    # 写出再读回，逐条一致（金额 float32 有 ~7 位精度）
+    out = io.BytesIO()
+    p = Path("_)tmp_check.day")
+    try:
+        write_day(p, bars)
+        assert read_day(p) == bars
+    finally:
+        p.unlink(missing_ok=True)