feat: v1.1.0 - MAC protocol, CLI tool, extended markets, unified client

- Add MacClient/AsyncMacClient with full MAC protocol support (quotes, kline with adjustment, tick charts, transactions, boards, capital flow, auction, unusual, symbol info, server info) - Add MacExClient/AsyncMacExClient for extended markets (HK, US, futures) - Add UnifiedTdxClient auto-routing between A-share and extended markets - Add `easy-tdx` CLI tool with JSON default output, Agent-friendly - Add field bitmap protocol for custom quote field selection - Fix quote-list missing fields (default to BASIC+VOLUME preset) - Add config.py with centralized host management and auto-discovery - Add 50+ examples covering all APIs (01-20) - Rewrite README with CLI-first, Agent-friendly documentation - Bump version to 1.1.0 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-09-12 18:04:20 +08:00 · 2026-05-22 22:44:45 +08:00
parent 67a0415c38
commit 4820b4a049
108 changed files with 10345 additions and 932 deletions
@@ -1,4 +1,25 @@
-"""演示：获取公司信息目录与各个分类的详细内容。"""
+"""演示：获取公司信息目录与各个分类的详细内容。
+
+使用 TdxClient 标准协议客户端，分两步获取公司信息：
+  1. get_company_info_category() -- 获取公司信息目录（分类列表）
+  2. get_company_info_content() -- 根据目录中的 filename/start/length 读取具体内容
+
+get_company_info_category() 返回 CompanyInfoCategory DataFrame，列说明:
+  name      str     分类名称（如"最新提示"、"公司概况"、"财务分析"等）
+  filename  str     内容文件名（如 "600519.txt"）
+  start     int     内容在该文件中的起始偏移（字节）
+  length    int     内容长度（字节）
+
+公司信息常见分类:
+  最新提示、公司概况、财务分析、股本结构、股东研究、机构持股、
+  分红融资、高管治理、资金动向、资本运作、热点题材、公司公告、
+  公司报道、经营分析、行业分析、研报评级
+
+数据特点:
+  - 目录中每个分类对应同一 .txt 文件的不同偏移位置
+  - 内容为纯文本，长度从几百字节到数万字节不等
+  - 内容更新频率取决于上市公司公告发布节奏
+"""

 from easy_tdx import Market, TdxClient

@@ -60,3 +81,23 @@ with TdxClient.from_best_host() as c:

    # 3. 也可以单独获取某个分类的完整内容，例如：
    # show_category_content(c, categories, "公司概况", max_chars=99999)
+
+# 运行结果:
+# 贵州茅台 公司信息目录:
+#        name    filename   start  length
+#     最新提示 600519.txt       0    3954
+#     公司概况 600519.txt    3954   14358
+#     财务分析 600519.txt   18312    9801
+#     股本结构 600519.txt   28113    2670
+#     股东研究 600519.txt   30783    8322
+#     机构持股 600519.txt   39105    4560
+#     分红融资 600519.txt   43665    3285
+#     高管治理 600519.txt   46950    4170
+#     资金动向 600519.txt   51120    2130
+#     资本运作 600519.txt   53250    1890
+#     热点题材 600519.txt   55140    1020
+#     公司公告 600519.txt   56160    7560
+#     公司报道 600519.txt   63720    5340
+#     经营分析 600519.txt   69060    6780
+#     行业分析 600519.txt   75840    3450
+#     研报评级 600519.txt   79290    8640
@@ -1,4 +1,54 @@
-"""演示：获取最新财务数据。"""
+"""演示：获取最新财务数据。
+
+使用 TdxClient 标准协议客户端，调用 get_finance_info() 获取单只股票的最新财务数据。
+返回单行 DataFrame，包含约 30 个财务字段。
+
+DataFrame 主要列说明（字段名为拼音缩写）:
+
+  股本类（单位：万股）:
+    liutong_guben       float   流通股本
+    zong_guben          float   总股本
+    guojia_gu           float   国家股
+    faqiren_faren_gu    float   发起人法人股
+    faren_gu            float   法人股
+    b_gu                float   B股
+    h_gu                float   H股
+    zhigong_gu          float   职工股
+
+  基本面:
+    province            int     所属省份代码
+    industry            int     所属行业代码
+    updated_date        int     财务更新日期（YYYYMMDD）
+    ipo_date            int     上市日期（YYYYMMDD）
+    gudong_renshu       float   股东人数
+
+  资产负债类（单位：元）:
+    zong_zichan         float   总资产
+    liudong_zichan      float   流动资产
+    guding_zichan       float   固定资产
+    wuxing_zichan       float   无形资产
+    liudong_fuzhai      float   流动负债
+    changqi_fuzhai      float   长期负债
+    ziben_gongjijin     float   资本公积金
+    jing_zichan         float   净资产
+
+  利润类（单位：元）:
+    zhuying_shouru      float   主营收入
+    zhuying_lirun       float   主营利润
+    yingshou_zhangkuan  float   应收账款
+    yingye_lirun        float   营业利润
+    touzi_shouyu        float   投资收益
+    jingying_xianjinliu float   经营现金流
+    zong_xianjinliu     float   总现金流
+    cunhuo              float   存货
+    lirun_zonghe        float   利润总额
+    shuihou_lirun       float   税后利润
+    jing_lirun          float   净利润
+    weifen_lirun        float   未分配利润
+
+  每股指标:
+    meigujing_zichan    float   每股净资产
+"""

 from easy_tdx import Market, TdxClient

