tdxquant 0.1.0__py3-none-any.whl

tdx_api/__init__.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""通达信量化（TdxQuant）HTTP SDK。
+
+直接调用通达信客户端官方 HTTP 接口（``POST http://127.0.0.1:17709/``），
+统一返回 ``pandas.DataFrame``，字段已重命名为金融行业 snake_case 规范。
+
+快速上手::
+
+    from tdx_api import TdxAPI
+
+    api = TdxAPI()  # 默认 http://127.0.0.1:17709，需通达信客户端在线
+    df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
+    snap = api.get_snapshot("000001.SZ")
+"""
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, _ClientBase
+from .enums import Adjust, Freq, Market
+from .exceptions import TdxQuantConnectionError, TdxQuantError
+from .api.calendar import CalendarMixin
+from .api.financial import FinancialMixin
+from .api.instrument import InstrumentMixin
+from .api.market import MarketMixin
+from .api.sector import SectorMixin
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TdxAPI",
+    "TdxQuantError",
+    "TdxQuantConnectionError",
+    "Freq",
+    "Adjust",
+    "Market",
+    "DEFAULT_BASE_URL",
+]
+
+
+class TdxAPI(
+    MarketMixin,
+    FinancialMixin,
+    SectorMixin,
+    InstrumentMixin,
+    CalendarMixin,
+    _ClientBase,
+):
+    """通达信量化 HTTP SDK 客户端。
+
+    Args:
+        base_url: 通达信客户端 HTTP 地址，默认 ``http://127.0.0.1:17709``
+            （需先启动支持 TQ 的通达信客户端）。
+        timeout: HTTP 超时秒数。
+
+    所有数据接口统一返回 ``pandas.DataFrame``；缓存/下载类操作返回 dict。
+    字段命名遵循 snake_case 金融行业惯例，原字段血缘见
+    ``docs/field_lineage.md``。
+    """

tdx_api/api/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""客户端业务接口模块（mixin）。
+
+各模块以 mixin 形式实现，最终由 :class:`tdx_api.TdxAPI` 组合继承，
+共享 :class:`tdx_api.client._ClientBase` 提供的 HTTP 与 DataFrame 工具。
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+
+def _as_list(x) -> list:
+    """把单个 str 或可迭代对象统一成 list。"""
+    if isinstance(x, str):
+        return [x]
+    return list(x)

tdx_api/api/calendar.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""交易日历与缓存/下载接口。"""
+from __future__ import annotations
+
+import pandas as pd
+
+from ..enums import validate_date
+from . import _as_list
+
+
+class CalendarMixin:
+    """交易日历、缓存刷新与文件下载接口。"""
+
+    def get_trading_calendar(
+        self, start_date: str, end_date: str, market: str = "SH"
+    ) -> pd.DataFrame:
+        """获取交易日历。
+
+        Args:
+            start_date: 起始日期 ``YYYYMMDD``。
+            end_date: 结束日期 ``YYYYMMDD``。
+            market: 市场，默认 ``SH``（上交所）。
+
+        Returns:
+            单列 DataFrame，列名 ``date``。
+        """
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_trading_calendar", market=market,
+            start_time=start_date, end_time=end_date,
+        )
+        dates = result.get("Date", []) or []
+        return pd.DataFrame({"date": dates})
+
+    def refresh_cache(self, market: str = "AG", force: bool = False) -> dict:
+        """刷新行情缓存（刷新后 5 分钟内取数据不触发刷新）。"""
+        return self._call("refresh_cache", market=market, force=force)
+
+    def refresh_kline(self, stock_list, period: str = "") -> dict:
+        """缓存历史 K线（仅支持 1m/5m/1d，不宜一次太多）。"""
+        return self._call(
+            "refresh_kline", stock_list=_as_list(stock_list), period=period or None
+        )
+
+    def download_file(
+        self, code: str, down_time: str = "", down_type: int = 1
+    ) -> dict:
+        """下载十大股东（``down_type=1``）/ ETF 申赎清单（``down_type=2``）。"""
+        return self._call(
+            "download_file", stock_code=code,
+            down_time=down_time or None, down_type=down_type,
+        )

tdx_api/api/financial.py

