ffdata 0.2.0__py3-none-any.whl

ffdata/client.py

@@ -0,0 +1,554 @@
+"""研究员使用的 ffdata Python 客户端。
+
+客户端统一封装远程 HTTP 查询、本地 Parquet 查询和自动路由，并向上保持稳定的
+``pandas.DataFrame`` 返回契约。
+"""
+# ruff: noqa: E501
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+import httpx
+import pandas as pd
+from ffdata_common.errors import DatasetError
+from ffdata_common.protocol import LOCAL_DATASET_APIS
+
+from .datasets import DatasetManager
+from .local import LocalStore
+from .transport import HttpTransport
+
+Source = Literal["remote", "local", "auto"]
+
+
+class Client:
+    """ffdata 主客户端，聚合远程传输、本地存储和数据集同步能力。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "http://127.0.0.1:8000",
+        token: str | None = None,
+        data_dir: str | Path | None = None,
+        timeout: float = 300.0,
+        http_client: httpx.Client | None = None,
+    ):
+        root = Path(
+            data_dir or os.getenv("FFDATA_DATA_DIR", str(Path.home() / ".ffdata" / "datasets"))
+        )
+        self.transport = HttpTransport(
+            base_url=base_url,
+            token=token,
+            timeout=timeout,
+            client=http_client,
+        )
+        self.local = LocalStore(root)
+        self.datasets = DatasetManager(self.transport, self.local)
+
+    def close(self) -> None:
+        self.transport.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def query(
+        self,
+        api_name: str,
+        *,
+        fields: list[str] | None = None,
+        source: Source = "remote",
+        response_format: Literal["json", "arrow"] = "arrow",
+        **params: Any,
+    ) -> pd.DataFrame:
+        """执行通用查询，并根据 ``source`` 选择远程或本地数据源。"""
+        if source not in {"remote", "local", "auto"}:
+            raise ValueError("source must be 'remote', 'local', or 'auto'")
+        dataset = LOCAL_DATASET_APIS.get(api_name)
+        if source == "local":
+            if dataset is None:
+                raise DatasetError(f"API {api_name!r} does not support local mode")
+            return self.local.query(dataset, params, fields=fields)
+        if source == "auto" and dataset is not None and self.local.covers(dataset, params):
+            return self.local.query(dataset, params, fields=fields)
+        return self.transport.query(
+            api_name,
+            params,
+            fields=fields,
+            response_format=response_format,
+        )
+
+    def create_export(
+        self,
+        api_name: str,
+        *,
+        fields: list[str] | None = None,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """创建异步 Parquet 导出任务，立即返回任务信息。"""
+        return self.transport.create_export(api_name, params, fields=fields)
+
+    def sql_query(
+        self,
+        sql: str,
+        *,
+        bindings: dict[str, str | int | float | bool | None] | None = None,
+        max_rows: int = 1_000,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """通过独立权限的服务端接口执行单条受限 SELECT。"""
+        return self.query(
+            "sql_query",
+            sql=sql,
+            bindings=bindings or {},
+            max_rows=max_rows,
+            fields=fields,
+        )
+
+    def export_status(self, job_id: str) -> dict[str, Any]:
+        return self.transport.export_status(job_id)
+
+    def download_export(self, job_id: str, destination: str | Path) -> Path:
+        return self.transport.download_export(job_id, Path(destination))
+
+    def stock_daily(
+        self,
+        ts_code: str | list[str] | None = None,
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        source: Source = "auto",
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "stock_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            source=source,
+            fields=fields,
+        )
+
+    def stock_adjusting_factor(
+        self,
+        ts_code: str | list[str] | None = None,
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        source: Source = "auto",
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "stock_adjusting_factor",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            source=source,
+            fields=fields,
+        )
+
+    def stock_valuation_daily(
+        self,
+        ts_code: str | list[str] | None = None,
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        source: Source = "auto",
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "stock_valuation_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            source=source,
+            fields=fields,
+        )
+
+    def index_daily(
+        self,
+        ts_code: str | list[str],
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "index_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def index_basic(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        symbol: str | list[str] | None = None,
+        name: str | None = None,
+        market: str | None = None,
+        publisher: str | None = None,
+        category: str | int | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询指数基本信息。
+
+        ``ts_code`` 可带后缀（如 ``000300.SH``），查询时服务端会剥离后缀按纯代码
+        匹配，与 ``symbol`` 行为一致（指数代码在不带后缀时唯一）。返回结果中
+        ``ts_code`` 为聚源发布机构口径的带后缀代码，并新增 ``inner_code``
+        （指数聚源内码）字段。至少需提供一个过滤参数；本接口仅支持远程查询。
+        """
+        return self.query(
+            "index_basic",
+            ts_code=ts_code,
+            symbol=symbol,
+            name=name,
+            market=market,
+            publisher=publisher,
+            category=category,
+            fields=fields,
+        )
+
+    def index_weight(
+        self,
+        index_code: str,
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询单个指数的成分证券与权重。
+
+        ``index_code`` 必须带市场后缀，例如 ``399300.SZ``；返回的
+        ``index_code``、``con_code`` 也始终带后缀。本接口仅支持远程查询。
+        """
+        return self.query(
+            "index_weight",
+            index_code=index_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def macro_indicator_basic(
+        self,
+        *,
+        indicator_code: int | list[int] | None = None,
+        name: str | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "macro_indicator_basic", indicator_code=indicator_code, name=name, fields=fields
+        )
+
+    def macro_indicator_data(
+        self,
+        indicator_code: int | list[int],
+        *,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        return self.query(
+            "macro_indicator_data",
+            indicator_code=indicator_code,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def stock_basic(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        name: str | None = None,
+        market: str | None = None,
+        list_status: str | list[str] | None = "L",
+        exchange: str | None = None,
+        is_hs: str | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询股票列表基础信息（18 列）。
+
+        ``list_status`` 取 ``L``（上市，默认）/``D``（退市）/``UN``（未上市），
+        也可传 ``"all"`` 返回全部；``market`` 取 ``主板``/``创业板``/``科创板``/``北交所``/``CDR``；
+        ``exchange`` 取 ``SH``/``SZ``/``BJ``（兼容 ``SSE``/``SZSE``/``BSE``）；
+        ``is_hs`` 取 ``N``/``H``（沪股通）/``S``（深股通）。字段口径见
+        [股票列表](../../docs/数据接口文档/股票列表.md)。
+        """
+        return self.query(
+            "stock_basic",
+            ts_code=ts_code,
+            name=name,
+            market=market,
+            list_status=list_status,
+            exchange=exchange,
+            is_hs=is_hs,
+            fields=fields,
+        )
+
+    def trade_cal(
+        self,
+        *,
+        exchange: str = "SH",
+        start_date: Any = None,
+        end_date: Any = None,
+        is_open: str | int | None = None,
+        is_week_end: str | int | None = None,
+        is_month_end: str | int | None = None,
+        is_quarter_end: str | int | None = None,
+        is_year_end: str | int | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询单个交易所的交易日历（8 列）。
+
+        ``exchange`` 取 ``SH``/``SZ``/``BJ``/``HK``/``US``/``IB``，默认 ``SH``。
+        五个标志均可作为过滤条件，取值 ``'1'``（是）或 ``'0'``（否）：
+        ``is_open``（是否交易日）、``is_week_end``/``is_month_end``/
+        ``is_quarter_end``/``is_year_end``（是否周/月/季/年最后一个交易日）。
+        ``US`` 为美国三个市场按 ``cal_date`` 合并后的日历。字段口径见
+        [交易日历](../../docs/数据接口文档/交易日历.md)。
+        """
+        return self.query(
+            "trade_cal",
+            exchange=exchange,
+            start_date=start_date,
+            end_date=end_date,
+            is_open=is_open,
+            is_week_end=is_week_end,
+            is_month_end=is_month_end,
+            is_quarter_end=is_quarter_end,
+            is_year_end=is_year_end,
+            fields=fields,
+        )
+
+    def etf_adj_daily(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        adjusting_standard: int = 2,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询 ETF 后复权行情（13 列）。
+
+        ``adjusting_standard`` 取 ``1`` 精确复权（现金分红口径）或 ``2`` 比例复权
+        （分红再投口径，默认）；两者价格序列不可混用。本表字典说明"均为后复权"，
+        故 ``adjusting_method`` 固定为 ``2``，不提供前复权。
+        """
+        return self.query(
+            "etf_adj_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            adjusting_standard=adjusting_standard,
+            fields=fields,
+        )
+
+    def etf_basic(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        index_code: str | list[str] | None = None,
+        list_date: Any = None,
+        list_status: str | None = None,
+        exchange: str | None = None,
+        mgr: str | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询 ETF 基础信息。
+
+        参数与 Tushare ``etf_basic`` 对齐：``ts_code`` 可带 ``.SH``/``.SZ`` 后缀
+        或纯代码（服务端剥离后缀后匹配，并校验后缀与交易所一致）；``index_code``
+        是跟踪目标代码，可能是指数，也可能是现货/商品标的；``list_status`` 取
+        ``L``/``D``/``P``；``exchange`` 取 ``SH``/``SZ``；``mgr`` 按管理人简称
+        模糊匹配。返回 16 列，其中 ``inner_code``（ETF 聚源内码）与
+        ``index_inner_code``（跟踪目标聚源内码）是 ffdata 扩展字段；不传任何过滤
+        条件时返回全部沪深上市 ETF。本接口仅支持远程查询。
+        """
+        return self.query(
+            "etf_basic",
+            ts_code=ts_code,
+            index_code=index_code,
+            list_date=list_date,
+            list_status=list_status,
+            exchange=exchange,
+            mgr=mgr,
+            fields=fields,
+        )
+
+    def etf_daily(
+        self,
+        ts_code: str | list[str] | None = None,
+        *,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询 ETF 日线行情。
+
+        ``ts_code`` 可带 ``.SH``/``.SZ`` 后缀或纯代码，支持列表与逗号分隔；至少要传
+        ``ts_code`` 或 ``trade_date`` 之一，``trade_date`` 与日期区间互斥，只给区间而
+        不给代码会被拒绝。返回 83 列：Tushare ``fund_daily`` 的 11 列兼容段 +
+        ``inner_code`` + 日表现扩展列 + 近一周/近一月/近一年区间表现列；``vol`` 与区间
+        成交量为**份**，``amount`` 为**元**。本接口仅支持远程查询。
+        """
+        return self.query(
+            "etf_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def fund_basic(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        market: str | None = None,
+        status: str | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询公募基金列表（71 列，对齐 Tushare ``fund_basic`` 并输出聚源全字段）。
+
+        ``ts_code`` 可带 ``.SH``/``.SZ``（场内）或 ``.OF``（场外）后缀；``market`` 取
+        ``E`` 场内 / ``O`` 场外，**默认返回场内 + 场外全部**（与 Tushare 默认 ``E`` 不同）；
+        ``status`` 取 ``D`` 已到期终止 / ``I`` 发行中 / ``L`` 已设立存续。
+        聚源主表无来源的 9 个 Tushare 列（``issue_date``/``delist_date``/``m_fee``/``c_fee``/
+        ``p_value``/``exp_return``/``trustee``/``purc_startdate``/``redm_startdate``）不在本接口输出。
+        """
+        return self.query(
+            "fund_basic",
+            ts_code=ts_code,
+            market=market,
+            status=status,
+            fields=fields,
+        )
+
+    def cb_daily(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询可转债行情（22 列，对齐 Tushare ``cb_daily`` 的前 11 列 + 聚源扩展）。
+
+        ``trade_date`` 与 ``start_date``/``end_date`` 互斥，且至少需要 ``ts_code`` 或
+        ``trade_date`` 之一。`vol` 与聚源 ``TurnoverVolume`` 同口径（不做单位换算），
+        `amount` 为元。Tushare 的纯债价值/溢价率与转股价值/溢价率 4 列不在本接口，
+        请调用 :meth:`cb_deriv`（可按 ``ts_code + trade_date`` 合并）。
+        """
+        return self.query(
+            "cb_daily",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def cb_deriv(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        trade_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        exchange: str | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询可转债衍生指标（26 列，ffdata 扩展接口）。
+
+        提供 Tushare ``cb_daily`` 对应关系：``cb_strb_value``（纯债价值）、
+        ``cb_strb_premium_ratio``（纯债溢价率）、``cb_convert_value``（转股价值）、
+        ``convert_premium_rate``（转股溢价率），以及 YTM、久期、凸性、双低等指标。
+        过滤规则与 :meth:`cb_daily` 相同，另支持 ``exchange``（``SH``/``SZ``）。
+        """
+        return self.query(
+            "cb_deriv",
+            ts_code=ts_code,
+            trade_date=trade_date,
+            start_date=start_date,
+            end_date=end_date,
+            exchange=exchange,
+            fields=fields,
+        )
+
+    def cb_issue(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        ann_date: Any = None,
+        start_date: Any = None,
+        end_date: Any = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询可转债发行信息（90 列，对齐 Tushare ``cb_issue`` + 聚源全字段）。
+
+        ``ann_date`` 为发行公告日（服务端按聚源募集说明书发布日比较），与日期区间互斥；
+        不传任何过滤条件时返回全部历史可转债发行记录。兼容段一律为聚源原值：
+        ``onl_size``/``shd_ration_size``/``offl_size`` 单位为**元**（Tushare 为张，
+        可按 ``par_value`` 换算）；``shd_ration_price`` 聚源无来源，本接口不输出该列。
+        """
+        return self.query(
+            "cb_issue",
+            ts_code=ts_code,
+            ann_date=ann_date,
+            start_date=start_date,
+            end_date=end_date,
+            fields=fields,
+        )
+
+    def cb_basic(
+        self,
+        *,
+        ts_code: str | list[str] | None = None,
+        list_date: Any = None,
+        exchange: str | None = None,
+        latest_status: int | None = None,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """查询可转债基本信息。
+
+        参数与 Tushare ``cb_basic`` 对齐，并额外支持 ``latest_status``：``ts_code`` 可带
+        ``.SH``/``.SZ`` 后缀或纯代码，支持列表与逗号分隔（服务端剥离后缀匹配并校验市场一致）；
+        ``list_date`` 为上市日期（精确到日）；``exchange`` 取 ``SH``/``SZ``；
+        ``latest_status`` 为聚源最新状态（``1`` 发行中、``2`` 存续中、``3`` 已到期、
+        ``4`` 发行失败）。返回 125 列：38 列 Tushare 兼容段 + 74 列聚源主表扩展 +
+        13 列关联扩展（含条款文本、最新评级、剩余金额等）。不传过滤条件时返回全部沪深
+        可转债；本接口仅支持远程查询。
+        """
+        return self.query(
+            "cb_basic",
+            ts_code=ts_code,
+            list_date=list_date,
+            exchange=exchange,
+            latest_status=latest_status,
+            fields=fields,
+        )
+
+
+__all__ = ["Client", "Source"]

ffdata/datasets/__init__.py

@@ -0,0 +1,5 @@
+"""客户端标准数据集管理。"""
+
+from .manager import DatasetManager
+
+__all__ = ["DatasetManager"]

ffdata/datasets/manager.py

@@ -0,0 +1,132 @@
+"""客户端本地数据集的事务式同步。
+
+同步采用 manifest 差异比较、断点续传、文件大小与 SHA-256 校验，并在全部分片
+成功后原子替换本地 manifest，避免查询到半更新状态的数据集。
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from ffdata_common.errors import DatasetError
+
+from ..local import LocalStore
+from ..transport import HttpTransport
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+class DatasetManager:
+    """管理远程数据集发现、本地状态检查、同步和完整性校验。"""
+
+    def __init__(self, transport: HttpTransport, local_store: LocalStore):
+        self.transport = transport
+        self.local_store = local_store
+
+    def list(self) -> list[str]:
+        return self.transport.dataset_names()
+
+    def status(self, name: str) -> dict[str, Any]:
+        local = self.local_store.manifest(name)
+        remote = self.transport.dataset_manifest(name)
+        complete = bool(local) and all(
+            (self.local_store.root / name / item.path).is_file() for item in local.files
+        )
+        return {
+            "dataset": name,
+            "installed": local is not None,
+            "complete": complete,
+            "local_version": local.version if local else None,
+            "remote_version": remote.version,
+            "update_available": local is None or local.version != remote.version,
+        }
+
+    def sync(self, name: str) -> dict[str, Any]:
+        """增量同步指定数据集，返回下载文件数和最终版本。"""
+        remote = self.transport.dataset_manifest(name)
+        local = self.local_store.manifest(name)
+        local_files = {item.path: item for item in local.files} if local else {}
+        dataset_root = self.local_store.root / name
+        dataset_root.mkdir(parents=True, exist_ok=True)
+
+        pending = []
+        for item in remote.files:
+            target = dataset_root / item.path
+            local_item = local_files.get(item.path)
+            if target.is_file() and target.stat().st_size == item.size:
+                if local_item is not None and local_item.sha256 == item.sha256:
+                    continue
+                if _sha256(target) == item.sha256:
+                    continue
+            pending.append(item.path)
+
+        if pending:
+            plan = self.transport.download_plan(name, pending)
+            planned = {item.path: item for item in plan.files}
+            if set(planned) != set(pending):
+                raise DatasetError("download plan does not match the requested files")
+            for manifest_file in remote.files:
+                if manifest_file.path not in planned:
+                    continue
+                target = dataset_root / manifest_file.path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                partial = target.with_suffix(f"{target.suffix}.partial")
+                offset = partial.stat().st_size if partial.is_file() else 0
+                if offset > manifest_file.size:
+                    partial.unlink()
+                    offset = 0
+                self.transport.download(
+                    planned[manifest_file.path].url,
+                    partial,
+                    offset=offset,
+                )
+                if partial.stat().st_size != manifest_file.size:
+                    raise DatasetError(f"downloaded size mismatch for {manifest_file.path}")
+                if _sha256(partial) != manifest_file.sha256:
+                    raise DatasetError(f"checksum mismatch for {manifest_file.path}")
+                partial.replace(target)
+
+        manifest_path = dataset_root / "manifest.json"
+        temporary = manifest_path.with_suffix(".json.partial")
+        temporary.write_text(remote.model_dump_json(indent=2), encoding="utf-8")
+        temporary.replace(manifest_path)
+        return {
+            "dataset": name,
+            "version": remote.version,
+            "downloaded_files": len(pending),
+            "total_files": len(remote.files),
+            "path": str(dataset_root),
+        }
+
+    def verify(self, name: str) -> dict[str, Any]:
+        """重新计算本地全部分片的 SHA-256，报告损坏或缺失文件。"""
+        manifest = self.local_store.manifest(name)
+        if manifest is None:
+            raise DatasetError(f"local dataset {name!r} is not installed")
+        invalid: list[str] = []
+        for item in manifest.files:
+            path = self.local_store.root / name / item.path
+            if (
+                not path.is_file()
+                or path.stat().st_size != item.size
+                or _sha256(path) != item.sha256
+            ):
+                invalid.append(item.path)
+        return {
+            "dataset": name,
+            "version": manifest.version,
+            "valid": not invalid,
+            "invalid_files": invalid,
+            "total_files": len(manifest.files),
+        }
+
+
+__all__ = ["DatasetManager"]

ffdata/local/__init__.py

@@ -0,0 +1,5 @@
+"""客户端本地数据查询实现。"""
+
+from .store import LocalStore
+
+__all__ = ["LocalStore"]