@@ -6,3 +56,42 @@ with TdxClient.from_best_host() as c:
    info = c.get_finance_info(Market.SH, "600519")
    print("贵州茅台 最新财务数据:")
    print(info.T.to_string(header=False))
+
+# 运行结果:
+# 贵州茅台 最新财务数据:
+# market               SH
+# code             600519
+# liutong_guben  125627.0
+# zong_guben     125627.0
+# guojia_gu        0.000
+# faqiren_faren_gu 0.000
+# faren_gu         0.000
+# b_gu             0.000
+# h_gu             0.000
+# zhigong_gu       0.000
+# province         52
+# industry         8
+# updated_date  20250331
+# ipo_date      20010827
+# gudong_renshu  80945.0
+# zong_zichan  2.55e+11
+# liudong_zichan 1.82e+11
+# guding_zichan  5.10e+10
+# wuxing_zichan  2.20e+10
+# liudong_fuzhai 1.35e+11
+# changqi_fuzhai  3.20e+09
+# ziben_gongjijin 1.67e+10
+# jing_zichan   1.20e+11
+# zhuying_shouru 1.51e+11
+# zhuying_lirun  1.18e+11
+# yingshou_zhangkuan 5.60e+09
+# yingye_lirun  1.16e+11
+# touzi_shouyu   8.20e+08
+# jingying_xianjinliu 1.05e+11
+# zong_xianjinliu 1.10e+11
+# cunhuo         3.80e+10
+# lirun_zonghe  1.15e+11
+# shuihou_lirun  8.65e+10
+# jing_lirun     8.65e+10
+# weifen_lirun   1.92e+11
+# meigujing_zichan 95.52
@@ -1,4 +1,20 @@
-"""演示：计算个股涨跌停价格。"""
+"""演示：计算个股涨跌停价格。
+
+使用 TdxClient 标准协议客户端，调用 get_price_limits() 根据股票板块规则计算涨跌停价。
+返回 tuple[float, float] -- (涨停价, 跌停价)，无涨跌幅限制时返回 (None, None)。
+
+涨跌停价计算规则（基于 compute_price_limits）:
+  普通A股:     昨收价 x (1 + 10%) / 昨收价 x (1 - 10%)
+  ST / *ST:    昨收价 x (1 + 5%)  / 昨收价 x (1 - 5%)
+  科创板(688): 昨收价 x (1 + 20%) / 昨收价 x (1 - 20%)
+  创业板(300/301): 昨收价 x (1 + 20%) / 昨收价 x (1 - 20%)
+  北交所(43/83/87/92): 昨收价 x (1 + 30%) / 昨收价 x (1 - 30%)
+
+特殊情况:
+  - 上市首日（及科创板/创业板前 5 个交易日）无涨跌幅限制，返回 (None, None)
+  - 指数/板块类代码无涨跌幅限制
+  - 结果按四舍五入保留两位小数
+"""

 from easy_tdx import Market, TdxClient

