Metadata-Version: 2.4
Name: tdx-cli
Version: 0.1.3
Summary: 通达信数据命令行工具：原生 TDX 协议，K线/行情/分笔/F10/板块/扩展行情，table/json/csv/parquet 输出
Keywords: tdx,tongdaxin,stock,quote,kline,cli,market-data
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=25.0.1
Requires-Dist: typer>=0.27.1
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/qiansheng/tdx-cli
Project-URL: Repository, https://github.com/qiansheng/tdx-cli
Project-URL: Issues, https://github.com/qiansheng/tdx-cli/issues
Description-Content-Type: text/markdown

# tdx-cli

通达信数据命令行工具与 Python 库。基于原生 TDX 协议（标准行情/板块文件/扩展行情），零第三方行情依赖。

## 安装

    # CLI 工具（推荐 uv 或 pipx）
    uv tool install tdx-cli
    pipx install tdx-cli

    # 作为 Python 库
    uv add tdx-cli
    pip install tdx-cli

要求 Python >= 3.13。

## CLI 快速开始

    tdx-cli --help

    # K线（前复权日K，CSV 落盘）
    tdx-cli kline 600519 --adjust qfq --format csv -o moutai.csv

    # 实时行情（管道中自动输出 JSON）
    tdx-cli quote 600519 000001 | jq .

    # 历史逐笔
    tdx-cli trades 600519 --date 20260713

    # 板块成分
    tdx-cli blocks industry

    # 港股（扩展行情）
    tdx-cli ex-quote 31 00700

## 命令组

| 组 | 命令 |
|---|---|
| K线 | kline / minute / minutes / minute-history / index-bars / auction |
| 行情 | quote / securities / stock-count |
| 分笔 | trades |
| F10/财务 | f10 / f10-categories / f10-content / finance / xdxr / xdxr-all |
| 板块 | blocks / block / special-blocks / industry-assignments / stock-stats / stock-stats2 / ipo-subscriptions / index-definitions / block-aliases |
| 文件 | report-file / zhb-files |
| 扩展行情 | ex-markets / ex-count / ex-instruments / ex-quote / ex-quote-list / ex-bars / ex-bars-range / ex-minute / ex-trades |

## 输出格式

`--format table/json/csv/parquet`（默认 table；管道场景自动转 json，显式 `--format` 不降级）。

`-o` 支持按后缀（.json/.csv/.parquet）推断格式；parquet 必须配 `-o`。

退出码：`0` 成功；`1` 协议/数据错误；`2` 用法错误或连接失败。

## Python 库用法

核心客户端 `TdxClient`，上下文管理器自动建连与关闭：

```python
from tdx_cli import TdxClient, Frequency, Market, determine_market

with TdxClient() as client:
    # K线（不复权/前复权/后复权）
    bars = client.kline("600519", frequency=Frequency.DAY, count=100, adjustment="qfq")

    # 实时五档行情
    quote = client.quote("600519")          # pd.Series
    quotes = client.quotes(["600519", "000001"])  # pd.DataFrame

    # 当日分时 / 历史分时 / 逐笔
    minute = client.minute("600519")                       # pd.DataFrame
    history = client.minutes("600519", date="20260713")
    trades = client.trades("600519", date="20260713")

    # F10 / 财务 / 除权
    profile = client.f10("600519", name="公司简介")          # dict
    xdxr = client.xdxr("600519")                            # pd.DataFrame

    # 板块（懒连接文件协议）
    blocks = client.blocks("industry")                      # list[TdxBlock]

    # 扩展行情：港股/期货（懒连接 ExHq）
    hk_quote = client.ex_quote(31, "00700")
```

代码与市场判断工具：

```python
from tdx_cli import classify_security, determine_market, determine_exchange, is_etf

determine_market("600519")      # 1（Market.SH）
determine_exchange("000001")    # "SZ"
classify_security("600519")     # "STOCK"
classify_security("000001")     # "STOCK"（深市）
classify_security("980515")    # "INDEX"
is_etf("510300")                # True
```

### 主要模块

| 模块 | 内容 |
|---|---|
| `tdx_cli` | 顶层导出：`TdxClient`、`Frequency`、`Market`、`SecurityType`、`ExFrequency`、代码工具函数 |
| `tdx_cli.tdx` | 统一客户端（40+ 方法：K线/行情/分笔/F10/板块/扩展行情） |
| `tdx_cli.tdx_standard` | 标准行情底层 `TdxStandardClient`、`normalize_code` |
| `tdx_cli.tdx_exhq` | 扩展行情 `ExHqClient`（期货/港股/外盘） |
| `tdx_cli.tdx_blocks` | 文件协议 `TdxProtocolClient`（板块/报表文件） |
| `tdx_cli.cli.output` | `emit`/`Format`：DataFrame/数据类 → table/json/csv/parquet |

### 连接说明

- 标准行情：`with TdxClient()` 或 `connect()` 时建立，内置多节点故障切换
- 板块文件协议、扩展行情：首次调用对应方法时懒连接，`close()` 统一关闭
- 需要显式指定服务器时用底层客户端构造注入：

```python
from tdx_cli import TdxClient
from tdx_cli.tdx_standard import TdxStandardClient

standard = TdxStandardClient(servers=[("60.191.117.167", 7709)])
standard.connect()
with TdxClient(standard_client=standard) as client:
    ...
```

## 配置

`~/.tdx-cli/config.toml`（可选）：

    [standard]
    servers = ["60.191.117.167:7709"]

    [blocks]
    servers = ["124.71.187.122:7709"]

    [extended]
    servers = ["112.74.214.43:7727"]

    [output]
    format = "table"

`--host/--port` 命令行优先级最高（指定后仅连该节点）。

## 开发

    uv sync
    uv run pytest

发布：`uv build && twine upload dist/tdx_cli-<version>*`

## License

MIT