@@ -0,0 +1,206 @@
+# -*- coding: utf-8 -*-
+"""财务类接口：专业财务、股票/板块/市场交易数据、单点数据、股本数据。
+
+说明：
+- 专业财务字段（``FNxxx``）、交易数据字段（``GPx``/``BKx``/``SCx``/``GOx``）为通达信
+  内部编码，SDK 保留编码转小写（``FN193`` → ``fn193``）；时间字段 ``announce_time`` /
+  ``tag_time`` 保留。
+- 底层 HTTP 接口的字段参数名为 ``table_list``（非 tqcenter 的 ``field_list``）。
+- ``get_financial`` 的 ``end_time`` 为必填，留空时自动取当天。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+import pandas as pd
+
+from ..enums import validate_date
+from . import _as_list
+
+
+def _date_to_year_mmdd(date_str: str) -> tuple[int, int]:
+    """``YYYYMMDD`` → ``(year, mmdd)``，空串返回 ``(0, 0)``。"""
+    if not date_str:
+        return 0, 0
+    return int(date_str[:4]), int(date_str[4:8])
+
+
+class FinancialMixin:
+    """财务与交易数据接口。"""
+
+    def get_financial(
+        self, stock_list, fields=None, start_date="", end_date="",
+        report_type="report_time",
+    ) -> pd.DataFrame:
+        """专业财务数据（需客户端下载专业财务数据）。
+
+        Args:
+            stock_list: 证券代码或列表。
+            fields: 字段列表（通达信编码，如 ``["Fn193", "Fn194"]``）。
+            start_date / end_date: 日期区间 ``YYYYMMDD``（end 留空取当天）。
+            report_type: ``report_time`` 按截止日期 / ``announce_time`` 按公告日期。
+        """
+        stock_list = _as_list(stock_list)
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date") or datetime.now().strftime("%Y%m%d")
+        result = self._call(
+            "get_financial_data",
+            stock_list=stock_list,
+            table_list=fields or [],
+            start_time=start_date or None,
+            end_time=end_date,
+            report_type=report_type,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_financial_by_date(
+        self, stock_list, fields=None, date=""
+    ) -> pd.DataFrame:
+        """指定日期的专业财务数据。"""
+        stock_list = _as_list(stock_list)
+        year, mmdd = _date_to_year_mmdd(validate_date(date, "date"))
+        result = self._call(
+            "get_financial_data_by_date",
+            stock_list=stock_list, table_list=fields or [], year=year, mmdd=mmdd,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_stock_trade_data(
+        self, stock_list, fields=None, start_date="", end_date=""
+    ) -> pd.DataFrame:
+        """股票交易数据（字段 GPx）。"""
+        stock_list = _as_list(stock_list)
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_gpjy_value",
+            stock_list=stock_list, table_list=fields or [],
+            start_time=start_date or None, end_time=end_date or None,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_stock_trade_data_by_date(
+        self, stock_list, fields=None, date=""
+    ) -> pd.DataFrame:
+        """指定日期的股票交易数据。"""
+        stock_list = _as_list(stock_list)
+        year, mmdd = _date_to_year_mmdd(validate_date(date, "date"))
+        result = self._call(
+            "get_gpjy_value_by_date",
+            stock_list=stock_list, table_list=fields or [], year=year, mmdd=mmdd,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_sector_trade_data(
+        self, stock_list, fields=None, start_date="", end_date=""
+    ) -> pd.DataFrame:
+        """板块交易数据（字段 BKx）。"""
+        stock_list = _as_list(stock_list)
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_bkjy_value",
+            stock_list=stock_list, table_list=fields or [],
+            start_time=start_date or None, end_time=end_date or None,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_sector_trade_data_by_date(
+        self, stock_list, fields=None, date=""
+    ) -> pd.DataFrame:
+        """指定日期的板块交易数据。"""
+        stock_list = _as_list(stock_list)
+        year, mmdd = _date_to_year_mmdd(validate_date(date, "date"))
+        result = self._call(
+            "get_bkjy_value_by_date",
+            stock_list=stock_list, table_list=fields or [], year=year, mmdd=mmdd,
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_market_trade_data(
+        self, fields=None, start_date="", end_date=""
+    ) -> pd.DataFrame:
+        """市场交易数据（字段 SCx，无个股维度）。"""
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_scjy_value",
+            table_list=fields or [],
+            start_time=start_date or None, end_time=end_date or None,
+        )
+        return self._flat_value_to_df(result)
+
+    def get_market_trade_data_by_date(
+        self, fields=None, date=""
+    ) -> pd.DataFrame:
+        """指定日期的市场交易数据。"""
+        year, mmdd = _date_to_year_mmdd(validate_date(date, "date"))
+        result = self._call(
+            "get_scjy_value_by_date",
+            table_list=fields or [], year=year, mmdd=mmdd,
+        )
+        return self._flat_value_to_df(result)
+
+    def get_stock_single_data(self, stock_list, fields=None) -> pd.DataFrame:
+        """股票单个数据（非序列，字段 GOx）。"""
+        stock_list = _as_list(stock_list)
+        result = self._call(
+            "get_gp_one_data", stock_list=stock_list, table_list=fields or [],
+        )
+        return self._stock_value_to_df(result, stock_list)
+
+    def get_share_capital(self, code, date_list=None, count=1) -> pd.DataFrame:
+        """每日股本数据（总股本/流通股本等）。"""
+        result = self._call(
+            "get_gb_info", stock_code=code, date_list=date_list or [], count=count,
+        )
+        return self._flat_value_to_df(result)
+
+    def get_share_capital_by_date(
+        self, code, start_date="", end_date=""
+    ) -> pd.DataFrame:
+        """按日期段获取股本数据。"""
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_gb_info_by_date",
+            stock_code=code,
+            start_date=start_date or None, end_date=end_date or None,
+        )
+        return self._flat_value_to_df(result)
+
+    # ---------------- 解析工具 ----------------
+    def _stock_value_to_df(self, result, stock_list) -> pd.DataFrame:
+        """``result.Value.{stock: {field: [list]|value}}`` → 长表，加 code 列。"""
+        value = result.get("Value", {})
+        parts: list[pd.DataFrame] = []
+        items = value.items() if isinstance(value, dict) else []
+        for stock, sv in items:
+            if stock not in stock_list or sv is None:
+                continue
+            if isinstance(sv, dict):
+                sdf = pd.DataFrame(sv)
+            else:
+                sdf = pd.DataFrame([{"value": sv}])
+            sdf.insert(0, "code", stock)
+            parts.append(sdf.reset_index(drop=True))
+        if not parts:
+            return pd.DataFrame()
+        out = pd.concat(parts, ignore_index=True)
+        out.columns = [c.lower() if c != "code" else c for c in out.columns]
+        return out
+
+    def _flat_value_to_df(self, result) -> pd.DataFrame:
+        """``result.Value`` 为扁平 dict / ``{field: [list]}`` / list → DataFrame。"""
+        value = result.get("Value", result)
+        if value is None or value == "":
+            return pd.DataFrame()
+        if isinstance(value, dict):
+            df = pd.DataFrame(value)
+        elif isinstance(value, list):
+            df = self._list_to_df(value)
+        else:
+            return pd.DataFrame()
+        if not df.empty:
+            df.columns = [str(c).lower() for c in df.columns]
+        return df

tdx_api/api/instrument.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+"""证券类接口：可转债、新股/新债申购、跟踪指数的 ETF。"""
+from __future__ import annotations
+
+import pandas as pd
+
+from ..schema import CB_FIELD_MAP, ETF_FIELD_MAP, IPO_FIELD_MAP
+
+
+class InstrumentMixin:
+    """可转债 / 新股 / ETF 接口。"""
+
+    def get_convertible_bond(self, code: str, fields=None) -> pd.DataFrame:
+        """获取可转债基础信息（HTTP 返回 Value 为 list，取首项）。
+
+        Returns:
+            单行 DataFrame，列见 ``docs/field_lineage.md`` 可转债表。
+        """
+        result = self._call("get_kzz_info", stock_code=code, field_list=fields or None)
+        value = result.get("Value", [])
+        if not value:
+            return pd.DataFrame()
+        item = value[0] if isinstance(value, list) else value
+        row = self._dict_to_row(item, CB_FIELD_MAP)
+        return self._rows_to_df([row])
+
+    def get_ipo_info(self, ipo_type: int = 0, ipo_date: int = 0) -> pd.DataFrame:
+        """获取新股 / 新债申购信息。
+
+        Args:
+            ipo_type: ``0`` 全部 / ``1`` 新债 / ``2`` 新股。
+            ipo_date: ``0`` 今天 / ``1`` 今天及以后。
+
+        Returns:
+            DataFrame，列：``code, name, subscribe_date, subscribe_price,
+            subscribe_code, max_subscribe, issue_pe``。
+        """
+        result = self._call("get_ipo_info", ipo_type=ipo_type, ipo_date=ipo_date)
+        value = result.get("Value", []) or []
+        df = self._list_to_df(value)
+        if not df.empty:
+            df = df.rename(columns=lambda c: self._rename(IPO_FIELD_MAP, c))
+        return df
+
+    def get_track_etf(self, zs_code: str) -> pd.DataFrame:
+        """获取跟踪指定指数的 ETF 列表。
+
+        Args:
+            zs_code: 指数代码，如 ``000300.SH``。
+
+        Returns:
+            DataFrame，列：``code, name, last_price, pre_close, iopv,
+            total_share, scale``。
+        """
+        result = self._call("get_trackzs_etf_info", zs_code=zs_code)
+        value = result.get("Value", []) or []
+        df = self._list_to_df(value)
+        if not df.empty:
+            df = df.rename(columns=lambda c: self._rename(ETF_FIELD_MAP, c))
+        return df

tdx_api/api/market.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""行情类接口：K线、快照、基本信息、更多信息、分红送配。
+
+直接调用通达信官方 HTTP 接口（POST 127.0.0.1:17709），字段血缘见
+:mod:`tdx_api.schema` 与 ``docs/field_lineage.md``。
+"""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+
+import pandas as pd
+
+from ..enums import adjust_to_dividend, freq_to_period, validate_date
+from ..schema import (
+    DIVIDEND_FIELD_MAP,
+    SNAPSHOT_FIELD_MAP,
+    STOCK_INFO_FIELD_MAP,
+)
+from . import _as_list
+
+
+class MarketMixin:
+    """行情数据接口。"""
+
+    def get_kline(
+        self,
+        code,
+        freq: str = "daily",
+        adjust: str = "none",
+        start_date: str = "",
+        end_date: str = "",
+        fields=None,
+        fill_data: bool = True,
+    ) -> pd.DataFrame:
+        """获取K线数据，返回标准 OHLCV 长表。
+
+        Args:
+            code: 证券代码或列表，如 ``"000001.SZ"`` 或 ``["000001.SZ", "600519.SH"]``。
+            freq: 频率：``1min/5min/15min/30min/60min/daily/weekly/monthly``。
+            adjust: 复权：``none`` 不复权 / ``qfq`` 前复权 / ``hfq`` 后复权。
+            start_date: 起始日期 ``YYYYMMDD``（分钟线可 ``YYYYMMDDHHMMSS``）。
+            end_date: 结束日期，留空取至今。
+            fields: 返回字段筛选（原字段名，如 ``["Open", "Close"]``）。
+            fill_data: 是否向后填充缺失数据。
+
+        Returns:
+            DataFrame，列：``datetime, code, open, high, low, close, volume,
+            amount, forward_factor, open_interest``。
+        """
+        stock_list = _as_list(code)
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_market_data",
+            stock_list=stock_list,
+            period=freq_to_period(freq),
+            count=-1,
+            dividend_type=adjust_to_dividend(adjust),
+            start_time=start_date or None,
+            end_time=end_date or None,
+            field_list=fields or None,
+            fill_data=fill_data,
+        )
+        return self._build_kline(result, stock_list)
+
+    def get_snapshot(self, code, fields=None, max_workers: int | None = 16) -> pd.DataFrame:
+        """获取实时行情快照（返回扁平字段，索引 ``code``）。
+
+        Args:
+            code: 证券代码或列表。
+            fields: 返回字段筛选（原字段名）。
+            max_workers: 并发线程数。传入多个代码时默认并发（``16``），
+                单次约 3.5ms、全市场 5500+ 只约 5s。传 ``None``/``1`` 退回串行。
+                注意：通达信客户端服务端并行上限约 12~16，超过 20 会因排队变慢。
+        """
+        codes = _as_list(code)
+        field_list = fields or None
+
+        def _fetch(c):
+            # 线程内只做 HTTP 拉取(纯 I/O、释放 GIL)，字段重命名留到拉取后单遍处理，
+            # 避免 GIL 持有的 Python 计算在 16 线程下被串行化、吃掉并发红利
+            return self._call("get_market_snapshot", stock_code=c, field_list=field_list)
+
+        if not max_workers or max_workers <= 1 or len(codes) == 1:
+            results = [_fetch(c) for c in codes]
+        else:
+            # httpx.Client 线程安全，复用 self._client；ThreadPoolExecutor.map 保序
+            with ThreadPoolExecutor(max_workers=max_workers) as ex:
+                results = list(ex.map(_fetch, codes))
+        rows = [
+            self._dict_to_row(r, SNAPSHOT_FIELD_MAP, code=c)
+            for c, r in zip(codes, results)
+        ]
+        return self._rows_to_df(rows, index_col="code")
+
+    def get_instrument_info(self, code, fields=None) -> pd.DataFrame:
+        """证券基本信息（返回扁平字段，索引 ``code``）。"""
+        codes = _as_list(code)
+        rows = []
+        for c in codes:
+            result = self._call(
+                "get_stock_info", stock_code=c, field_list=fields or None
+            )
+            rows.append(self._dict_to_row(result, STOCK_INFO_FIELD_MAP, code=c))
+        return self._rows_to_df(rows, index_col="code")
+
+    def get_more_info(self, code, fields=None) -> pd.DataFrame:
+        """证券更多信息（返回扁平字段，索引 ``code``）。
+
+        注意：HTTP 返回的数据在 ``result.Value`` 内。
+        """
+        codes = _as_list(code)
+        rows = []
+        for c in codes:
+            result = self._call(
+                "get_more_info", stock_code=c, field_list=fields or None
+            )
+            data = result.get("Value", result)
+            rows.append(self._dict_to_row(data, STOCK_INFO_FIELD_MAP, code=c))
+        return self._rows_to_df(rows, index_col="code")
+
+    def get_dividend_factors(
+        self, code: str, start_date: str = "", end_date: str = ""
+    ) -> pd.DataFrame:
+        """获取分红送配（除权除息）数据。
+
+        Returns:
+            DataFrame，列：``date, div_type, cash_dividend, rights_price,
+            share_bonus, rights_issue``。
+        """
+        start_date = validate_date(start_date, "start_date")
+        end_date = validate_date(end_date, "end_date")
+        result = self._call(
+            "get_divid_factors",
+            stock_code=code,
+            start_time=start_date or None,
+            end_time=end_date or None,
+        )
+        return self._divid_to_df(result)
+
+    # ---------------- 内部工具 ----------------
+    def _divid_to_df(self, result: dict) -> pd.DataFrame:
+        """解析 get_divid_factors 的 result。
+
+        结构：``{Date:[...], Type:[...], Value:[[bonus,allotprice,sharebonus,allotment],...]}``
+        """
+        dates = result.get("Date", []) or []
+        types = result.get("Type", []) or []
+        values = result.get("Value", []) or []
+        rows = []
+        for i in range(len(dates)):
+            v = values[i] if i < len(values) else []
+            rows.append(
+                {
+                    "date": dates[i],
+                    "div_type": types[i] if i < len(types) else None,
+                    "cash_dividend": v[0] if len(v) > 0 else None,
+                    "rights_price": v[1] if len(v) > 1 else None,
+                    "share_bonus": v[2] if len(v) > 2 else None,
+                    "rights_issue": v[3] if len(v) > 3 else None,
+                }
+            )
+        if not rows:
+            return pd.DataFrame()
+        df = pd.DataFrame(rows)
+        for c in ("cash_dividend", "rights_price", "share_bonus", "rights_issue"):
+            df[c] = pd.to_numeric(df[c], errors="coerce")
+        return df

