From ad0eabe948b313b6ae5a112766cb83480bc7d691 Mon Sep 17 00:00:00 2001
From: zhuhao <zhuhao@ft.tech>
Date: Fri, 4 Sep 2026 11:59:53 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat=EF=BC=9A=E9=80=82=E9=85=8D=E8=82=A1?=
 =?UTF-8?q?=E7=A5=A8=E5=9F=BA=E7=A1=80=E4=BF=A1=E6=81=AF=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E8=B0=83=E6=95=B4=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/API_REFERENCE.md          | 10 ++++-----
 src/ftshare/apis/stock.py      | 38 ++++++++++++++++++++++++++++++----
 src/ftshare/endpoints/stock.py |  8 ++++---
 tests/test_client.py           | 29 +++++++++++++++++++++++++-
 4 files changed, 72 insertions(+), 13 deletions(-)

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``.
 ```
 
-<h4 id="api-stock-description-all"><code>stock_description_all</code></h4>
+<h4 id="api-stock-description"><code>stock_description</code></h4>
 
 - 接口名称：股票基础信息
 - 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/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)
 

From 10c975dd696419ecebaa75a49325484b3c03c0a0 Mon Sep 17 00:00:00 2001
From: zhuhao <zhuhao@ft.tech>
Date: Fri, 4 Sep 2026 12:04:14 +0800
Subject: [PATCH 2/2] =?UTF-8?q?feat:=20sdk=E7=89=88=E6=9C=AC=E8=B0=83?=
 =?UTF-8?q?=E6=95=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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"