From 88d2c4bf85b7d04d89740a07be63a50f3229bb1d Mon Sep 17 00:00:00 2001 From: zhuhao Date: Thu, 17 Sep 2026 19:55:01 +0800 Subject: [PATCH] =?UTF-8?q?feat=EF=BC=9A=E5=90=8C=E6=AD=A5=20ftshare-doc?= =?UTF-8?q?=20=E6=96=B0=E5=A2=9E=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 可转债历史K线族（批量历史K线、历史分钟K线、实时日K线、实时分钟K线）、 股票跨日分时行情、招股书列表；可转债K线标题与来源文档更名为可转债历史K线。 API_REFERENCE 总数更新为 236。 --- docs/API_REFERENCE.md | 228 ++++++++++++++++++++++++++-- src/ftshare/apis/bond.py | 154 ++++++++++++++++++- src/ftshare/apis/llm_corpus.py | 58 +++++++ src/ftshare/apis/stock.py | 42 +++++ src/ftshare/endpoints/bond.py | 37 ++++- src/ftshare/endpoints/llm_corpus.py | 8 + src/ftshare/endpoints/stock.py | 7 + tests/endpoint_cases.py | 5 + tests/test_client.py | 99 ++++++++++++ 9 files changed, 615 insertions(+), 23 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 099e3ef..5aaa7e0 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -6,22 +6,22 @@ | 指标 | 数量 | |---|---:| -| SDK 方法总数 | 229 | +| SDK 方法总数 | 236 | ## 专题分布 | ftshare-doc 专题 | SDK 方法数 | API mixin 模块 | Endpoint 模块 | |---|---:|---|---| -| 股票数据 | 121 | `ftshare.apis.stock` | `ftshare.endpoints.stock` | +| 股票数据 | 124 | `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` | | ETF专题 | 17 | `ftshare.apis.etf` | `ftshare.endpoints.etf` | | 公募基金 | 18 | `ftshare.apis.fund` | `ftshare.endpoints.fund` | | 期货数据 | 18 | `ftshare.apis.futures` | `ftshare.endpoints.futures` | -| 债券专题 | 6 | `ftshare.apis.bond` | `ftshare.endpoints.bond` | +| 债券专题 | 10 | `ftshare.apis.bond` | `ftshare.endpoints.bond` | | 宏观经济 | 23 | `ftshare.apis.economic` | `ftshare.endpoints.economic` | -| 大模型语料 | 4 | `ftshare.apis.llm_corpus` | `ftshare.endpoints.llm_corpus` | +| 大模型语料 | 5 | `ftshare.apis.llm_corpus` | `ftshare.endpoints.llm_corpus` | | 现货数据 | 1 | `ftshare.apis.spot` | `ftshare.endpoints.spot` | | 外汇数据 | 0 | `ftshare.apis.forex` | `ftshare.endpoints.forex` | @@ -120,6 +120,7 @@ | [`stock_institution_holdings`](#api-stock-institution-holdings) | 机构持股 | `GET` | `api/v2/market/data/share/stock-institution-holdings` | `year`, `report_type`, `inst_type`, `page`, `page_size` | `机构持股.md` | | [`stock_institution_holdings_detail`](#api-stock-institution-holdings-detail) | 机构持股明细 | `GET` | `api/v2/market/data/share/stock-institution-holdings-detail` | `stock_code`, `year`, `report_type`, `inst_type`, `page`, `page_size` | `机构持股明细.md` | | [`stock_institution_share_holdings`](#api-stock-institution-share-holdings) | 机构股本持股 | `GET` | `api/v2/market/data/institution/institution-share-holdings` | `institution_id`, `year`, `report_type`, `invest_type` | `机构股本持股.md` | +| [`stock_intraday`](#api-stock-intraday) | 股票跨日分时行情 | `GET` | `api/v4/market/data/stock-intraday` | `symbol`, `range`, `days`, `ts_ms` | `股票跨日分时行情.md` | | [`stock_intraday_auction_volume`](#api-stock-intraday-auction-volume) | 连续竞价成交量 | `GET` | `api/v2/market/data/intraday-auction-volume` | `trade_date`, `page`, `page_size` | `连续竞价成交量.md` | | [`stock_intraday_prices`](#api-stock-intraday-prices) | 标的分时数据 | `GET` | `api/v4/market/data/daec/history/prices` | `symbol`, `range`, `days`, `ts_ms` | `标的分时数据.md` | | [`stock_ipos`](#api-stock-ipos) | 股票IPO | `GET` | `api/v1/market/data/stock-ipos` | `page`, `page_size` | `股票IPO.md` | @@ -265,11 +266,14 @@ ### 债券专题 -| [`cb_lists`](#api-cb-lists) | 可转债列表 | `GET` | `api/v1/market/data/cb/cb-lists` | - | `可转债列表.md` | - | SDK 方法 | 接口名称 | HTTP | Path | 参数 | 来源文档 | |---|---|---|---|---|---| -| [`convertible_bond_candlesticks`](#api-convertible-bond-candlesticks) | 可转债K线 | `GET` | `api/v1/market/data/convertible-bond-candlesticks` | `symbol`, `interval_unit`, `interval_value`, `adjust_kind`, `since_ts_millis`, `until_ts_millis`, `limit` | `可转债K线.md` | +| [`cb_lists`](#api-cb-lists) | 可转债列表 | `GET` | `api/v1/market/data/cb/cb-lists` | - | `可转债列表.md` | +| [`convertible_bond_candlesticks`](#api-convertible-bond-candlesticks) | 可转债历史K线 | `GET` | `api/v1/market/data/convertible-bond-candlesticks` | `symbol`, `interval_unit`, `interval_value`, `adjust_kind`, `since_ts_millis`, `until_ts_millis`, `limit` | `可转债历史K线.md` | +| [`convertible_bond_candlesticks_batch`](#api-convertible-bond-candlesticks-batch) | 批量可转债历史K线 | `GET` | `api/v2/market/data/convertible-bond-candlesticks/batch` | `symbols`, `interval_unit`, `interval_value`, `adjust_kind`, `since_ts_millis`, `until_ts_millis`, `limit` | `批量可转债历史K线.md` | +| [`convertible_bond_minute_candlesticks`](#api-convertible-bond-minute-candlesticks) | 可转债历史分钟K线 | `GET` | `api/v2/market/data/convertible-bond-minute-candlesticks` | `symbol`, `symbols`, `interval_value`, `since_ts_millis`, `until_ts_millis`, `limit` | `可转债历史分钟K线.md` | +| [`convertible_bond_realtime_day_kline`](#api-convertible-bond-realtime-day-kline) | 可转债实时日K线 | `GET` | `api/v4/market/data/convertible-bond-realtime-day-kline` | `symbols` | `可转债实时日K线.md` | +| [`convertible_bond_realtime_minute_kline`](#api-convertible-bond-realtime-minute-kline) | 可转债实时分钟K线 | `GET` | `api/v4/market/data/convertible-bond-realtime-minute-kline` | `symbols` | `可转债实时分钟K线.md` | | [`szse_convertible_bond_declaration_snapshots`](#api-szse-convertible-bond-declaration-snapshots) | 深交所可转债申报快照 | `GET` | `api/v1/market/data/convertible-bond/szse/declaration-snapshots` | `security_code`, `trade_date`, `start_date`, `end_date`, `page`, `page_size` | `深交所可转债申报快照.md` | | [`szse_convertible_bond_directed_trades`](#api-szse-convertible-bond-directed-trades) | 深交所可转债定向成交 | `GET` | `api/v1/market/data/convertible-bond/szse/directed-trades` | `security_code`, `trade_date`, `start_date`, `end_date`, `page`, `page_size` | `深交所可转债定向成交.md` | | [`szse_convertible_bond_matching_trades`](#api-szse-convertible-bond-matching-trades) | 深交所可转债匹配成交 | `GET` | `api/v1/market/data/convertible-bond/szse/matching-trades` | `security_code`, `trade_date`, `start_date`, `end_date`, `page`, `page_size` | `深交所可转债匹配成交.md` | @@ -311,6 +315,7 @@ | [`shareholders_meeting`](#api-shareholders-meeting) | 股东大会 | `GET` | `api/v1/market/data/corporate/meeting` | `page`, `page_size` | `股东大会.md` | | [`stock_announcements`](#api-stock-announcements) | 公告列表 | `GET` | `api/v2/market/data/announcements/stock-announcements` | `stock_code`, `start_date`, `end_date`, `type`, `page`, `page_size` | `公告列表.md` | | [`stock_reports`](#api-stock-reports) | 研报列表 | `GET` | `api/v2/market/data/report/stock-reports` | `stock_code`, `start_date`, `end_date`, `type`, `page`, `page_size` | `研报列表.md` | +| [`stock_prospectuses`](#api-stock-prospectuses) | 招股书列表 | `GET` | `api/v2/market/data/announcements/stock-prospectuses` | `stock_code`, `start_date`, `end_date`, `page`, `page_size` | `招股书列表.md` | ### 现货数据 @@ -2441,6 +2446,37 @@ Returns: payloads when multi-page fetching is used with ``raw=True``. ``` +

