Merge pull request #16 from FTShare-Lab/howe_dev

feat: 新增股票历史ST状态接口

Author: Yumetski

docs/API_REFERENCE.md

@@ -6,13 +6,13 @@
 
 | 指标 | 数量 |
 |---|---:|
-| SDK 方法总数 | 227 |
+| SDK 方法总数 | 228 |
 
 ## 专题分布
 
 | ftshare-doc 专题 | SDK 方法数 | API mixin 模块 | Endpoint 模块 |
 |---|---:|---|---|
-| 股票数据 | 119 | `ftshare.apis.stock` | `ftshare.endpoints.stock` |
+| 股票数据 | 120 | `ftshare.apis.stock` | `ftshare.endpoints.stock` |
 | 港股数据 | 3 | `ftshare.apis.hk` | `ftshare.endpoints.hk` |
 | 美股数据 | 2 | `ftshare.apis.us` | `ftshare.endpoints.us` |
 | 指数专题 | 15 | `ftshare.apis.index` | `ftshare.endpoints.index` |
@@ -133,6 +133,7 @@
 | [`stock_realtime_minute_kline`](#api-stock-realtime-minute-kline) | 股票实时分钟K线 | `GET` | `api/v4/market/data/stock-realtime-minute-kline` | `symbols` | `股票实时分钟K线.md` |
 | [`stock_share`](#api-stock-share) | 股本 | `GET` | `api/v2/market/data/share/get-stock-share` | `stock_code`, `date` | `股本.md` |
 | [`stock_share_chg`](#api-stock-share-chg) | 股东增减持 | `GET` | `api/v1/market/data/holder/stock-share-chg` | `stock_code`, `is_last`, `page`, `page_size` | `股东增减持.md` |
+| [`stock_st_history`](#api-stock-st-history) | 股票历史ST状态 | `GET` | `api/v1/market/data/stock-st-history` | `symbol`, `st_type` | `股票历史ST状态.md` |
 | [`stock_unlock`](#api-stock-unlock) | 限售解禁 | `GET` | `api/v1/market/data/unlock/stock_unlock` | `stock_code`, `start_date`, `end_date`, `page`, `page_size` | `限售解禁.md` |
 | [`supply_chain_company_supply_chain_companies`](#api-supply-chain-company-supply-chain-companies) | 供应链公司候选 | `GET` | `api/v3/market/data/supply-chain/company-supply-chain-companies` | `trade_code`, `direction`, `page`, `page_size` | `供应链公司候选.md` |
 | [`supply_chain_subindustry_subsubindustries`](#api-supply-chain-subindustry-subsubindustries) | 供应链子行业层级展开 | `GET` | `api/v3/market/data/supply-chain/subindustry-subsubindustries` | `industry_name` | `供应链子行业层级展开.md` |
@@ -2823,6 +2824,31 @@ Returns:
     payloads when multi-page fetching is used with ``raw=True``.
 ```
 
+<h4 id="api-stock-st-history"><code>stock_st_history</code></h4>
+
+- 接口名称：股票历史ST状态
+- HTTP：`GET`
+- Path：`api/v1/market/data/stock-st-history`
+- 参数：`symbol`, `st_type`
+- 来源文档：`股票历史ST状态.md`
+- 原始接口：`stock_st_history`
+
+```text
+股票历史ST状态.
+
+Endpoint: ``api/v1/market/data/stock-st-history``.
+Method: ``GET``.
+Documented endpoint: ``stock_st_history``.
+
+Args:
+    symbol: 股票代码（带 .SH/.SZ 后缀），逗号分隔支持批量，去重后最多 50 只 (type: string; required: Y).
+    st_type: 阶段类型过滤，取值 ST / *ST / PT / 退市整理期 (type: string; required: N).
+    raw: Return the decoded JSON payload without tabular extraction.
+    fields: Optional field list or comma-separated field string applied after extraction.
+    as_dataframe: Return a pandas ``DataFrame`` by default; set to ``False`` for Python rows.
+    **kwargs: Extra request parameters forwarded unchanged. Useful when the service adds parameters before the SDK is regenerated.
+```
+
 <h4 id="api-stock-unlock"><code>stock_unlock</code></h4>
 
 - 接口名称：限售解禁

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ftshare"
-version = "1.0.5"
+version = "1.0.6"
 description = "Python SDK for FTShare market data APIs."
 readme = "README.md"
 requires-python = ">=3.9"

src/ftshare/apis/stock.py

@@ -4192,3 +4192,23 @@ def stock_minutes_batch(self, symbols: Any | None = None, interval_value: Any |
         params = {'symbols': symbols, 'interval_value': interval_value, 'adjust_kind': adjust_kind, 'since_ts_millis': since_ts_millis, 'until_ts_millis': until_ts_millis, 'limit': limit}
         params.update(kwargs)
         return self._call_endpoint('stock_minutes_batch', raw=raw, fields=fields, as_dataframe=as_dataframe, **params)
+
+
+    def stock_st_history(self, symbol: Any | None = None, st_type: Any | None = None, *, raw: bool = False, fields: Sequence[str] | str | None = None, as_dataframe: bool = True, **kwargs: Any) -> Any:
+        """股票历史ST状态.
+
+        Endpoint: ``api/v1/market/data/stock-st-history``.
+        Method: ``GET``.
+        Documented endpoint: ``stock_st_history``.
+
+        Args:
+            symbol: 股票代码（带 .SH/.SZ 后缀），逗号分隔支持批量，去重后最多 50 只 (type: string; required: Y).
+            st_type: 阶段类型过滤，取值 ST / *ST / PT / 退市整理期 (type: string; required: N).
+            raw: Return the decoded JSON payload without tabular extraction.
+            fields: Optional field list or comma-separated field string applied after extraction.
+            as_dataframe: Return a pandas ``DataFrame`` by default; set to ``False`` for Python rows.
+            **kwargs: Extra request parameters forwarded unchanged. Useful when the service adds parameters before the SDK is regenerated.
+        """
+        params = {'symbol': symbol, 'st_type': st_type}
+        params.update(kwargs)
+        return self._call_endpoint('stock_st_history', raw=raw, fields=fields, as_dataframe=as_dataframe, **params)

src/ftshare/endpoints/stock.py

@@ -909,4 +909,12 @@
         'params': ('symbol', 'since_date', 'until_date', 'page', 'page_size'),
     },
 
+    'stock_st_history': {
+        'path': 'api/v1/market/data/stock-st-history',
+        'title': '股票历史ST状态',
+        'doc_file': '股票历史ST状态.md',
+        'original_api': 'stock_st_history',
+        'params': ('symbol', 'st_type'),
+    },
+
 })

tests/endpoint_cases.py

@@ -117,6 +117,7 @@
     "start_date": "20260701",
     "start_week": "202628",
     "start_time": "09:30:00",
+    "st_type": "*ST",
     "stat_date": "20260717",
     "stati_perd": "日",
     "stock_code": "000001.SZ",

tests/test_client.py

@@ -83,6 +83,24 @@ def test_new_endpoints_forward_documented_parameters():
     assert session.calls[4]["params"] == {"n": 5}
 
 
+def test_stock_st_history_forwards_documented_parameters():
+    session = FakeSession(
+        [
+            FakeResponse(payload={"code": 200, "message": "success", "data": [{"symbol": "600735.SH", "st_type": "ST"}]}),
+            FakeResponse(payload={"code": 200, "message": "success", "data": []}),
+        ]
+    )
+    client = FtshareClient(session=session)
+
+    rows = client.stock_st_history(symbol="600735.SH,000004.SZ", as_dataframe=False)
+    client.stock_st_history(symbol="000004.SZ", st_type="退市整理期", as_dataframe=False)
+
+    assert session.calls[0]["url"] == "https://market.ft.tech/gateway/api/v1/market/data/stock-st-history"
+    assert session.calls[0]["params"] == {"symbol": "600735.SH,000004.SZ"}
+    assert rows == [{"symbol": "600735.SH", "st_type": "ST"}]
+    assert session.calls[1]["params"] == {"symbol": "000004.SZ", "st_type": "退市整理期"}
+
+
 def test_stock_ggcg_em_rejects_page_size_above_200():
     client = FtshareClient(session=FakeSession([]))