tdx_api/api/sector.py

@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""板块 / 分类成分股接口。"""
+from __future__ import annotations
+
+import pandas as pd
+
+# get_stock_list 的分类代码(market) → 中文名称映射
+STOCK_CATEGORY: dict[str, str] = {
+    "5": "所有A股",
+    "6": "上证指数成份股",
+    "7": "上证主板",
+    "8": "深证主板",
+    "9": "重点指数",
+    "10": "所有板块指数",
+    "11": "缺省行业板块",
+    "12": "概念板块",
+    "13": "风格板块",
+    "14": "地区板块",
+    "15": "行业+概念板块",
+    "16": "研究行业一级",
+    "17": "研究行业二级",
+    "18": "研究行业三级",
+    "21": "含H股",
+    "22": "含可转债",
+    "23": "沪深300",
+    "24": "中证500",
+    "25": "中证1000",
+    "26": "国证2000",
+    "27": "中证2000",
+    "28": "中证A500",
+    "30": "REITs",
+    "31": "ETF基金",
+    "32": "可转债",
+    "33": "LOF基金",
+    "34": "所有可交易基金",
+    "35": "所有沪深基金",
+    "36": "T+0基金",
+    "49": "金融类企业",
+    "50": "沪深A股",
+    "51": "创业板",
+    "52": "科创板",
+    "53": "北交所",
+    "101": "国内期货",
+    "102": "港股",
+    "103": "美股",
+}
+
+# market 不传时默认遍历的分类（股票 + 基金，不含期货/港股/美股/纯指数）
+DEFAULT_STOCK_MARKETS = [
+    "5", "7", "8", "23", "24", "25", "31", "32", "50", "51", "52", "53",
+]
+
+
+class SectorMixin:
+    """板块与分类成分股接口。"""
+
+    def get_stock_list(self, market=None) -> pd.DataFrame:
+        """获取股票/基金分类成分股。
+
+        Args:
+            market: 分类代码。不传(默认)则遍历所有主要分类合并返回；
+                传具体值(如 ``"5"``/``"23"``/``"32"``)只返回该分类。
+                完整取值见模块级 ``STOCK_CATEGORY``。
+
+        Returns:
+            DataFrame，列：``code, market, category``（category 为中文分类名）。
+            ``market`` 不传时，同一股票可能属于多个分类而出现多行。
+        """
+        markets = DEFAULT_STOCK_MARKETS if market is None else [str(market)]
+        parts: list[pd.DataFrame] = []
+        for m in markets:
+            result = self._call("get_stock_list", market=m, list_type=0)
+            codes = result.get("Value", []) or []
+            if not codes:
+                continue
+            df = pd.DataFrame({"code": codes})
+            df["market"] = m
+            df["category"] = STOCK_CATEGORY.get(m, m)
+            parts.append(df)
+        if not parts:
+            return pd.DataFrame(columns=["code", "market", "category"])
+        return pd.concat(parts, ignore_index=True)
+
+    def get_sector_list(self, list_type: int = 0) -> pd.DataFrame:
+        """获取 A 股全部板块。
+
+        Args:
+            list_type: ``0`` 仅代码（列 ``code``）/ ``1`` 含名称（列 ``code, name``）。
+
+        Returns:
+            DataFrame。
+        """
+        result = self._call("get_sector_list", list_type=list_type)
+        value = result.get("Value", []) or []
+        columns = ["code", "name"] if list_type else None
+        return self._list_to_df(value, columns=columns)
+
+    def get_user_sectors(self) -> pd.DataFrame:
+        """获取用户自定义板块列表。
+
+        Returns:
+            DataFrame，列：``code, name``（无自定义板块时为空）。
+        """
+        result = self._call("get_user_sector")
+        value = result.get("Value")
+        if not value:
+            return pd.DataFrame(columns=["code", "name"])
+        return self._list_to_df(value, columns=["code", "name"])
+
+    def get_sector_stocks(
+        self, block_code: str, block_type: int = 0, list_type: int = 0
+    ) -> pd.DataFrame:
+        """获取板块成分股。
+
+        Args:
+            block_code: 板块代码（如 ``880081.SH``）或名称（如 ``钛金属``）；
+                ``block_type=1`` 时传自定义板块简称。
+            block_type: ``0`` 系统板块 / ``1`` 自定义板块简称。
+
+        Returns:
+            单列 DataFrame，列名 ``code``。
+        """
+        result = self._call(
+            "get_stock_list_in_sector",
+            block_code=block_code,
+            block_type=block_type,
+            list_type=list_type,
+        )
+        value = result.get("Value", []) or []
+        return self._list_to_df(value)

tdx_api/client.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""HTTP 客户端：直接调用通达信官方 HTTP 接口。
+
+通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）::
+
+    POST http://127.0.0.1:17709/
+    body : {"id": 1, "method": "<tqcenter 方法名>", "params": {...}}
+    响应 : {"id": 1, "result": {...}}
+
+``method`` 为 tqcenter 中的函数名，``params`` 为底层参数名（多数与 tqcenter
+参数名一致，少数不同，如财务类的 ``field_list`` 底层为 ``table_list``）。
+
+本模块负责构造请求、解析响应、字段重命名、拼装 DataFrame。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import orjson
+import pandas as pd
+
+from .exceptions import TdxQuantConnectionError, TdxQuantError
+
+# 通达信客户端官方 HTTP 端口
+DEFAULT_BASE_URL = "http://127.0.0.1:17709"
+
+
+class _ClientBase:
+    """HTTP 客户端基类，提供官方 HTTP 调用与 DataFrame 拼装工具。"""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        # trust_env=False：忽略系统/环境变量代理，直连同本机客户端
+        self._client = httpx.Client(
+            base_url=self.base_url, trust_env=False, timeout=timeout
+        )
+
+    # ---------------- 生命周期 ----------------
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "_ClientBase":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---------------- 核心调用 ----------------
+    def _call(self, method: str, **params: Any) -> dict:
+        """POST 官方 HTTP 接口，返回 ``result`` 字典。
+
+        Raises:
+            TdxQuantConnectionError: 网络/连接错误。
+            TdxQuantError: 通达信返回 ErrorId 非 0（含 .error_id / .error_msg）。
+        """
+        params = {k: v for k, v in params.items() if v is not None}
+        try:
+            resp = self._client.post(
+                "/", json={"id": 1, "method": method, "params": params}
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError as e:
+            raise TdxQuantConnectionError(
+                f"通达信 HTTP 连接失败({self.base_url}): {e}"
+            ) from e
+        try:
+            # orjson 直接解析 resp.content(bytes)，省一次 decode；响应小但调用频繁时累积收益明显
+            payload = orjson.loads(resp.content)
+        except ValueError as e:
+            raise TdxQuantError(f"返回非 JSON: {resp.text[:200]}") from e
+        result = payload.get("result", {})
+        if str(result.get("ErrorId", "0")) != "0":
+            raise TdxQuantError(
+                result.get("Error") or result.get("ErrorId") or "未知错误",
+                result.get("ErrorId"),
+            )
+        return result
+
+    def health(self) -> dict:
+        """健康检查：试调一个轻量接口验证连通性。"""
+        try:
+            self._call("get_trading_dates", market="SH", count=1)
+            return {"status": "ok", "base_url": self.base_url}
+        except Exception as e:  # noqa: BLE001
+            return {"status": "error", "msg": str(e)}
+
+    # ---------------- DataFrame 拼装工具 ----------------
+    @staticmethod
+    def _rename(mapping: dict[str, str], key: str) -> str:
+        """按映射表重命名字段，未命中则转小写。"""
+        return mapping.get(key, key.lower())
+
+    def _dict_to_row(
+        self, raw: dict, mapping: dict[str, str], code: str | None = None
+    ) -> dict:
+        """把单只证券的 dict 重命名 key，返回一行数据。"""
+        row: dict[str, Any] = {}
+        if code is not None:
+            row["code"] = code
+        for k, v in raw.items():
+            if k in ("ErrorId", "Error", "run_id"):
+                continue
+            row[self._rename(mapping, k)] = v
+        return row
+
+    def _rows_to_df(
+        self, rows: list[dict], index_col: str | None = None
+    ) -> pd.DataFrame:
+        if not rows:
+            return pd.DataFrame()
+        df = pd.DataFrame(rows)
+        for col in df.columns:
+            df[col] = self._maybe_numeric(df[col])
+        if index_col and index_col in df.columns:
+            df = df.set_index(index_col)
+        return df
+
+    @staticmethod
+    def _maybe_numeric(series: pd.Series) -> pd.Series:
+        if series.map(lambda x: isinstance(x, (list, dict))).any():
+            return series
+        converted = pd.to_numeric(series, errors="coerce")
+        if converted.isna().all() and not series.isna().all():
+            return series
+        return converted
+
+    def _list_to_df(self, raw, columns=None) -> pd.DataFrame:
+        """列表结果转 DataFrame（str→单列 / dict→自动成表 / list→多列）。"""
+        if not raw:
+            return pd.DataFrame()
+        first = raw[0]
+        if isinstance(first, str):
+            col = columns[0] if columns else "code"
+            return pd.DataFrame({col: raw})
+        if isinstance(first, dict):
+            return pd.DataFrame(raw)
+        df = pd.DataFrame(raw)
+        if columns and len(columns) >= df.shape[1]:
+            df = df.iloc[:, : len(columns)]
+            df.columns = columns
+        return df
+
+    def _build_kline(self, result: dict, stock_list) -> pd.DataFrame:
+        """解析 get_market_data 的 result。
+
+        result.Value.{stock}.{field: [list]} → 标准 OHLCV 长表。
+        """
+        from .schema import KLINE_FIELD_MAP
+
+        stock_list = list(stock_list)
+        value = result.get("Value", {})
+        parts: list[pd.DataFrame] = []
+        for stock in stock_list:
+            sv = value.get(stock)
+            if not sv:
+                continue
+            dates = sv.get("Date", [])
+            idx = pd.to_datetime(dates, errors="coerce") if dates else None
+            col_data: dict[str, Any] = {}
+            for field in (
+                "Open", "High", "Low", "Close",
+                "Volume", "Amount", "ForwardFactor", "VolInStock",
+            ):
+                if field in sv:
+                    col_data[field] = pd.to_numeric(
+                        pd.Series(sv[field]), errors="coerce"
+                    ).values
+            if not col_data:
+                continue
+            sdf = pd.DataFrame(col_data, index=idx)
+            sdf.insert(0, "code", stock)
+            parts.append(sdf)
+        if not parts:
+            return pd.DataFrame()
+        out = pd.concat(parts)
+        out.index.name = "datetime"
+        out = out.reset_index()
+        out = out.rename(
+            columns=lambda c: KLINE_FIELD_MAP.get(c, c) if c != "datetime" else c
+        )
+        return out

tdx_api/enums.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+"""枚举与常量定义。
+
+对外暴露的枚举使用金融行业常用写法（daily / 5min / qfq），
+内部再转换为 tqcenter 要求的 period / dividend_type 字符串。
+"""
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+
+class Freq(str, Enum):
+    """K线频率（SDK 对外写法 → tqcenter period）。
+
+    使用 ``str`` 作为基类，因此可直接当字符串用：``Freq.DAILY == "daily"``。
+    """
+
+    MIN1 = "1min"      # 1分钟
+    MIN5 = "5min"      # 5分钟
+    MIN15 = "15min"    # 15分钟
+    MIN30 = "30min"    # 30分钟
+    MIN60 = "60min"    # 60分钟
+    DAILY = "daily"    # 日线
+    WEEKLY = "weekly"  # 周线
+    MONTHLY = "monthly"  # 月线
+
+
+# SDK 频率 → tqcenter period 映射
+FREQ_TO_PERIOD: dict[str, str] = {
+    "1min": "1m",
+    "5min": "5m",
+    "15min": "15m",
+    "30min": "30m",
+    "60min": "1h",
+    "daily": "1d",
+    "weekly": "1w",
+    "monthly": "1mon",
+}
+
+
+class Adjust(str, Enum):
+    """复权类型（SDK 对外写法 → tqcenter dividend_type）。"""
+
+    NONE = "none"  # 不复权
+    QFQ = "qfq"    # 前复权
+    HFQ = "hfq"    # 后复权
+
+
+# SDK 复权 → tqcenter dividend_type 映射
+ADJUST_TO_DIVIDEND: dict[str, str] = {
+    "none": "none",
+    "qfq": "front",
+    "hfq": "back",
+}
+
+
+class Market(str, Enum):
+    """市场后缀（证券代码 ``XXXXXX.XX`` 中的后缀部分）。"""
+
+    SH = "SH"  # 上海
+    SZ = "SZ"  # 深圳
+    BJ = "BJ"  # 北交所
+    JJ = "JJ"  # 基金
+
+
+def normalize_freq(freq: str) -> str:
+    """把用户传入的频率统一成小写字符串。"""
+    return str(freq).lower()
+
+
+def freq_to_period(freq: str) -> str:
+    """SDK 频率 → tqcenter period，无效时抛 ValueError。"""
+    key = normalize_freq(freq)
+    if key not in FREQ_TO_PERIOD:
+        raise ValueError(
+            f"不支持的频率: {freq!r}，可选: {list(FREQ_TO_PERIOD.keys())}"
+        )
+    return FREQ_TO_PERIOD[key]
+
+
+def normalize_adjust(adjust: str | None) -> str:
+    """复权类型归一化，默认不复权。"""
+    if adjust is None:
+        return "none"
+    key = str(adjust).lower()
+    if key not in ADJUST_TO_DIVIDEND:
+        raise ValueError(
+            f"不支持的复权类型: {adjust!r}，可选: none / qfq / hfq"
+        )
+    return key
+
+
+def adjust_to_dividend(adjust: str | None) -> str:
+    """SDK 复权 → tqcenter dividend_type。"""
+    return ADJUST_TO_DIVIDEND[normalize_adjust(adjust)]
+
+
+# 严格日期格式：YYYYMMDD（日级）或 YYYYMMDDHHMMSS（分钟级）
+_DATE_PATTERN = re.compile(r"^\d{8}$")
+_DATETIME_PATTERN = re.compile(r"^\d{14}$")
+
+
+def validate_date(value, name: str = "date") -> str:
+    """严格校验日期格式为 ``YYYYMMDD``（或分钟线的 ``YYYYMMDDHHMMSS``）。
+
+    Args:
+        value: 日期值。``None`` / 空串视为"不限制"，原样返回。
+        name: 参数名，用于报错信息。
+
+    Returns:
+        校验通过的字符串。
+
+    Raises:
+        ValueError: 格式不符合 ``YYYYMMDD``。
+    """
+    if value is None or value == "":
+        return value if value is not None else ""
+    s = str(value)
+    if _DATE_PATTERN.match(s) or _DATETIME_PATTERN.match(s):
+        return s
+    raise ValueError(
+        f"{name} 格式错误: {value!r}，应为 YYYYMMDD（如 20260613）"
+    )

tdx_api/exceptions.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""SDK 异常定义。"""
+from __future__ import annotations
+
+
+class TdxQuantError(Exception):
+    """通达信量化 SDK 通用错误（业务错误，error_id 非 0）。"""
+
+    def __init__(self, message: str, error_id: str | None = None) -> None:
+        super().__init__(message)
+        self.error_id = error_id
+        self.error_msg = message
+
+
+class TdxQuantConnectionError(TdxQuantError):
+    """网关连接错误（网络不可达、超时等）。"""