stock_intraday

+ +- 接口名称：股票跨日分时行情 +- HTTP：`GET` +- Path：`api/v4/market/data/stock-intraday` +- 参数：`symbol`, `range`, `days`, `ts_ms` +- 来源文档：`股票跨日分时行情.md` +- 原始接口：`stock_intraday` + +```text +股票跨日分时行情. + +Endpoint: ``api/v4/market/data/stock-intraday``. +Method: ``GET``. +Documented endpoint: ``stock_intraday``. + +Args: + symbol: 股票代码，需带市场后缀，如 600000.SH、000001.SZ；不接受裸代码 (type: string; required: Y). + range: 预置时间区间：Today（当日）/ FiveDays（当日及此前 4 个交易日，默认），大小写敏感 (type: string; required: N). + days: 1～5；查询当日及此前 N-1 个交易日，1 表示当日 (type: int; required: N). + ts_ms: 当日过滤起点，Unix 毫秒时间戳，包含起点；不能通过它指定历史日期 (type: int(ms); 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``, or raw JSON when ``raw=True``. +``` +

stock_intraday_auction_volume

- 接口名称：连续竞价成交量 @@ -4873,28 +4909,97 @@ Returns:

convertible_bond_candlesticks

-- 接口名称：可转债K线 +- 接口名称：可转债历史K线 - HTTP：`GET` - Path：`api/v1/market/data/convertible-bond-candlesticks` - 参数：`symbol`, `interval_unit`, `interval_value`, `adjust_kind`, `since_ts_millis`, `until_ts_millis`, `limit` -- 来源文档：`可转债K线.md` +- 来源文档：`可转债历史K线.md` - 原始接口：`convertible_bond_candlesticks` ```text -可转债K线. +可转债历史K线. Endpoint: ``api/v1/market/data/convertible-bond-candlesticks``. Method: ``GET``. Documented endpoint: ``convertible_bond_candlesticks``. Args: - symbol: 可转债代码，如 113027.XSHG、128048.XSHE；也接受 .SH、.SZ 短后缀 (type: string; required: Y). - interval_unit: 周期单位：Minute/Day/Week/Month/Year (type: enum; required: Y). - interval_value: 间隔数值，默认 1；例如 Minute+5 表示 5 分钟 K 线 (type: int; required: N). + symbol: 单只可转债代码，如 113042.SH；也接受 .XSHG、.XSHE 后缀 (type: string; required: Y). + interval_unit: 周期单位：Day/Week/Month/Year，大小写不敏感 (type: enum; required: Y). + interval_value: 可省略；周期查询无需设置 (type: int; required: N). adjust_kind: 复权：None（默认，不复权）/Forward（前复权）/Backward（后复权） (type: enum; required: N). - since_ts_millis: 开始时间戳，单位毫秒；分钟 K 线与 until 的跨度 ≤3 天 (type: int(ms); required: N). + since_ts_millis: 起始时间戳，单位毫秒；不得晚于 until，且与 until 相差不超过 12 个自然月 (type: int(ms); required: Y). until_ts_millis: 结束时间戳，单位毫秒 (type: int(ms); required: Y). - limit: 返回条数上限；未传 since 和 limit 时默认最多返回 50 根 K 线 (type: int; required: N). + limit: 保留最新 K 线条数上限；省略返回窗口内全部记录 (type: int; 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``, or raw page + payloads when multi-page fetching is used with ``raw=True``. +``` + +

