feat：新增股票日K快照与同花顺板块成分股接口，修复分页 limit 重复取数

pyproject.toml

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

src/ftshare/apis/futures.py

@@ -298,6 +298,7 @@ def eastmoney_futures_position(
     def futures_minutes(
         self,
         symbol: Any | None = None,
+        symbols: Any | None = None,
         interval: Any | None = None,
         start: Any | None = None,
         end: Any | None = None,
@@ -308,17 +309,18 @@ def futures_minutes(
         as_dataframe: bool = True,
         **kwargs: Any,
     ) -> Any:
-        """期货历史分钟行情.
+        """期货历史分钟K线.
 
         Endpoint: ``api/v2/market/data/futures_minutes``.
         Method: ``GET``.
         Documented endpoint: ``futures_minutes``.
 
         Args:
-            symbol: 期货合约代码，带交易所短后缀 (type: string; required: Y).
+            symbol: 单个期货合约代码，带交易所短后缀；与 ``symbols`` 二选一 (type: string; required: N).
+            symbols: 1～20 个期货合约代码；支持重复参数、逗号分隔或列表；与 ``symbol`` 二选一 (type: string[]; required: N).
             interval: 分钟周期，默认 ``1min`` (type: string; required: N).
-            start: 起始时间戳，单位毫秒 (type: integer; required: N).
-            end: 结束时间戳，单位毫秒，不能单独传 (type: integer; required: N).
+            start: 起始时间戳，单位毫秒；必填 (type: integer; required: Y).
+            end: 结束时间戳，单位毫秒；必填，不能单独传 (type: integer; required: Y).
             limit: 返回条数上限，范围 1～1000 (type: integer; required: N).
             raw: Return the decoded JSON payload without tabular extraction.
             fields: Optional field list or comma-separated field string applied after extraction.
@@ -331,6 +333,7 @@ def futures_minutes(
         """
         request_params = {
             'symbol': symbol,
+            'symbols': symbols,
             'interval': interval,
             'start': start,
             'end': end,
@@ -345,7 +348,7 @@ def futures_minutes(
             **request_params,
         )
 
-    def futures_contract_kline(
+    def futures_kline(
         self,
         symbol: Any | None = None,
         interval: Any | None = None,
@@ -358,11 +361,11 @@ def futures_contract_kline(
         as_dataframe: bool = True,
         **kwargs: Any,
     ) -> Any:
-        """期货行情.
+        """期货合约历史K线.
 
         Endpoint: ``api/v1/market/data/futures/kline``.
         Method: ``GET``.
-        Documented endpoint: ``futures_contract_kline``.
+        Documented endpoint: ``futures_kline``.
 
         Args:
             symbol: 期货合约代码 (type: string; required: Y).
@@ -388,7 +391,57 @@ def futures_contract_kline(
         }
         request_params.update(kwargs)
         return self._call_endpoint(
-            'futures_contract_kline',
+            'futures_kline',
+            raw=raw,
+            fields=fields,
+            as_dataframe=as_dataframe,
+            **request_params,
+        )
+
+    def futures_kline_batch(
+        self,
+        symbols: Any | None = None,
+        interval: Any | None = None,
+        start: Any | None = None,
+        end: Any | None = None,
+        limit: Any | None = None,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """批量期货合约历史K线.
+
+        Endpoint: ``api/v2/market/data/futures/kline/batch``.
+        Method: ``GET``.
+        Documented endpoint: ``futures_kline_batch``.
+
+        Args:
+            symbols: 1～20 个期货合约代码；支持重复参数、逗号分隔或列表 (type: string[]; required: Y).
+            interval: K 线周期，默认 ``daily`` (type: string; required: N).
+            start: 起始时间戳，单位毫秒 (type: integer; required: N).
+            end: 结束时间戳，单位毫秒，不能单独传 (type: integer; required: N).
+            limit: 每个合约返回条数上限，默认 500 (type: integer; 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.
+
+        Returns:
+            A pandas ``DataFrame`` by default, Python rows when
+            ``as_dataframe=False``, or raw JSON when ``raw=True``.
+        """
+        request_params = {
+            'symbols': symbols,
+            'interval': interval,
+            'start': start,
+            'end': end,
+            'limit': limit,
+        }
+        request_params.update(kwargs)
+        return self._call_endpoint(
+            'futures_kline_batch',
             raw=raw,
             fields=fields,
             as_dataframe=as_dataframe,
@@ -430,6 +483,43 @@ def futures_minutes_realtime(
             as_dataframe=as_dataframe,
             **request_params,
         )
+
+    def futures_realtime_day_kline(
+        self,
+        symbols: Any | None = None,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """期货实时日K线.
+
+        Endpoint: ``api/v4/market/data/futures-realtime-day-kline``.
+        Method: ``GET``.
+        Documented endpoint: ``futures_realtime_day_kline``.
+
+        Args:
+            symbols: 1～20 个期货合约代码；支持重复参数、逗号分隔或列表 (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.
+
+        Returns:
+            A pandas ``DataFrame`` by default, Python rows when
+            ``as_dataframe=False``, or raw JSON when ``raw=True``.
+        """
+        request_params = {'symbols': symbols}
+        request_params.update(kwargs)
+        return self._call_endpoint(
+            'futures_realtime_day_kline',
+            raw=raw,
+            fields=fields,
+            as_dataframe=as_dataframe,
+            **request_params,
+        )
+
     def fut_wsr(
         self,
         trade_date: Any | None = None,

src/ftshare/apis/stock.py

@@ -1104,20 +1104,32 @@ def company_list(
     def eastmoney_board_constituents(
         self,
         board_code: Any | None = None,
+        date: 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/eastmoney-board-constituents``.
         Method: ``GET``.
         Documented endpoint: ``eastmoney_board_constituents``.
 
         Args:
-            board_code: 板块代码，如 BK1024 (type: string; required: Y).
+            board_code: 板块代码，取东方财富板块代码（BK 开头），如 BK0475、BK0490、BK0153 (type: string; required: Y).
+            date: 查询日期，格式 YYYYMMDD；不传返回当前仍在板块内的成分股 (type: string; required: N).
+            page: Page number, starting from 1. If omitted, the server default is used unless ``limit`` or ``all_pages`` is set.
+            page_size: Rows per page. The SDK validates this against the endpoint-specific maximum.
+            limit: Maximum number of rows to return. The SDK may fetch multiple pages to satisfy this limit.
+            all_pages: Fetch and combine pages until the server reports the last page.
+            max_pages: Optional safety cap for ``all_pages``.
             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.
@@ -1128,10 +1140,17 @@ def eastmoney_board_constituents(
             ``as_dataframe=False``, raw JSON when ``raw=True``, or raw page
             payloads when multi-page fetching is used with ``raw=True``.
         """
-        request_params = {'board_code': board_code}
+        request_params = {'board_code': board_code, 'date': date}
         request_params.update(kwargs)
-        return self._call_endpoint(
-            'eastmoney_board_constituents',
+        path = ENDPOINTS['eastmoney_board_constituents'].path
+        return self.get_paginated(
+            path,
+            page=page,
+            page_size=page_size,
+            limit=limit,
+            all_pages=all_pages,
+            max_pages=max_pages,
+            max_page_size=ENDPOINTS['eastmoney_board_constituents'].max_page_size,
             raw=raw,
             fields=fields,
             as_dataframe=as_dataframe,
@@ -1695,6 +1714,33 @@ def stk_code_change(
         request_params.update(kwargs)
         return self._call_endpoint('stk_code_change', raw=raw, fields=fields, as_dataframe=as_dataframe, **request_params)
 
+    def stk_code_change_timeline(
+        self,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """A股代码变更时间线.
+
+        Endpoint: ``api/v1/market/data/stk_code_change_timeline``.
+        Method: ``GET``.
+        Documented endpoint: ``stk_code_change_timeline``.
+
+        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``.
+        """
+        request_params = dict(kwargs)
+        return self._call_endpoint('stk_code_change_timeline', raw=raw, fields=fields, as_dataframe=as_dataframe, **request_params)
+
     def stk_status_change(
         self,
         trade_code: Any | None = None,
@@ -3881,6 +3927,12 @@ def stock_share(
         self,
         stock_code: Any | None = None,
         date: Any | None = None,
+        date_type: 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,
@@ -3889,13 +3941,19 @@ def stock_share(
     ) -> Any:
         """股本.
 
-        Endpoint: ``api/v1/market/data/share/get-stock-share``.
+        Endpoint: ``api/v2/market/data/share/get-stock-share``.
         Method: ``GET``.
         Documented endpoint: ``get_stock_share``.
 
         Args:
-            stock_code: 股票代码 (type: string; required: Y).
+            stock_code: 股票代码；不传时查询指定日期的全市场股本 (type: string; required: N).
             date: 日期 YYYYMMDD (type: string; required: Y).
+            date_type: 日期条件类型：``publish_date``（发布日期，默认）或 ``end_date``（生效日期） (type: string; required: N).
+            page: Page number, starting from 1. If omitted, the server default is used unless ``limit`` or ``all_pages`` is set.
+            page_size: Rows per page. The SDK validates this against the endpoint-specific maximum.
+            limit: Maximum number of rows to return. The SDK may fetch multiple pages to satisfy this limit.
+            all_pages: Fetch and combine pages until the server reports the last page.
+            max_pages: Optional safety cap for ``all_pages``.
             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.
@@ -3906,13 +3964,64 @@ def stock_share(
             ``as_dataframe=False``, raw JSON when ``raw=True``, or raw page
             payloads when multi-page fetching is used with ``raw=True``.
         """
-        request_params = {'stock_code': stock_code, 'date': date}
+        request_params = {'stock_code': stock_code, 'date': date, 'date_type': date_type}
         request_params.update(kwargs)
-        return self._call_endpoint(
-            'stock_share',
+        endpoint = ENDPOINTS['stock_share']
+        return self.get_paginated(
+            endpoint.path,
+            page=page,
+            page_size=page_size,
+            limit=limit,
+            all_pages=all_pages,
+            max_pages=max_pages,
+            max_page_size=endpoint.max_page_size,
+            raw=raw,
+            fields=fields,
+            as_dataframe=as_dataframe,
+            **request_params,
+        )
+
+    def stock_factor(
+        self,
+        symbol: Any | None = None,
+        trade_date: Any | None = None,
+        category: Any | None = None,
+        *,
+        raw: bool = False,
+        fields: Sequence[str] | str | None = None,
+        as_dataframe: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """股票技术面因子.
+
+        Endpoint: ``api/v2/market/data/stock-factor``.
+        Method: ``GET``.
+        Documented endpoint: ``market_stock_factor``.
+
+        Args:
+            symbol: 沪深北 A 股代码，必须带交易所后缀，如 ``000001.SZ`` (type: string; required: Y).
+            trade_date: 目标日期 YYYYMMDD；不传时以当前日期为目标日期 (type: string; required: N).
+            category: 返回字段分类：``quote``、``valuation``、``capital``、``trend``、``momentum``、``volatility``、``volume`` 或 ``sentiment``；不传时返回全部字段 (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.
+
+        Returns:
+            A pandas ``DataFrame`` by default, Python rows when
+            ``as_dataframe=False``, raw JSON when ``raw=True``。服务端把因子放在
+            ``data.values``，SDK 直接返回该对象（``as_dataframe=True`` 时为单行
+            ``DataFrame``）。
+        """
+        request_params = {'symbol': symbol, 'trade_date': trade_date, 'category': category}
+        request_params.update(kwargs)
+        path = ENDPOINTS['stock_factor'].path
+        return self.get(
+            path,
             raw=raw,
             fields=fields,
             as_dataframe=as_dataframe,
+            unwrap_bare_data=True,
             **request_params,
         )
 
@@ -4738,3 +4847,15 @@ def news_reaction_snapshot(self, symbol: Any | None = None, start_date: Any | No
         params.update(kwargs)
         path = ENDPOINTS['news_reaction_snapshot'].path
         return self.get_paginated(path, page=page, page_size=page_size, limit=limit, all_pages=all_pages, max_pages=max_pages, max_page_size=200, raw=raw, fields=fields, as_dataframe=as_dataframe, **params)
+
+    def stock_candlesticks_daily(self, trade_date: 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:
+        """股票日K快照."""
+        params = {'trade_date': trade_date}
+        params.update(kwargs)
+        return self.get_paginated(ENDPOINTS['stock_candlesticks_daily'].path, page=page, page_size=page_size, limit=limit, all_pages=all_pages, max_pages=max_pages, max_page_size=500, raw=raw, fields=fields, as_dataframe=as_dataframe, **params)
+
+    def ths_board_constituents(self, board_code: Any | None = None, board_name: Any | None = None, board_type: Any | None = None, date: 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:
+        """同花顺板块成分股."""
+        params = {'board_code': board_code, 'board_name': board_name, 'board_type': board_type, 'date': date}
+        params.update(kwargs)
+        return self.get_paginated(ENDPOINTS['ths_board_constituents'].path, page=page, page_size=page_size, limit=limit, all_pages=all_pages, max_pages=max_pages, max_page_size=1000, raw=raw, fields=fields, as_dataframe=as_dataframe, **params)