按 ftshare-doc 适配 SDK 接口

.gitignore

@@ -34,6 +34,12 @@ htmlcov/
 # Logs / runtime
 *.log
 
+# Local API documentation checkout used to regenerate SDK metadata
+ftshare-doc/
+
+# Local SDK verification workspace; not shipped with package releases
+sdk_smoke_test/
+
 # Secrets / env
 .env
 .env.local

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-06-29
+
+### Changed
+- Default `base_url` changed from `https://market.ft.tech/data/` to `https://market.ft.tech/gateway/`.
+- Endpoint and API mixin registries are now split by `ftshare-doc/api-doc` topic.
+- SDK coverage updated to 179 market-data endpoints.
+
 ## [0.1.0] - 2026-06-23
 
 ### Added

README.md

@@ -26,7 +26,13 @@ Agent 应用                # 面向最终用户的投研分析体验
 
 ## 安装
 
-克隆仓库并以可编辑模式安装（含测试依赖）：
+通过 PyPI 安装：
+
+```bash
+pip install ftshare
+```
+
+本地开发时，克隆仓库并以可编辑模式安装（含测试依赖）：
 
 ```bash
 git clone git@github.com:ftshare-lab/ftshare-python-sdk.git
@@ -110,23 +116,23 @@ with ft.market_api(timeout=20) as market:
 import ftshare as ft
 
 print(ft.BASE_URL)
-# https://market.ft.tech/data/
+# https://market.ft.tech/gateway/
 ```
 
 全局修改，影响之后创建的新客户端：
 
 ```python
-ft.set_base_url("https://market.ft.tech/data/")
+ft.set_base_url("https://market.ft.tech/gateway/")
 market = ft.market_api()
 ```
 
 只修改某个客户端：
 
 ```python
-market = ft.market_api(base_url="https://market.ft.tech/data/")
+market = ft.market_api(base_url="https://market.ft.tech/gateway/")
 ```
 
-SDK 会规范化 URL，`https://host/data` 和 `https://host/data/` 都可以。
+SDK 会规范化 URL，`https://host/gateway` 和 `https://host/gateway/` 都可以。
 
 ## 返回类型
 
@@ -367,10 +373,10 @@ src/ftshare/
   client.py            # FtshareClient 组合类和 market_api 工厂
   config.py            # BASE_URL、默认分页大小和全局配置
   dataframe.py         # pandas DataFrame 转换
-  endpoints.py         # 接口 path 注册表
+  endpoints/           # 按 ftshare-doc 专题拆分的接口注册表
   exceptions.py        # SDK 异常类型
   fields.py            # fields 参数解析和列筛选
   pagination.py        # page/page_size/limit/max_pages 校验
   response.py          # API 业务错误、records/items 提取、总页数解析
-  apis/                # 按业务域组织的接口 mixin
+  apis/                # 按 ftshare-doc 专题拆分的接口 mixin
 ```

pyproject.toml

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

src/ftshare/__init__.py

@@ -43,8 +43,8 @@ def set_base_url(url: str) -> str:
     """Set the package-level base URL used by new clients.
 
     Args:
-        url: API base URL. Both ``https://host/data`` and
-            ``https://host/data/`` are accepted.
+        url: API base URL. Both ``https://host/gateway`` and
+            ``https://host/gateway/`` are accepted.
 
     Returns:
         The normalized base URL.

src/ftshare/apis/__init__.py

@@ -1,33 +1,31 @@
-"""Business-domain API mixins used by ``FtshareClient``."""
+"""ftshare-doc topic API mixins used by ``FtshareClient``."""
 
-from .corporate import CorporateApiMixin
-from .economic import EconomicApiMixin
+from .stock import StockApiMixin
+from .hk import HkApiMixin
+from .us import UsApiMixin
+from .index import IndexApiMixin
 from .etf import EtfApiMixin
-from .finance import FinanceApiMixin
 from .fund import FundApiMixin
 from .futures import FuturesApiMixin
-from .global_index import GlobalIndexApiMixin
-from .goodwill import GoodwillApiMixin
-from .hk import HkApiMixin
-from .holder import HolderApiMixin
-from .index import IndexApiMixin
-from .market import MarketApiMixin
-from .pledge import PledgeApiMixin
-from .stock import StockApiMixin
+from .bond import BondApiMixin
+from .economic import EconomicApiMixin
+from .llm_corpus import LlmCorpusApiMixin
+from .spot import SpotApiMixin
+from .forex import ForexApiMixin
+from .unpublished import UnpublishedApiMixin
 
 __all__ = [
-    'CorporateApiMixin',
-    'EconomicApiMixin',
+    'StockApiMixin',
+    'HkApiMixin',
+    'UsApiMixin',
+    'IndexApiMixin',
     'EtfApiMixin',
-    'FinanceApiMixin',
     'FundApiMixin',
     'FuturesApiMixin',
-    'GlobalIndexApiMixin',
-    'GoodwillApiMixin',
-    'HkApiMixin',
-    'HolderApiMixin',
-    'IndexApiMixin',
-    'MarketApiMixin',
-    'PledgeApiMixin',
-    'StockApiMixin',
+    'BondApiMixin',
+    'EconomicApiMixin',
+    'LlmCorpusApiMixin',
+    'SpotApiMixin',
+    'ForexApiMixin',
+    'UnpublishedApiMixin',
 ]

src/ftshare/apis/bond.py

@@ -0,0 +1,84 @@
+"""Bond API methods grouped by ftshare-doc."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from ..endpoints import ENDPOINTS
+
+
+class BondApiMixin:
+    """Endpoint methods for the bond ftshare-doc topic."""
+
+    def cb_base_data(
+        self,
+        symbol_code: Any | None = None,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """可转债基础数据.
+
+        Endpoint: ``api/v1/market/data/cb/cb-base-data``.
+        Method: ``GET``.
+        Documented endpoint: ``get_cb_base_data_handler``.
+
+        Args:
+            symbol_code: 转债代码 (type: string; required: Y).
+            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.
+
+        Returns:
+            A pandas ``DataFrame`` by default, Python rows when
+            ``as_dataframe=False``, raw JSON when ``raw=True``, or raw page
+            payloads when multi-page fetching is used with ``raw=True``.
+        """
+        request_params = {'symbol_code': symbol_code}
+        request_params.update(kwargs)
+        return self._call_endpoint(
+            'cb_base_data',
+            raw=raw,
+            fields=fields,
+            as_dataframe=as_dataframe,
+            **request_params,
+        )
+
+    def cb_lists(
+        self,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """可转债列表.
+
+        Endpoint: ``api/v1/market/data/cb/cb-lists``.
+        Method: ``GET``.
+        Documented endpoint: ``get_cb_lists_handler``.
+
+        Args:
+            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.
+
+        Returns:
+            A pandas ``DataFrame`` by default, Python rows when
+            ``as_dataframe=False``, raw JSON when ``raw=True``, or raw page
+            payloads when multi-page fetching is used with ``raw=True``.
+        """
+        request_params = {}
+        request_params.update(kwargs)
+        return self._call_endpoint(
+            'cb_lists',
+            raw=raw,
+            fields=fields,
+            as_dataframe=as_dataframe,
+            **request_params,
+        )