tdx_api/schema.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""字段血缘映射表（字段重命名的唯一真实来源）。
+
+本文件记录 tqcenter 原始字段名 → SDK 规范字段名（snake_case 金融行业惯例）的映射。
+``docs/field_lineage.md`` 据此生成，保证代码与文档一致。
+
+设计原则：
+- 价格类：open / high / low / close / last / last_close / average_price
+- 量额类：volume(手) / amount(元或万元) / turnover
+- 五档买卖：bid_prices / bid_volumes / ask_prices / ask_volumes
+- 基金：nav(净值)
+- 涨跌：pct_chg(涨跌幅) / change_speed(涨速)
+- 期货：open_interest(持仓量)
+"""
+from __future__ import annotations
+
+# ----------------------------------------------------------------------
+# K线字段：tqcenter get_market_data 返回 {field: DataFrame(index=stock, col=time)}
+# SDK 转换为长表，每行一个时间点。
+# ----------------------------------------------------------------------
+KLINE_FIELD_MAP: dict[str, str] = {
+    "Date": "date",
+    "Time": "time",
+    "Open": "open",
+    "High": "high",
+    "Low": "low",
+    "Close": "close",
+    "Volume": "volume",
+    "Amount": "amount",
+    "ForwardFactor": "forward_factor",  # 前复权因子(仅不复权时有效)
+    "VolInStock": "open_interest",      # 持仓量(期货)
+}
+
+# ----------------------------------------------------------------------
+# 行情快照字段：tqcenter get_market_snapshot 返回 dict
+# ----------------------------------------------------------------------
+SNAPSHOT_FIELD_MAP: dict[str, str] = {
+    "ItemNum": "tick_count",          # 快照笔数
+    "LastClose": "last_close",        # 昨收价
+    "Open": "open",                   # 开盘价
+    "Max": "high",                    # 最高价
+    "Min": "low",                     # 最低价
+    "Now": "last",                    # 最新价(现价)
+    "Volume": "volume",               # 总成交量(手)
+    "NowVol": "last_volume",          # 现手
+    "Amount": "amount",               # 总成交额
+    "Inside": "inside_volume",        # 内盘
+    "Outside": "outside_volume",      # 外盘
+    "TickDiff": "tick_change",        # 笔涨跌
+    "InOutFlag": "in_out_flag",       # 内外盘标志 0买1卖2未知
+    "Jjjz": "nav",                    # 基金净值
+    "Buyp": "bid_prices",             # 五档买价(list)
+    "Buyv": "bid_volumes",            # 五档买量(list)
+    "Sellp": "ask_prices",            # 五档卖价(list)
+    "Sellv": "ask_volumes",           # 五档卖量(list)
+    "UpHome": "up_count",             # 上涨家数(指数)
+    "DownHome": "down_count",         # 下跌家数(指数)
+    "Before5MinNow": "price_5min_ago",  # 5分钟前价格
+    "Average": "average_price",       # 均价
+    "XsFlag": "decimal_places",       # 小数位数
+    "Zangsu": "change_speed",         # 涨速
+    "ZAFPre3": "pct_chg_3d",          # 3日涨幅(%)
+}
+
+# ----------------------------------------------------------------------
+# 证券基本信息字段：tqcenter get_stock_info 返回 dict
+# 字段以实际返回为准，此处覆盖文档已知项；未知原字段保留原名转小写。
+# ----------------------------------------------------------------------
+STOCK_INFO_FIELD_MAP: dict[str, str] = {
+    "Code": "code",
+    "Name": "name",
+    "J_zgb": "total_share_capital",   # 总股本
+    "ActiveCapital": "float_capital",  # 流通股本
+    "J_zltb": "float_ratio",          # 流通占比
+    "Industry": "industry",           # 行业
+    "J_hy": "industry_code",
+    "J_zh": "concept_code",
+    "J_country": "region",
+    "J_main": "main_business",
+}
+
+# ----------------------------------------------------------------------
+# 分红送配字段：tqcenter get_divid_factors 返回 DataFrame
+# ----------------------------------------------------------------------
+DIVIDEND_FIELD_MAP: dict[str, str] = {
+    # 实际字段（index 为除权除息日期）
+    "Type": "div_type",             # 分红类型
+    "Bonus": "cash_dividend",       # 每股派息(红利)
+    "AllotPrice": "rights_price",   # 配股价
+    "ShareBonus": "share_bonus",    # 每股送转股
+    "Allotment": "rights_issue",    # 每股配股
+    "ForwardFactor": "forward_factor",
+    "BackwardFactor": "backward_factor",
+}
+
+# 可转债字段：tqcenter get_kzz_info 返回 dict
+CB_FIELD_MAP: dict[str, str] = {
+    "SetCode": "market",               # 市场 0深1沪
+    "KZZCode": "bond_code",            # 可转债代码
+    "HSCode": "underlying_code",       # 正股代码
+    "ZGPrice": "conversion_price",     # 转股价
+    "CurRate": "coupon_rate",          # 票面利率
+    "RestScope": "remaining_scale",    # 剩余规模
+    "PutBack": "putback_flag",         # 回售标志
+    "ForceRedeem": "force_redeem_flag",  # 强制赎回标志
+}
+
+# ETF 字段：tqcenter get_trackzs_etf_info 返回 list[dict]
+ETF_FIELD_MAP: dict[str, str] = {
+    "Code": "code",
+    "Name": "name",
+    "NowPrice": "last_price",   # 现价
+    "PreClose": "pre_close",    # 昨收
+    "IOPV": "iopv",             # 参考净值
+    "Zgb": "total_share",       # 总份额/规模
+    "Sz": "scale",              # 规模
+}
+
+# 新股/新债申购字段：tqcenter get_ipo_info 返回 list[dict]
+IPO_FIELD_MAP: dict[str, str] = {
+    "SetCode": "market",          # 市场 0深1沪
+    "Code": "code",
+    "Name": "name",
+    "SGDate": "subscribe_date",   # 申购日期
+    "SGPrice": "subscribe_price", # 申购价
+    "SGCode": "subscribe_code",   # 申购代码
+    "MaxSG": "max_subscribe",     # 最大申购额
+    "PE_Issue": "issue_pe",       # 发行市盈率
+}
+
+# 板块字段：tqcenter get_sector_list 返回 list
+# 元素为 [code, name] 形式，SDK 转为 DataFrame(code, name)
+SECTOR_FIELD_MAP: dict[str, str] = {
+    "code": "code",
+    "name": "name",
+}
+
+
+def rename_keys(data: dict, mapping: dict[str, str]) -> dict:
+    """按映射表重命名字典的 key；未命中的 key 原样保留。
+
+    Args:
+        data: 原始字典。
+        mapping: {原字段: 新字段} 映射。
+
+    Returns:
+        重命名后的新字典。
+    """
+    return {mapping.get(k, k): v for k, v in data.items()}
+
+
+def rename_dataframe_columns(
+    df, mapping: dict[str, str], keep_unknown: bool = True
+):
+    """重命名 DataFrame 的列名。
+
+    Args:
+        df: pandas.DataFrame。
+        mapping: {原列名: 新列名}。
+        keep_unknown: True 时未命中的列保留原名；False 时丢弃。
+    """
+    import pandas as pd
+
+    if df is None or df.empty:
+        return df
+    if not keep_unknown:
+        df = df[[c for c in df.columns if c in mapping]]
+    return df.rename(columns={k: v for k, v in mapping.items() if k in df.columns})

tdxquant-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: tdxquant
+Version: 0.1.0
+Summary: 通达信量化(TdxQuant) HTTP SDK —— 统一返回 DataFrame，字段金融规范化(snake_case)
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: orjson>=3.11.9
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# tdx-api
+
+通达信量化（TdxQuant）**HTTP SDK** —— 直接调用通达信客户端官方 HTTP 接口（`POST http://127.0.0.1:17709/`），统一返回 `pandas.DataFrame`，字段重命名为金融行业规范的 **snake_case**。
+
+## 工作方式
+
+通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）：
+
+```
+你的代码(SDK) ──HTTP/JSON──► 通达信客户端(127.0.0.1:17709)
+```
+
+1. 启动支持 TQ 的通达信客户端（它会监听 `127.0.0.1:17709`）
+2. SDK 直接 POST 调用，字段重命名 + DataFrame 封装在 SDK 内完成
+
+> 请求格式：`{"id":1, "method":"<tqcenter方法名>", "params":{...}}`，`method` 为 tqcenter 函数名，`params` 为底层参数名。
+
+## 安装
+
+```bash
+uv sync          # 本地开发
+# 或 pip install -e .
+```
+
+> 需要 Python ≥ 3.13、通达信金融终端（量化模拟版 / 专业研究版等支持 TQ 策略的版本）。
+
+## 快速开始
+
+```python
+from tdx_api import TdxAPI
+
+api = TdxAPI()   # 默认 http://127.0.0.1:17709，需通达信客户端在线
+
+# K线（OHLCV 长表）
+df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
+# 实时快照
+snap = api.get_snapshot("000001.SZ")
+# 股票 / 板块 / ETF
+api.get_stock_list()                   # 所有分类合并(带 market/category 列)
+api.get_sector_list()
+api.get_track_etf("000300.SH")
+# 财务
+api.get_financial("600519.SH", fields=["Fn193","Fn194"], start_date="20240101")
+# 交易日历
+api.get_trading_calendar("20260101", "20260613")
+```
+
+从别的机器调用：`TdxAPI(base_url="http://通达信机器IP:17709")`。
+
+## 接口总览
+
+| 类别 | 方法 | 说明 |
+|---|---|---|
+| 行情 | `get_kline` | K线（OHLCV 长表） |
+| | `get_snapshot` | 实时快照（五档） |
+| | `get_instrument_info` / `get_more_info` | 基本信息 |
+| | `get_dividend_factors` | 分红送配 |
+| 财务 | `get_financial` / `get_financial_by_date` | 专业财务（FNxxx） |
+| | `get_stock_trade_data(_by_date)` | 股票交易（GPx） |
+| | `get_sector_trade_data(_by_date)` | 板块交易（BKx） |
+| | `get_market_trade_data(_by_date)` | 市场交易（SCx） |
+| | `get_stock_single_data` | 单点数据（GOx） |
+| | `get_share_capital(_by_date)` | 股本数据 |
+| 板块 | `get_stock_list` | 分类成分股（market 不传返回全部，带 market/category 列） |
+| | `get_sector_list` / `get_user_sectors` | 板块列表 |
+| | `get_sector_stocks` | 板块成分股 |
+| 证券 | `get_convertible_bond` | 可转债 |
+| | `get_ipo_info` | 新股/新债申购 |
+| | `get_track_etf` | 跟踪指数的 ETF |
+| 日历 | `get_trading_dates` / `get_trading_calendar` | 交易日 |
+
+> 交易类（`order_stock`）按需求不做。完整参数与字段说明见 [`docs/api_reference.md`](docs/api_reference.md)。
+
+## 字段命名规范
+
+- 全部 **snake_case 小写**，采用金融行业惯例（OHLCV / bid-ask / nav / pct_chg）。
+- 原字段 → 新字段完整血缘见 [`docs/field_lineage.md`](docs/field_lineage.md)。
+- 通达信专业编码字段（`FNxxx`/`GPx` 等）保留转小写，需对照通达信字段手册。
+
+代码格式：`000001.SZ` / `600519.SH`（6 位 + 市场后缀）；频率 `daily/5min/...`；
+复权 `none/qfq/hfq`；日期严格 `YYYYMMDD`（区间用 `start_date`/`end_date`，按日期点用 `date`）。
+
+## 测试
+
+```bash
+uv run pytest                     # 单元测试（字段血缘契约 + 拼装逻辑）
+uv run pytest --runintegration    # 集成测试（需通达信客户端在线）
+```
+
+## 项目结构
+
+```
+tdx_api/
+├── client.py          # HTTP 客户端（POST 17709）+ DataFrame 拼装
+├── schema.py          # 字段血缘映射表（唯一真实来源）
+├── enums.py           # Freq / Adjust 枚举 + validate_date 日期校验
+├── exceptions.py      # 异常
+└── api/               # 各业务接口（mixin）
+    ├── market.py  financial.py  sector.py  instrument.py  calendar.py
+```
+
+## 常见问题
+
+- **`server return none` / 连接失败**：确认通达信客户端已启动并登录行情；SDK 默认连 `127.0.0.1:17709`。
+- **`502 Bad Gateway`**：本机代理（Clash/V2Ray）劫持 localhost 请求。SDK 已默认 `trust_env=False` 直连，若仍异常请关闭代理。
+- **财务/专业数据为空**：需先在通达信客户端下载对应盘后/专业财务数据。
+- **`get_financial` 报 end_time 缺失**：底层要求结束日期，`end_date` 留空时 SDK 自动取当天。

tdxquant-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+tdx_api/__init__.py,sha256=unm9Wof0jH3PVi44LnHeIYMDoSNAIhPP_L-J5ekLhVY,1653
+tdx_api/client.py,sha256=snxqm-4SL6gRNrCmSHHn4CjprHCct2G9Nlk14LkhERE,6769
+tdx_api/enums.py,sha256=yq3eZzyeGNDlXlOr6uns9bIQEUgl3FejyvKEHyhq2UU,3347
+tdx_api/exceptions.py,sha256=uf4lJd_obfKMyWnKa2Fjp_AC8vaLzaTOqi39JLgbYvc,489
+tdx_api/schema.py,sha256=4Ge1mDI9LpR7B_zrBETNPg9yY8-1i3AbebgtgCcusW4,6696
+tdx_api/api/__init__.py,sha256=60yb9xd8Y3jFLTPCiAfH_uy3d5BUcE-dwe2GGvpaUyk,456
+tdx_api/api/calendar.py,sha256=WPgM0-TtHB2CO0fyfUvJds9vNejmjPbVlMMk1g5p5nE,1880
+tdx_api/api/financial.py,sha256=9Bgwl4Pi8eyS1r6KD9qMvBmRKyefv33kC0exySawQ3I,8280
+tdx_api/api/instrument.py,sha256=GwOjeWnBOzRafeDeA4lez3Hg8uAPDVS518pZzI5jwiw,2227
+tdx_api/api/market.py,sha256=foXfF_w2H_FoWUito7H7nofKGn7IEr99_CBwrd7rSDo,6709
+tdx_api/api/sector.py,sha256=ggXM1zf_iGfbW2Tv1HaYw7E7rmonGuGJySidn7m9X8k,4340
+tdxquant-0.1.0.dist-info/METADATA,sha256=Q-3NzioXkXAMJAmnBrZiG6CO_ParxSBkSLAlAb0yQ3k,4828
+tdxquant-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tdxquant-0.1.0.dist-info/RECORD,,

tdxquant-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any