diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
index ac7a74e..3b238eb 100644
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -102,7 +102,7 @@
| [`stock_comment_score_em`](#api-stock-comment-score-em) | 千股千评评分 | `GET` | `api/v1/market/data/stock-comment/score` | `symbol` | `千股千评评分.md` |
| [`stock_connect_members`](#api-stock-connect-members) | 互联互通成份 | `GET` | `api/v1/market/data/stock-connect-members` | `direction`, `channel`, `page`, `page_size` | `互联互通成份.md` |
| [`stock_daec_stocks`](#api-stock-daec-stocks) | A股行情列表 | `GET` | `api/v1/market/data/daec/stocks/{board}` | `board`, `page`, `page_size`, `filter`, `order_by` | `A股行情列表.md` |
-| [`stock_description_all`](#api-stock-description-all) | 股票基础信息 | `GET` | `api/v1/market/data/stock-description-all` | - | `股票基础信息.md` |
+| [`stock_description`](#api-stock-description) | 股票基础信息 | `GET` | `api/v1/market/data/stock-description` | `symbol_id`, `page`, `page_size` | `股票基础信息.md` |
| [`stock_dividends`](#api-stock-dividends) | 股票分红记录 | `GET` | `api/v1/market/data/stock-dividends` | `symbol`, `since_date`, `until_date`, `page`, `page_size` | `股票分红记录.md` |
| [`stock_filter`](#api-stock-filter) | 股票筛选 | `GET` | `api/v2/market/data/stock-list/filter` | `symbol`, `board`, `listing_date_since`, `page`, `page_size` | `股票筛选.md` |
| [`stock_float_holders`](#api-stock-float-holders) | 十大流通股东 | `GET` | `api/v1/market/data/holder/stock-holder-ften` | `stock_code`, `is_last`, `page`, `page_size` | `十大流通股东.md` |
@@ -2068,14 +2068,14 @@ Returns:
payloads when multi-page fetching is used with ``raw=True``.
```
-
stock_description_all
+stock_description
- 接口名称:股票基础信息
- HTTP:`GET`
-- Path:`api/v1/market/data/stock-description-all`
-- 参数:-
+- Path:`api/v1/market/data/stock-description`
+- 参数:`symbol_id`, `page`, `page_size`
- 来源文档:`股票基础信息.md`
-- 原始接口:`stock_description_all`
+- 原始接口:`stock_description`
```text
股票基础信息.
diff --git a/pyproject.toml b/pyproject.toml
index 9b42ff0..c863f36 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "ftshare"
-version = "1.0.1"
+version = "1.0.2"
description = "Python SDK for FTShare market data APIs."
readme = "README.md"
requires-python = ">=3.9"
diff --git a/src/ftshare/apis/stock.py b/src/ftshare/apis/stock.py
index dd0705b..d8bbc8d 100644
--- a/src/ftshare/apis/stock.py
+++ b/src/ftshare/apis/stock.py
@@ -3707,11 +3707,41 @@ def stock_unlock(
as_dataframe=as_dataframe,
**request_params,
)
- def stock_description_all(self, page: int | None = None, page_size: int | None = None, *, raw: bool = False, fields: Sequence[str] | str | None = None, as_dataframe: bool = True, **kwargs: Any) -> Any:
- """股票基础信息."""
- params = {'page': page, 'page_size': page_size}
+ def stock_description(
+ self,
+ symbol_id: Any | None = None,
+ page: int | None = None,
+ page_size: int | None = None,
+ limit: int | None = None,
+ all_pages: bool = False,
+ max_pages: int | None = None,
+ *,
+ raw: bool = False,
+ fields: Sequence[str] | str | None = None,
+ as_dataframe: bool = True,
+ **kwargs: Any,
+ ) -> Any:
+ """股票基础信息.
+
+ Endpoint: ``api/v1/market/data/stock-description``.
+ Method: ``GET``.
+ Documented endpoint: ``stock_description``.
+ """
+ params = {'symbol_id': symbol_id}
params.update(kwargs)
- return self._call_endpoint('stock_description_all', raw=raw, fields=fields, as_dataframe=as_dataframe, **params)
+ return self.get_paginated(
+ ENDPOINTS['stock_description'].path,
+ page=page,
+ page_size=page_size,
+ limit=limit,
+ all_pages=all_pages,
+ max_pages=max_pages,
+ max_page_size=ENDPOINTS['stock_description'].max_page_size,
+ raw=raw,
+ fields=fields,
+ as_dataframe=as_dataframe,
+ **params,
+ )
def tdx_board_index(self, ts_code: Any | None = None, idx_name: Any | None = None, idx_type: Any | None = None, idx_type_code: Any | None = None, market: Any | None = None, page: int | None = None, page_size: int | None = None, *, raw: bool = False, fields: Sequence[str] | str | None = None, as_dataframe: bool = True, **kwargs: Any) -> Any:
diff --git a/src/ftshare/endpoints/stock.py b/src/ftshare/endpoints/stock.py
index 8ef4ab0..b7f616c 100644
--- a/src/ftshare/endpoints/stock.py
+++ b/src/ftshare/endpoints/stock.py
@@ -546,11 +546,13 @@
'original_api': 'get_yzxdr_detail',
'params': ('year', 'quarter', 'stock_code', 'page', 'page_size'),
},
- 'stock_description_all': {
- 'path': 'api/v1/market/data/stock-description-all',
+ 'stock_description': {
+ 'path': 'api/v1/market/data/stock-description',
'title': '股票基础信息',
'doc_file': '股票基础信息.md',
- 'original_api': 'stock_description_all',
+ 'original_api': 'stock_description',
+ 'params': ('symbol_id', 'page', 'page_size'),
+ 'max_page_size': 200,
},
'tdx_board_index': {
diff --git a/tests/test_client.py b/tests/test_client.py
index bbc5beb..6346860 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -288,7 +288,34 @@ def test_new_batch_endpoints_forward_symbols_and_documented_parameters():
assert session.calls[0]["params"] == kwargs
-def test_new_paginated_endpoints_use_documented_page_size_limits():
+def test_stock_description_uses_paginated_route_and_filters():
+ session = FakeSession([FakeResponse(payload=paginated_records([{"symbol": "600000.SH"}]))])
+ client = FtshareClient(session=session)
+
+ rows = client.stock_description(
+ symbol_id="600000.SH",
+ page=1,
+ page_size=1,
+ as_dataframe=False,
+ )
+
+ assert rows == [{"symbol": "600000.SH"}]
+ assert session.calls[0]["url"] == "https://market.ft.tech/gateway/api/v1/market/data/stock-description"
+ assert session.calls[0]["params"] == {
+ "symbol_id": "600000.SH",
+ "page": 1,
+ "page_size": 1,
+ }
+
+
+def test_stock_description_rejects_page_size_above_200():
+ client = FtshareClient(session=FakeSession([]))
+
+ with pytest.raises(ValueError, match="page_size must be between 1 and 200"):
+ client.stock_description(page_size=201)
+
+
+
session = FakeSession([FakeResponse(payload=paginated_records([]))] * 2)
client = FtshareClient(session=session)