Skip to content

Commit 454fdf3

Browse files
Howe319Howe319
committed
feat：移除年度分K归档包下载接口
1 parent 22b3c2c commit 454fdf3

7 files changed

Lines changed: 5 additions & 623 deletions

File tree

‎docs/API_REFERENCE.md‎

Lines changed: 2 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@
66

77
| 指标 | 数量 |
88
|---|---:|
9-
| SDK 方法总数 | 241 |
9+
| SDK 方法总数 | 239 |
1010

1111
## 专题分布
1212

1313
| ftshare-doc 专题 | SDK 方法数 | API mixin 模块 | Endpoint 模块 |
1414
|---|---:|---|---|
15-
| 股票数据 | 127 | `ftshare.apis.stock` | `ftshare.endpoints.stock` |
15+
| 股票数据 | 125 | `ftshare.apis.stock` | `ftshare.endpoints.stock` |
1616
| 港股数据 | 3 | `ftshare.apis.hk` | `ftshare.endpoints.hk` |
1717
| 美股数据 | 2 | `ftshare.apis.us` | `ftshare.endpoints.us` |
1818
| 指数专题 | 15 | `ftshare.apis.index` | `ftshare.endpoints.index` |
@@ -71,8 +71,6 @@
7171
| [`goodwill_stock_detail`](#api-goodwill-stock-detail) | 商誉个股明细 | `GET` | `api/v1/market/data/goodwill/stock-detail` | `date`, `page`, `page_size` | `商誉个股明细.md` |
7272
| [`goodwill_stock_impairment`](#api-goodwill-stock-impairment) | 商誉减值 | `GET` | `api/v1/market/data/goodwill/stock-impairment` | `date`, `page`, `page_size` | `商誉减值.md` |
7373
| [`income`](#api-income) | A股利润表 | `GET` | `api/v1/market/data/finance/income` | `stock_code`, `year`, `report_type`, `page`, `page_size` | `A股利润表.md` |
74-
| [`kline_archives`](#api-kline-archives) | 年度分K归档包下载 | `GET` | `api/v2/market/data/kline-archives` | - | `年度分K归档包下载.md` |
75-
| [`kline_archives_download`](#api-kline-archives-download) | 年度分K归档包下载 | `GET` | `api/v2/market/data/kline-archives/{year}/download` | `year`, `save_dir`, `retries` | `年度分K归档包下载.md` |
7674
| [`kline_pattern_annotations`](#api-kline-pattern-annotations) | K线形态标注 | `GET` | `api/v3/market/data/kline-pattern-annotations` | `date`, `trade_code`, `pattern`, `page`, `page_size` | `K线形态标注.md` |
7775
| [`limit_event_timeline_3s`](#api-limit-event-timeline-3s) | 涨跌停事件时间线 | `GET` | `api/v2/market/data/limit-event-timeline-3s` | `symbol`, `trade_date`, `page`, `page_size` | `涨跌停事件时间线.md` |
7876
| [`limit_list`](#api-limit-list) | 涨跌停池 | `GET` | `api/v1/market/data/limit-list` | `limit_type`, `trade_date` | `涨跌停池.md` |
@@ -1232,63 +1230,6 @@ Returns:
12321230
payloads when multi-page fetching is used with ``raw=True``.
12331231
```
12341232

1235-
<h4 id="api-kline-archives"><code>kline_archives</code></h4>
1236-
1237-
- 接口名称：年度分K归档包下载
1238-
- HTTP：`GET`
1239-
- Path：`api/v2/market/data/kline-archives`
1240-
- 参数：`-`
1241-
- 来源文档：`年度分K归档包下载.md`
1242-
- 原始接口：`kline_archives`
1243-
1244-
```text
1245-
年度分K归档包清单.
1246-
1247-
Endpoint: ``api/v2/market/data/kline-archives``.
1248-
Method: ``GET``.
1249-
Documented endpoint: ``kline_archives``.
1250-
1251-
Args:
1252-
raw: Return the decoded JSON payload without tabular extraction.
1253-
fields: Optional field list or comma-separated field string applied after extraction.
1254-
as_dataframe: Return a pandas ``DataFrame`` by default; set to ``False`` for Python rows.
1255-
**kwargs: Extra request parameters forwarded unchanged.
1256-
1257-
Returns:
1258-
A pandas ``DataFrame`` by default, Python rows when ``as_dataframe=False``, or raw JSON when ``raw=True``. Rows carry `year`, `size_bytes`, `last_modified` and `sha256` for each downloadable archive package.
1259-
```
1260-
1261-
<h4 id="api-kline-archives-download"><code>kline_archives_download</code></h4>
1262-
1263-
- 接口名称：年度分K归档包下载
1264-
- HTTP：`GET`
1265-
- Path：`api/v2/market/data/kline-archives/{year}/download`
1266-
- 参数：`year`, `save_dir`, `retries`
1267-
- 来源文档：`年度分K归档包下载.md`
1268-
- 说明：`kline_archives` 的二进制归档包路由，下载 zstd 压缩 tar 并落盘，返回文件路径；支持 HTTP Range 断点续传与网络失败重试，完成后按清单 `sha256` 校验。
1269-
1270-
```text
1271-
下载年度分K归档包.
1272-
1273-
Endpoint: ``api/v2/market/data/kline-archives/{year}/download``.
1274-
Method: ``GET``.
1275-
1276-
归档包为按年打包的分钟 K 线（zstd 压缩 tar，4–5 GB），下载前先用 ``kline_archives`` 校验该年份是否在清单内，下载中支持 HTTP Range 断点续传（半成品写在 `{文件名}.part`，旁挂 `.part.meta` 记录 ETag；服务端 ETag 变化时丢弃半成品重下），支持网络失败重试，下载完成后按清单的 `sha256` 校验完整性。
1277-
1278-
Args:
1279-
year: 4 位年份，如 `2023`；须为 ``kline_archives`` 返回的年份之一 (type: int | string; required: Y).
1280-
save_dir: 保存目录，默认为当前目录；目录不存在时自动创建。
1281-
retries: 首次失败后的额外重试次数，默认 3（即最多尝试 4 次）。网络异常、429、5xx 与 416 会重试。
1282-
1283-
Returns:
1284-
落盘后的文件路径；目标文件已存在且 sha256 与清单一致时直接返回该路径，不重新下载。
1285-
1286-
Raises:
1287-
ValueError: 传入的 `year` 不是 4 位数字。
1288-
FtshareDownloadError: 该年份不在清单内，或下载完成后 size / sha256 校验不一致。
1289-
FtshareHTTPError: 下载接口返回不可重试的 HTTP 错误状态。
1290-
```
1291-
12921233
<h4 id="api-kline-pattern-annotations"><code>kline_pattern_annotations</code></h4>
12931234

12941235
- 接口名称：K线形态标注

‎src/ftshare/__init__.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
from .exceptions import (
2424
FtshareAPIError,
2525
FtshareDecodeError,
26-
FtshareDownloadError,
2726
FtshareError,
2827
FtshareHTTPError,
2928
)
@@ -91,7 +90,6 @@ def market_api(
9190
"FtshareAPIError",
9291
"FtshareClient",
9392
"FtshareDecodeError",
94-
"FtshareDownloadError",
9593
"FtshareError",
9694
"FtshareHTTPError",
9795
"get_base_url",

‎src/ftshare/apis/stock.py‎

Lines changed: 1 addition & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,10 @@
22

33
from __future__ import annotations
44

5-
import os
6-
import re
7-
from collections.abc import Mapping, Sequence
5+
from collections.abc import Sequence
86
from typing import Any
97

108
from ..endpoints import ENDPOINTS
11-
from ..exceptions import FtshareDownloadError
129
from ..params import symbols_to_json_string
1310

1411

@@ -4388,94 +4385,6 @@ def ashare_news_sentiment_factors(self, trade_code: Any | None = None, start_dat
43884385
return self.get_paginated(path, page=page, page_size=page_size, limit=limit, all_pages=all_pages, max_pages=max_pages, raw=raw, fields=fields, as_dataframe=as_dataframe, **params)
43894386

43904387

4391-
def kline_archives(
4392-
self,
4393-
*,
4394-
raw: bool = False,
4395-
fields: Sequence[str] | str | None = None,
4396-
as_dataframe: bool = True,
4397-
**kwargs: Any,
4398-
) -> Any:
4399-
"""年度分K归档包清单.
4400-
4401-
Endpoint: ``api/v2/market/data/kline-archives``.
4402-
Method: ``GET``.
4403-
Documented endpoint: ``kline_archives``.
4404-
4405-
Args:
4406-
raw: Return the decoded JSON payload without tabular extraction.
4407-
fields: Optional field list or comma-separated field string applied after extraction.
4408-
as_dataframe: Return a pandas ``DataFrame`` by default; set to ``False`` for Python rows.
4409-
**kwargs: Extra request parameters forwarded unchanged.
4410-
4411-
Returns:
4412-
A pandas ``DataFrame`` by default, Python rows when ``as_dataframe=False``, or raw JSON when ``raw=True``. Rows carry `year`, `size_bytes`, `last_modified` and `sha256` for each downloadable archive package.
4413-
"""
4414-
request_params = dict(kwargs)
4415-
return self._call_endpoint(
4416-
'kline_archives',
4417-
raw=raw,
4418-
fields=fields,
4419-
as_dataframe=as_dataframe,
4420-
**request_params,
4421-
)
4422-
4423-
def kline_archives_download(
4424-
self,
4425-
year: Any,
4426-
save_dir: str | os.PathLike[str] = ".",
4427-
retries: int = 3,
4428-
) -> str:
4429-
"""下载年度分K归档包.
4430-
4431-
Endpoint: ``api/v2/market/data/kline-archives/{year}/download``.
4432-
Method: ``GET``.
4433-
4434-
归档包为按年打包的分钟 K 线（zstd 压缩 tar，4–5 GB），下载前先用 ``kline_archives`` 校验该年份是否在清单内，下载中支持 HTTP Range 断点续传（半成品写在 `{文件名}.part`，旁挂 `.part.meta` 记录 ETag；服务端 ETag 变化时丢弃半成品重下），支持网络失败重试，下载完成后按清单的 `sha256` 校验完整性。
4435-
4436-
Args:
4437-
year: 4 位年份，如 `2023`；须为 ``kline_archives`` 返回的年份之一 (type: int | string; required: Y).
4438-
save_dir: 保存目录，默认为当前目录；目录不存在时自动创建。
4439-
retries: 首次失败后的额外重试次数，默认 3（即最多尝试 4 次）。网络异常、429、5xx 与 416 会重试。
4440-
4441-
Returns:
4442-
落盘后的文件路径；目标文件已存在且 sha256 与清单一致时直接返回该路径，不重新下载。
4443-
4444-
Raises:
4445-
ValueError: 传入的 `year` 不是 4 位数字。
4446-
FtshareDownloadError: 该年份不在清单内，或下载完成后 size / sha256 校验不一致。
4447-
FtshareHTTPError: 下载接口返回不可重试的 HTTP 错误状态。
4448-
"""
4449-
year_str = str(year)
4450-
if re.fullmatch(r"\d{4}", year_str) is None:
4451-
raise ValueError(f"year must be a 4-digit year; got {year!r}")
4452-
4453-
listing = self.kline_archives(as_dataframe=False)
4454-
rows = listing if isinstance(listing, list) else []
4455-
entry = next(
4456-
(
4457-
row
4458-
for row in rows
4459-
if isinstance(row, Mapping) and str(row.get('year')) == year_str
4460-
),
4461-
None,
4462-
)
4463-
if entry is None:
4464-
raise FtshareDownloadError(
4465-
self._url_for(ENDPOINTS['kline_archives'].path),
4466-
f"no archive package is offered for year {year_str}",
4467-
)
4468-
4469-
path = self._format_path(ENDPOINTS['kline_archives'].path + '/{year}/download', {'year': year_str})
4470-
return self.download_resumable(
4471-
path,
4472-
expected_size=entry.get('size_bytes'),
4473-
expected_sha256=entry.get('sha256'),
4474-
save_dir=save_dir,
4475-
filename=f"ftshare_1m_{year_str}.tar.zst",
4476-
retries=retries,
4477-
)
4478-
44794388
def kline_pattern_annotations(self, date: Any | None = None, symbol: Any | None = None, pattern: Any | None = None, page: Any | None = None, page_size: Any | 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:
44804389
"""K线形态标注."""
44814390
params = {'date': date, 'symbol': symbol, 'pattern': pattern}

0 commit comments

Comments
 (0)