convertible_bond_candlesticks_batch

+ +- 接口名称：批量可转债历史K线 +- HTTP：`GET` +- Path：`api/v2/market/data/convertible-bond-candlesticks/batch` +- 参数：`symbols`, `interval_unit`, `interval_value`, `adjust_kind`, `since_ts_millis`, `until_ts_millis`, `limit` +- 来源文档：`批量可转债历史K线.md` +- 原始接口：`convertible_bond_candlesticks_batch` + +```text +批量可转债历史K线. + +Endpoint: ``api/v2/market/data/convertible-bond-candlesticks/batch``. +Method: ``GET``. +Documented endpoint: ``convertible_bond_candlesticks_batch``. + +Args: + symbols: 可转债代码列表，1～20 个；支持重复参数、逗号分隔或 JSON 字符串数组 (type: string[]; required: Y). + interval_unit: 周期单位：Day/Week/Month/Year，大小写不敏感 (type: enum; required: Y). + interval_value: 可省略；周期查询无需设置 (type: int; required: N). + adjust_kind: 复权：None（默认，不复权）/Forward（前复权）/Backward（后复权） (type: enum; required: N). + since_ts_millis: 起始时间戳，单位毫秒；不得晚于 until，且与 until 相差不超过 12 个自然月 (type: int(ms); required: Y). + until_ts_millis: 结束时间戳，单位毫秒 (type: int(ms); required: Y). + limit: 每个标的最新 K 线条数上限；省略返回窗口内全部记录 (type: int; 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``, or raw page + payloads when multi-page fetching is used with ``raw=True``. +``` + +

convertible_bond_minute_candlesticks

+ +- 接口名称：可转债历史分钟K线 +- HTTP：`GET` +- Path：`api/v2/market/data/convertible-bond-minute-candlesticks` +- 参数：`symbol`, `symbols`, `interval_value`, `since_ts_millis`, `until_ts_millis`, `limit` +- 来源文档：`可转债历史分钟K线.md` +- 原始接口：`convertible_bond_minute_candlesticks` + +```text +可转债历史分钟K线. + +Endpoint: ``api/v2/market/data/convertible-bond-minute-candlesticks``. +Method: ``GET``. +Documented endpoint: ``convertible_bond_minute_candlesticks``. + +Args: + symbol: 单只可转债代码（与 symbols 二选一，不能同时传） (type: string; required: N). + symbols: 1～20 个可转债代码；支持重复参数、逗号分隔或 JSON 字符串数组（与 symbol 二选一） (type: string[]; required: N). + interval_value: 分钟周期：仅支持 1、5、15，默认 1 (type: enum; required: N). + since_ts_millis: 起始时间戳，单位毫秒；单只、批量都必须提供 (type: int(ms); required: Y). + until_ts_millis: 结束时间戳，单位毫秒；不得早于 since，且单次跨度不超过 3 个自然日 (type: int(ms); required: Y). + limit: 每只标的聚合后最多返回条数，范围 1～1000；省略返回窗口内全部记录 (type: int; 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. @@ -4906,6 +5011,62 @@ Returns: payloads when multi-page fetching is used with ``raw=True``. ``` +