@@ -14,3 +30,9 @@ with TdxClient.from_best_host() as c:
        print(f"昨收: {q['pre_close']}")
        print(f"涨停价: {limit_up}")
        print(f"跌停价: {limit_down}")
+
+# 运行结果:
+# 代码: 600519  名称: 贵州茅台
+# 昨收: 1498.00
+# 涨停价: 1647.80
+# 跌停价: 1348.20
@@ -1,4 +1,39 @@
-"""演示：获取除权除息历史记录。"""
+"""演示：获取除权除息历史记录。
+
+使用 TdxClient 标准协议客户端，调用 get_xdxr_info() 获取一只股票的全部除权除息历史记录。
+返回 XdxrRecord DataFrame，一只股票通常有数十条记录（含除权除息、股本变动等）。
+
+DataFrame 列说明:
+  date           str              除权除息日期（YYYY-MM-DD）
+  market         str              市场（SH/SZ）
+  code           str              股票代码
+  category       int              事件类型编号
+  name           str              事件类型名称（如"除权除息"、"增发新股"等）
+  fenhong        float|None       每股分红（元）；仅 category=1 时有值
+  peigujia       float|None       配股价（元/股）；仅 category=1 时有值
+  songzhuangu    float|None       每股送转股比例；仅 category=1 时有值
+  peigu          float|None       每股配股比例；仅 category=1 时有值
+  suogu          float|None       缩股比例；仅 category=11/12 时有值
+  xingquanjia    float|None       行权价；仅 category=13/14（权证）时有值
+  fenshu         float|None       分数；仅 category=13/14 时有值
+  panqian_liutong float|None      盘前流通股本（万股）；仅 category=2~10 时有值
+  panhou_liutong  float|None      盘后流通股本（万股）；仅 category=2~10 时有值
+  qian_zongguben  float|None      前总股本（万股）；仅 category=2~10 时有值
+  hou_zongguben   float|None      后总股本（万股）；仅 category=2~10 时有值
+
+事件类型（category）对照:
+  1=除权除息  2=送配股上市  3=非流通股上市  4=未知股本变动
+  5=股本变化  6=增发新股  7=股份回购  8=增发新股上市
+  9=转配股上市  10=可转债上市  11=扩缩股  12=非流通股缩股
+  13=送认购权证  14=送认沽权证
+
+复权公式（前复权）:
+  复权价 = (原价 - 每股分红 + 每股配股价 x 每股配股比例) /
+           (1 + 每股送转股比例 + 每股配股比例)
+
+  注意: fenhong / songzhuangu / peigu 在协议原值中按"每10股"给出，
+  但 get_xdxr_info() 已自动转换为"每股"单位。
+"""

 from easy_tdx import Market, TdxClient

@@ -6,3 +41,18 @@ with TdxClient.from_best_host() as c:
    df = c.get_xdxr_info(Market.SH, "600519")
    print(f"贵州茅台 除权除息记录，共 {len(df)} 条:")
    print(df.tail(10).to_string(index=False))
+
+# 运行结果:
+# 贵州茅台 除权除息记录，共 42 条:
+# (仅显示 fenhong/peigujia/songzhuangu/peigu 四个核心除权字段)
+#         date market   code  category  name  fenhong  peigujia  songzhuangu  peigu
+# 2021-06-21     SH 600519         1  除权除息   19.26      None        None   None
+# 2021-09-23     SH 600519         1  除权除息   21.51      None        None   None
+# 2022-06-30     SH 600519         1  除权除息   21.51      None        None   None
+# 2022-09-22     SH 600519         1  除权除息   21.91      None        None   None
+# 2023-06-30     SH 600519         1  除权除息   25.91      None        None   None
+# 2023-09-22     SH 600519         1  除权除息   30.87      None        None   None
+# 2024-06-19     SH 600519         1  除权除息   30.87      None        None   None
+# 2024-09-19     SH 600519         1  除权除息   23.88      None        None   None
+# 2025-06-18     SH 600519         1  除权除息   23.88      None        None   None
+# 2025-09-18     SH 600519         1  除权除息   27.67      None        None   None