ffdata 0.2.0__py3-none-any.whl

ffdata/__init__.py

@@ -0,0 +1,162 @@
+"""ffdata 轻量客户端的公共入口。
+
+本模块提供全局客户端配置和与 ``Client`` 同名的便捷查询函数。研究代码只需
+依赖本包，不需要接触数据库连接、聚源表结构或服务端配置。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from .client import Client
+
+_default_client: Client | None = None
+
+
+def configure(
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+    data_dir: str | Path | None = None,
+) -> Client:
+    """创建并保存模块级默认客户端，返回该客户端实例。"""
+    global _default_client
+    _default_client = Client(
+        base_url=base_url or os.getenv("FFDATA_BASE_URL", "http://127.0.0.1:8000"),
+        token=token or os.getenv("FFDATA_TOKEN"),
+        data_dir=data_dir,
+    )
+    return _default_client
+
+
+def set_token(token: str) -> None:
+    """仅更新默认客户端使用的 Token。"""
+    configure(token=token)
+
+
+def _client() -> Client:
+    return _default_client or configure()
+
+
+def query(api_name: str, **params: Any):
+    """通过默认客户端调用通用数据查询接口。"""
+    return _client().query(api_name, **params)
+
+
+def sql_query(sql: str, **kwargs: Any):
+    """通过默认客户端执行单条受限 SELECT。"""
+    return _client().sql_query(sql, **kwargs)
+
+
+def stock_daily(*args: Any, **kwargs: Any):
+    return _client().stock_daily(*args, **kwargs)
+
+
+def stock_adjusting_factor(*args: Any, **kwargs: Any):
+    return _client().stock_adjusting_factor(*args, **kwargs)
+
+
+def stock_valuation_daily(*args: Any, **kwargs: Any):
+    """通过默认客户端查询 A 股估值分析（日频）。"""
+    return _client().stock_valuation_daily(*args, **kwargs)
+
+
+def index_daily(*args: Any, **kwargs: Any):
+    return _client().index_daily(*args, **kwargs)
+
+
+def index_basic(*args: Any, **kwargs: Any):
+    """通过默认客户端查询指数基本信息（返回含 inner_code 指数聚源内码）。"""
+    return _client().index_basic(*args, **kwargs)
+
+
+def index_weight(*args: Any, **kwargs: Any):
+    """通过默认客户端查询指数成分与权重。"""
+    return _client().index_weight(*args, **kwargs)
+
+
+def etf_basic(*args: Any, **kwargs: Any):
+    """通过默认客户端查询 ETF 基础信息（返回含 ETF 与跟踪目标两个聚源内码）。"""
+    return _client().etf_basic(*args, **kwargs)
+
+
+def etf_daily(*args: Any, **kwargs: Any):
+    """通过默认客户端查询 ETF 日线行情（83 列，含聚源区间表现列）。"""
+    return _client().etf_daily(*args, **kwargs)
+
+
+def etf_adj_daily(*args: Any, **kwargs: Any):
+    """通过默认客户端查询 ETF 后复权行情（13 列，支持精确/比例复权口径）。"""
+    return _client().etf_adj_daily(*args, **kwargs)
+
+
+def cb_basic(*args: Any, **kwargs: Any):
+    """通过默认客户端查询可转债基本信息（125 列，含条款文本与最新评级）。"""
+    return _client().cb_basic(*args, **kwargs)
+
+
+def cb_daily(*args: Any, **kwargs: Any):
+    """通过默认客户端查询可转债行情（22 列，对齐 Tushare cb_daily 前 11 列）。"""
+    return _client().cb_daily(*args, **kwargs)
+
+
+def cb_deriv(*args: Any, **kwargs: Any):
+    """通过默认客户端查询可转债衍生指标（26 列，含 YTM、久期、凸性、双低）。"""
+    return _client().cb_deriv(*args, **kwargs)
+
+
+def cb_issue(*args: Any, **kwargs: Any):
+    """通过默认客户端查询可转债发行信息（90 列，对齐 Tushare cb_issue 并输出聚源全字段）。"""
+    return _client().cb_issue(*args, **kwargs)
+
+
+def fund_basic(*args: Any, **kwargs: Any):
+    """通过默认客户端查询公募基金列表（71 列，含管理人/托管人全称与投资范围）。"""
+    return _client().fund_basic(*args, **kwargs)
+
+
+def macro_indicator_basic(*args: Any, **kwargs: Any):
+    return _client().macro_indicator_basic(*args, **kwargs)
+
+
+def macro_indicator_data(*args: Any, **kwargs: Any):
+    return _client().macro_indicator_data(*args, **kwargs)
+
+
+def trade_cal(*args: Any, **kwargs: Any):
+    """通过默认客户端查询交易日历（8 列，支持沪深/北交所/港股/美股/银行间）。"""
+    return _client().trade_cal(*args, **kwargs)
+
+
+def stock_basic(*args: Any, **kwargs: Any):
+    """通过默认客户端查询股票列表基础信息（18 列，含退市日期与沪深港通标的）。"""
+    return _client().stock_basic(*args, **kwargs)
+
+
+__all__ = [
+    "Client",
+    "cb_basic",
+    "cb_daily",
+    "cb_deriv",
+    "cb_issue",
+    "configure",
+    "etf_adj_daily",
+    "etf_basic",
+    "etf_daily",
+    "fund_basic",
+    "index_basic",
+    "index_daily",
+    "index_weight",
+    "macro_indicator_basic",
+    "macro_indicator_data",
+    "query",
+    "sql_query",
+    "set_token",
+    "stock_adjusting_factor",
+    "stock_basic",
+    "stock_daily",
+    "stock_valuation_daily",
+    "trade_cal",
+]

ffdata/cli.py

@@ -0,0 +1,46 @@
+"""ffdata 客户端命令行入口，提供数据集查询、同步和校验命令。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+from .client import Client
+
+
+def _client() -> Client:
+    return Client(
+        base_url=os.getenv("FFDATA_BASE_URL", "http://127.0.0.1:8000"),
+        token=os.getenv("FFDATA_TOKEN"),
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="ffdata")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    dataset = subparsers.add_parser("dataset")
+    dataset_commands = dataset.add_subparsers(dest="dataset_command", required=True)
+    dataset_commands.add_parser("list")
+    status = dataset_commands.add_parser("status")
+    status.add_argument("name")
+    sync = dataset_commands.add_parser("sync")
+    sync.add_argument("name")
+    verify = dataset_commands.add_parser("verify")
+    verify.add_argument("name")
+    args = parser.parse_args()
+
+    with _client() as client:
+        if args.dataset_command == "list":
+            result = {"datasets": client.datasets.list()}
+        elif args.dataset_command == "status":
+            result = client.datasets.status(args.name)
+        elif args.dataset_command == "sync":
+            result = client.datasets.sync(args.name)
+        else:
+            result = client.datasets.verify(args.name)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()