convertible_bond_realtime_day_kline

+ +- 接口名称：可转债实时日K线 +- HTTP：`GET` +- Path：`api/v4/market/data/convertible-bond-realtime-day-kline` +- 参数：`symbols` +- 来源文档：`可转债实时日K线.md` +- 原始接口：`convertible_bond_realtime_day_kline` + +```text +可转债实时日K线. + +Endpoint: ``api/v4/market/data/convertible-bond-realtime-day-kline``. +Method: ``GET``. +Documented endpoint: ``convertible_bond_realtime_day_kline``. + +Args: + symbols: 1～20 个可转债代码的 JSON 字符串数组，如 ``["113042.SH","123107.SZ"]``；单只也必须传单元素数组 (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``, or raw JSON when ``raw=True``. +``` + +

convertible_bond_realtime_minute_kline

+ +- 接口名称：可转债实时分钟K线 +- HTTP：`GET` +- Path：`api/v4/market/data/convertible-bond-realtime-minute-kline` +- 参数：`symbols` +- 来源文档：`可转债实时分钟K线.md` +- 原始接口：`convertible_bond_realtime_minute_kline` + +```text +可转债实时分钟K线. + +Endpoint: ``api/v4/market/data/convertible-bond-realtime-minute-kline``. +Method: ``GET``. +Documented endpoint: ``convertible_bond_realtime_minute_kline``. + +Args: + symbols: 1～20 个可转债代码的 JSON 字符串数组，如 ``["113042.SH","123107.SZ"]``；单只也必须传单元素数组 (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``, or raw JSON when ``raw=True``. +``` +

szse_convertible_bond_declaration_snapshots

- 接口名称：深交所可转债申报快照 @@ -5672,6 +5833,43 @@ Returns: payloads when multi-page fetching is used with ``raw=True``. ``` +

stock_prospectuses

+ +- 接口名称：招股书列表 +- HTTP：`GET` +- Path：`api/v2/market/data/announcements/stock-prospectuses` +- 参数：`stock_code`, `start_date`, `end_date`, `page`, `page_size` +- 来源文档：`招股书列表.md` +- 原始接口：`stock_prospectuses` + +```text +招股书列表. + +Endpoint: ``api/v2/market/data/announcements/stock-prospectuses``. +Method: ``GET``. +Documented endpoint: ``stock_prospectuses``. + +Args: + stock_code: 股票代码；按标的查询时必填，支持裸代码、短后缀和长后缀 (type: string; required: N). + start_date: 披露日期 YYYYMMDD；未提供 stock_code 时必填 (type: string; required: N). + end_date: 披露日期 YYYYMMDD；不填默认等于 start_date，传入时必须等于 start_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. + **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``. + +``` + ### 现货数据

bullion_price

diff --git a/src/ftshare/apis/bond.py b/src/ftshare/apis/bond.py index 081bda2..4c4d28d 100644 --- a/src/ftshare/apis/bond.py +++ b/src/ftshare/apis/bond.py @@ -6,6 +6,7 @@ from typing import Any from ..endpoints import ENDPOINTS +from ..params import symbols_to_json_string class BondApiMixin: @@ -26,20 +27,20 @@ def convertible_bond_candlesticks( as_dataframe: bool = True, **kwargs: Any, ) -> Any: - """可转债K线. + """可转债历史K线. Endpoint: ``api/v1/market/data/convertible-bond-candlesticks``. Method: ``GET``. Documented endpoint: ``convertible_bond_candlesticks``. Args: - symbol: 可转债代码，如 113027.XSHG、128048.XSHE；也接受 .SH、.SZ 短后缀 (type: string; required: Y). - interval_unit: 周期单位：Minute/Day/Week/Month/Year (type: enum; required: Y). - interval_value: 间隔数值，默认 1；例如 Minute+5 表示 5 分钟 K 线 (type: int; required: N). + symbol: 单只可转债代码，如 113042.SH；也接受 .XSHG、.XSHE 后缀 (type: string; required: Y). + interval_unit: 周期单位：Day/Week/Month/Year，大小写不敏感 (type: enum; required: Y). + interval_value: 可省略；周期查询无需设置 (type: int; required: N). adjust_kind: 复权：None（默认，不复权）/Forward（前复权）/Backward（后复权） (type: enum; required: N). - since_ts_millis: 开始时间戳，单位毫秒；分钟 K 线与 until 的跨度 ≤3 天 (type: int(ms); required: N). + since_ts_millis: 起始时间戳，单位毫秒；不得晚于 until，且与 until 相差不超过 12 个自然月 (type: int(ms); required: Y). until_ts_millis: 结束时间戳，单位毫秒 (type: int(ms); required: Y). - limit: 返回条数上限；未传 since 和 limit 时默认最多返回 50 根 K 线 (type: int; required: N). + limit: 保留最新 K 线条数上限；省略返回窗口内全部记录 (type: int; 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. @@ -59,6 +60,147 @@ def convertible_bond_candlesticks( as_dataframe=as_dataframe, **request_params, ) + + def convertible_bond_candlesticks_batch( + self, + symbols: Any | None = None, + interval_unit: Any | None = None, + interval_value: Any | None = None, + adjust_kind: Any | None = None, + since_ts_millis: Any | None = None, + until_ts_millis: 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/convertible-bond-candlesticks/batch``. + Method: ``GET``. + Documented endpoint: ``convertible_bond_candlesticks_batch``. + + Args: + symbols: 可转债代码列表，1～20 个；支持重复参数、逗号分隔或 JSON 字符串数组 (type: string[]; required: Y). + interval_unit: 周期单位：Day/Week/Month/Year，大小写不敏感 (type: enum; required: Y). + interval_value: 可省略；周期查询无需设置 (type: int; required: N). + adjust_kind: 复权：None（默认，不复权）/Forward（前复权）/Backward（后复权） (type: enum; required: N). + since_ts_millis: 起始时间戳，单位毫秒；不得晚于 until，且与 until 相差不超过 12 个自然月 (type: int(ms); required: Y). + until_ts_millis: 结束时间戳，单位毫秒 (type: int(ms); required: Y). + limit: 每个标的最新 K 线条数上限；省略返回窗口内全部记录 (type: int; 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``, or raw page + payloads when multi-page fetching is used with ``raw=True``. + """ + request_params = {'symbols': symbols, 'interval_unit': interval_unit, 'interval_value': interval_value, 'adjust_kind': adjust_kind, 'since_ts_millis': since_ts_millis, 'until_ts_millis': until_ts_millis, 'limit': limit} + request_params.update(kwargs) + return self._call_endpoint( + 'convertible_bond_candlesticks_batch', + raw=raw, + fields=fields, + as_dataframe=as_dataframe, + **request_params, + ) + + def convertible_bond_minute_candlesticks( + self, + symbol: Any | None = None, + symbols: Any | None = None, + interval_value: Any | None = None, + since_ts_millis: Any | None = None, + until_ts_millis: 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/convertible-bond-minute-candlesticks``. + Method: ``GET``. + Documented endpoint: ``convertible_bond_minute_candlesticks``. + + Args: + symbol: 单只可转债代码（与 symbols 二选一，不能同时传） (type: string; required: N). + symbols: 1～20 个可转债代码；支持重复参数、逗号分隔或 JSON 字符串数组（与 symbol 二选一） (type: string[]; required: N). + interval_value: 分钟周期：仅支持 1、5、15，默认 1 (type: enum; required: N). + since_ts_millis: 起始时间戳，单位毫秒；单只、批量都必须提供 (type: int(ms); required: Y). + until_ts_millis: 结束时间戳，单位毫秒；不得早于 since，且单次跨度不超过 3 个自然日 (type: int(ms); required: Y). + limit: 每只标的聚合后最多返回条数，范围 1～1000；省略返回窗口内全部记录 (type: int; 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``, or raw page + payloads when multi-page fetching is used with ``raw=True``. + """ + request_params = {'symbol': symbol, 'symbols': symbols, 'interval_value': interval_value, 'since_ts_millis': since_ts_millis, 'until_ts_millis': until_ts_millis, 'limit': limit} + request_params.update(kwargs) + return self._call_endpoint( + 'convertible_bond_minute_candlesticks', + raw=raw, + fields=fields, + as_dataframe=as_dataframe, + **request_params, + ) + + def convertible_bond_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/convertible-bond-realtime-day-kline``. + Method: ``GET``. + Documented endpoint: ``convertible_bond_realtime_day_kline``. + + Args: + symbols: 1～20 个可转债代码的 JSON 字符串数组，如 ``["113042.SH","123107.SZ"]``；单只也必须传单元素数组 (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``, or raw JSON when ``raw=True``. + """ + params = {'symbols': symbols_to_json_string(symbols)} + params.update(kwargs) + return self._call_endpoint('convertible_bond_realtime_day_kline', raw=raw, fields=fields, as_dataframe=as_dataframe, **params) + + def convertible_bond_realtime_minute_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/convertible-bond-realtime-minute-kline``. + Method: ``GET``. + Documented endpoint: ``convertible_bond_realtime_minute_kline``. + + Args: + symbols: 1～20 个可转债代码的 JSON 字符串数组，如 ``["113042.SH","123107.SZ"]``；单只也必须传单元素数组 (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``, or raw JSON when ``raw=True``. + """ + params = {'symbols': symbols_to_json_string(symbols)} + params.update(kwargs) + return self._call_endpoint('convertible_bond_realtime_minute_kline', raw=raw, fields=fields, as_dataframe=as_dataframe, **params) + def szse_convertible_bond_matching_trades(self, security_code: Any | None = None, trade_date: Any | None = None, start_date: Any | None = None, end_date: 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: """深交所可转债匹配成交.""" params = {'security_code': security_code, 'trade_date': trade_date, 'start_date': start_date, 'end_date': end_date, 'page': page, 'page_size': page_size} diff --git a/src/ftshare/apis/llm_corpus.py b/src/ftshare/apis/llm_corpus.py index 4fbd83c..5e8dbca 100644 --- a/src/ftshare/apis/llm_corpus.py +++ b/src/ftshare/apis/llm_corpus.py @@ -224,3 +224,61 @@ def stock_reports( as_dataframe=as_dataframe, **request_params, ) + + def stock_prospectuses( + self, + stock_code: Any | None = None, + start_date: Any | None = None, + end_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/v2/market/data/announcements/stock-prospectuses``. + Method: ``GET``. + Documented endpoint: ``stock_prospectuses``. + + Args: + stock_code: 股票代码；按标的查询时必填，支持裸代码、短后缀和长后缀 (type: string; required: N). + start_date: 披露日期 YYYYMMDD；未提供 stock_code 时必填 (type: string; required: N). + end_date: 披露日期 YYYYMMDD；不填默认等于 start_date，传入时必须等于 start_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. + **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 = {'stock_code': stock_code, 'start_date': start_date, 'end_date': end_date} + request_params.update(kwargs) + path = ENDPOINTS['stock_prospectuses'].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['stock_prospectuses'].max_page_size, + raw=raw, + fields=fields, + as_dataframe=as_dataframe, + **request_params, + ) diff --git a/src/ftshare/apis/stock.py b/src/ftshare/apis/stock.py index 54a3281..e1133fa 100644 --- a/src/ftshare/apis/stock.py +++ b/src/ftshare/apis/stock.py @@ -3708,6 +3708,48 @@ def stock_prev_close( **request_params, ) + def stock_intraday( + self, + symbol: Any | None = None, + range: Any | None = None, + days: Any | None = None, + ts_ms: Any | None = None, + *, + raw: bool = False, + fields: Sequence[str] | str | None = None, + as_dataframe: bool = True, + **kwargs: Any, + ) -> Any: + """股票跨日分时行情. + + Endpoint: ``api/v4/market/data/stock-intraday``. + Method: ``GET``. + Documented endpoint: ``stock_intraday``. + + Args: + symbol: 股票代码，需带市场后缀，如 600000.SH、000001.SZ；不接受裸代码 (type: string; required: Y). + range: 预置时间区间：Today（当日）/ FiveDays（当日及此前 4 个交易日，默认），大小写敏感 (type: string; required: N). + days: 1～5；查询当日及此前 N-1 个交易日，1 表示当日 (type: int; required: N). + ts_ms: 当日过滤起点，Unix 毫秒时间戳，包含起点；不能通过它指定历史日期 (type: int(ms); 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``, or raw JSON when ``raw=True``. + """ + request_params = {'symbol': symbol, 'range': range, 'days': days, 'ts_ms': ts_ms} + request_params.update(kwargs) + return self._call_endpoint( + 'stock_intraday', + raw=raw, + fields=fields, + as_dataframe=as_dataframe, + **request_params, + ) + def stock_intraday_prices( self, symbol: Any | None = None, diff --git a/src/ftshare/endpoints/bond.py b/src/ftshare/endpoints/bond.py index b7bacd4..9bdf523 100644 --- a/src/ftshare/endpoints/bond.py +++ b/src/ftshare/endpoints/bond.py @@ -8,12 +8,45 @@ ENDPOINTS: dict[str, Endpoint] = build_endpoints({ 'convertible_bond_candlesticks': { 'path': 'api/v1/market/data/convertible-bond-candlesticks', - 'title': '可转债K线', - 'doc_file': '可转债K线.md', + 'title': '可转债历史K线', + 'doc_file': '可转债历史K线.md', 'original_api': 'convertible_bond_candlesticks', 'method': 'GET', 'params': ('symbol', 'interval_unit', 'interval_value', 'adjust_kind', 'since_ts_millis', 'until_ts_millis', 'limit'), }, + + 'convertible_bond_candlesticks_batch': { + 'path': 'api/v2/market/data/convertible-bond-candlesticks/batch', + 'title': '批量可转债历史K线', + 'doc_file': '批量可转债历史K线.md', + 'original_api': 'convertible_bond_candlesticks_batch', + 'params': ('symbols', 'interval_unit', 'interval_value', 'adjust_kind', 'since_ts_millis', 'until_ts_millis', 'limit'), + }, + + 'convertible_bond_minute_candlesticks': { + 'path': 'api/v2/market/data/convertible-bond-minute-candlesticks', + 'title': '可转债历史分钟K线', + 'doc_file': '可转债历史分钟K线.md', + 'original_api': 'convertible_bond_minute_candlesticks', + 'params': ('symbol', 'symbols', 'interval_value', 'since_ts_millis', 'until_ts_millis', 'limit'), + }, + + 'convertible_bond_realtime_day_kline': { + 'path': 'api/v4/market/data/convertible-bond-realtime-day-kline', + 'title': '可转债实时日K线', + 'doc_file': '可转债实时日K线.md', + 'original_api': 'convertible_bond_realtime_day_kline', + 'params': ('symbols',), + }, + + 'convertible_bond_realtime_minute_kline': { + 'path': 'api/v4/market/data/convertible-bond-realtime-minute-kline', + 'title': '可转债实时分钟K线', + 'doc_file': '可转债实时分钟K线.md', + 'original_api': 'convertible_bond_realtime_minute_kline', + 'params': ('symbols',), + }, + 'szse_convertible_bond_matching_trades': { 'path': 'api/v1/market/data/convertible-bond/szse/matching-trades', 'title': '深交所可转债匹配成交', diff --git a/src/ftshare/endpoints/llm_corpus.py b/src/ftshare/endpoints/llm_corpus.py index a2fe4e4..ccdffdf 100644 --- a/src/ftshare/endpoints/llm_corpus.py +++ b/src/ftshare/endpoints/llm_corpus.py @@ -34,4 +34,12 @@ 'original_api': 'stock_reports', 'params': ('stock_code', 'start_date', 'end_date', 'type', 'page', 'page_size'), }, + 'stock_prospectuses': { + 'path': 'api/v2/market/data/announcements/stock-prospectuses', + 'title': '招股书列表', + 'doc_file': '招股书列表.md', + 'original_api': 'stock_prospectuses', + 'params': ('stock_code', 'start_date', 'end_date', 'page', 'page_size'), + 'max_page_size': 500, + }, }) diff --git a/src/ftshare/endpoints/stock.py b/src/ftshare/endpoints/stock.py index d455e7d..e8e58b7 100644 --- a/src/ftshare/endpoints/stock.py +++ b/src/ftshare/endpoints/stock.py @@ -417,6 +417,13 @@ 'original_api': 'get_stock_institution_share_holdings', 'params': ('institution_id', 'year', 'report_type', 'invest_type'), }, + 'stock_intraday': { + 'path': 'api/v4/market/data/stock-intraday', + 'title': '股票跨日分时行情', + 'doc_file': '股票跨日分时行情.md', + 'original_api': 'stock_intraday', + 'params': ('symbol', 'range', 'days', 'ts_ms'), + }, 'stock_intraday_auction_volume': { 'path': 'api/v2/market/data/intraday-auction-volume', 'title': '连续竞价成交量', diff --git a/tests/endpoint_cases.py b/tests/endpoint_cases.py index dde1d7c..81c695e 100644 --- a/tests/endpoint_cases.py +++ b/tests/endpoint_cases.py @@ -164,6 +164,10 @@ "eastmoney_us_stock_list": {"refresh": False, "page": 1, "page_size": 5}, "eastmoney_us_stock_daily_ohlc": {"stock_code": "AAPL", "start_date": "20260818", "end_date": "20260820", "page": 1, "page_size": 10}, "convertible_bond_candlesticks": {"symbol": "113027.SH", "interval_unit": "Day", "interval_value": 1, "adjust_kind": "forward", "since_ts_millis": 1716000000000, "until_ts_millis": 1718000000000, "limit": 5}, + "convertible_bond_candlesticks_batch": {"symbols": "113042.SH", "interval_unit": "Day", "interval_value": 1, "adjust_kind": "forward", "since_ts_millis": 1784048400000, "until_ts_millis": 1784050200000, "limit": 5}, + "convertible_bond_minute_candlesticks": {"symbol": "113042.SH", "symbols": None, "interval_value": 1, "since_ts_millis": 1784048400000, "until_ts_millis": 1784050200000, "limit": 5}, + "convertible_bond_realtime_day_kline": {"symbols": '["113042.SH"]'}, + "convertible_bond_realtime_minute_kline": {"symbols": '["113042.SH"]'}, "etf_candlesticks": {"symbol": "510300.SH", "interval_unit": "day", "interval_value": 1, "adjust_kind": "forward", "since_ts_millis": 1716000000000, "until_ts_millis": 1718000000000, "limit": 5}, "etf_components_all": {"symbol": "510300.SH"}, "etf_minutes": {"symbol": "510300.SH", "interval_value": 1, "adjust_kind": "none", "since_ts_millis": 1784048400000, "until_ts_millis": 1784050200000, "limit": 5}, @@ -211,6 +215,7 @@ "stk_surv": {"ts_code": "000001.SZ", "trade_date": "20260717", "start_date": None, "end_date": None, "page": 1, "page_size": 5}, "stock_announcements": {"stock_code": "000001.SZ", "start_date": None, "end_date": None, "type": "stock", "page": 1, "page_size": 5}, "stock_reports": {"stock_code": "000001.SZ", "start_date": None, "end_date": None, "type": "StockReport", "page": 1, "page_size": 5}, + "stock_prospectuses": {"stock_code": "600000.SH", "start_date": None, "end_date": None, "page": 1, "page_size": 5}, "stock_candlesticks": {"symbol": "600519.SH", "interval_unit": "day", "interval_value": 1, "adjust_kind": "forward", "since_ts_millis": 1784048400000, "until_ts_millis": 1784050200000, "limit": 5}, "stock_connect_members": {"direction": "north", "channel": "SH", "page": 1, "page_size": 5}, "stock_dividends": {"symbol": "600519.SH", "since_date": "2026-07-01", "until_date": "2026-07-17", "page": 1, "page_size": 5}, diff --git a/tests/test_client.py b/tests/test_client.py index 7a480ca..78286af 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -213,6 +213,7 @@ def test_requested_endpoint_api_versions(): expected_paths = { "hk_candlesticks": "api/v2/market/data/hk/hk-candlesticks", "stock_announcements": "api/v2/market/data/announcements/stock-announcements", + "stock_prospectuses": "api/v2/market/data/announcements/stock-prospectuses", "stock_reports": "api/v2/market/data/report/stock-reports", "stock_minutes": "api/v2/market/data/stock_minutes", "futures_minutes": "api/v2/market/data/futures_minutes", @@ -1018,6 +1019,104 @@ def test_convertible_bond_candlesticks_uses_get_query_params(): } +def test_convertible_bond_kline_family_forwards_documented_parameters(): + kline = [{"symbol": "113042.SH", "close": "116.8380"}] + grouped = [{"symbol": "113042.SH", "items": kline, "total": 1}] + + cases = [ + ( + "convertible_bond_candlesticks", + "api/v1/market/data/convertible-bond-candlesticks", + kline, + {"symbol": "113042.SH", "interval_unit": "Day", "since_ts_millis": 1786291200000, "until_ts_millis": 1786377599999, "limit": 1}, + ), + ( + "convertible_bond_candlesticks_batch", + "api/v2/market/data/convertible-bond-candlesticks/batch", + kline, + {"symbols": ["113042.SH", "123107.SZ"], "interval_unit": "Day", "since_ts_millis": 1786291200000, "until_ts_millis": 1786377599999, "limit": 1}, + ), + ( + "convertible_bond_minute_candlesticks", + "api/v2/market/data/convertible-bond-minute-candlesticks", + kline, + {"symbol": "113042.SH", "interval_value": 1, "since_ts_millis": 1786291200000, "until_ts_millis": 1786377599999, "limit": 1}, + ), + ] + + for method_name, path, payload, kwargs in cases: + session = FakeSession([FakeResponse(payload=payload)]) + client = FtshareClient(session=session) + + getattr(client, method_name)(as_dataframe=False, **kwargs) + + assert session.calls[0]["url"] == "https://market.ft.tech/gateway/" + path + assert session.calls[0]["params"] == kwargs + + session = FakeSession([FakeResponse(payload=grouped)]) + client = FtshareClient(session=session) + + client.convertible_bond_minute_candlesticks( + symbols=["113042.SH", "123107.SZ"], + since_ts_millis=1786291200000, + until_ts_millis=1786377599999, + as_dataframe=False, + ) + + assert session.calls[0]["params"] == { + "symbols": ["113042.SH", "123107.SZ"], + "since_ts_millis": 1786291200000, + "until_ts_millis": 1786377599999, + } + + for method_name in ("convertible_bond_realtime_day_kline", "convertible_bond_realtime_minute_kline"): + session = FakeSession([FakeResponse(payload={"code": 200, "message": "success", "data": grouped})]) + client = FtshareClient(session=session) + + getattr(client, method_name)(symbols=["113042.SH", "123107.SZ"], as_dataframe=False) + + assert session.calls[0]["params"] == {"symbols": '["113042.SH", "123107.SZ"]'} + + +def test_stock_intraday_forwards_range_days_and_ts_ms(): + session = FakeSession([FakeResponse(payload=[{"ts_ms": 1789522200000, "price": 9.19}])] * 2) + client = FtshareClient(session=session) + + client.stock_intraday(symbol="600000.SH", range="Today", as_dataframe=False) + client.stock_intraday(symbol="600000.SH", days=3, ts_ms=1789522200000, as_dataframe=False) + + assert session.calls[0]["url"] == "https://market.ft.tech/gateway/api/v4/market/data/stock-intraday" + assert session.calls[0]["params"] == {"symbol": "600000.SH", "range": "Today"} + assert session.calls[1]["params"] == {"symbol": "600000.SH", "days": 3, "ts_ms": 1789522200000} + + +def test_stock_prospectuses_supports_stock_and_date_modes(): + session = FakeSession( + [ + FakeResponse(payload=paginated_records([{"stock_code": "600000.SH"}])), + FakeResponse(payload=paginated_records([{"stock_code": "920002.BJ"}])), + ] + ) + client = FtshareClient(session=session) + + client.stock_prospectuses(stock_code="600000.SH", page=1, page_size=500, as_dataframe=False) + client.stock_prospectuses(start_date="20061114", end_date="20061114", page=1, page_size=500, as_dataframe=False) + + assert session.calls[0]["url"] == "https://market.ft.tech/gateway/api/v2/market/data/announcements/stock-prospectuses" + assert session.calls[0]["params"] == {"stock_code": "600000.SH", "page": 1, "page_size": 500} + assert session.calls[1]["params"] == {"start_date": "20061114", "end_date": "20061114", "page": 1, "page_size": 500} + + +def test_stock_prospectuses_rejects_page_size_above_documented_maximum(): + session = FakeSession([]) + client = FtshareClient(session=session) + + with pytest.raises(ValueError, match="page_size must be between 1 and 500"): + client.stock_prospectuses(stock_code="600000.SH", page_size=501, as_dataframe=False) + + assert session.calls == [] + + def test_index_candlesticks_uses_get_query_params(): session = FakeSession([FakeResponse(payload=[{"close": "4500"}])]) client = FtshareClient(session=session)