ffdata 0.2.0__tar.gz

ffdata-0.2.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: ffdata
+Version: 0.2.0
+Summary: ffdata lightweight Python client for governed financial-data APIs
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pandas>=3.0.5
+Requires-Dist: polars>=1.43.2
+Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: pydantic>=2.11.0
+
+# ffdata
+
+`ffdata` 是面向量化研究的轻量 Python 客户端。它只通过 HTTP 调用已部署的
+ffdata 数据服务，不包含服务端、JYDB SQL、数据库配置或后台管理实现。
+
+完整的客户端职责说明见 [客户端模块说明](../docs/模块说明/客户端.md)；安装、构建和升级见
+[客户端打包与交付](../docs/部署与运维/客户端打包与交付.md)；每个对外 API 的可运行案例见
+[使用案例](examples/README.md)。
+
+## 配置服务地址与 Token
+
+安装客户端 wheel 后运行：
+
+```bash
+source "$(dirname "$(command -v ffdata)")/configure_ffdata.sh"
+```
+
+脚本会交互式设置 `FFDATA_BASE_URL` 与 `FFDATA_TOKEN`，Token 输入不回显，并将两者写入
+`~/.bash_profile`（仅当前用户可读）。因此新的 Bash 终端及其他项目都能直接读取配置；若当前使用
+的是 zsh 等其他 shell，可执行 `source ~/.bash_profile` 加载。

ffdata-0.2.0/README.md

@@ -0,0 +1,20 @@
+# ffdata
+
+`ffdata` 是面向量化研究的轻量 Python 客户端。它只通过 HTTP 调用已部署的
+ffdata 数据服务，不包含服务端、JYDB SQL、数据库配置或后台管理实现。
+
+完整的客户端职责说明见 [客户端模块说明](../docs/模块说明/客户端.md)；安装、构建和升级见
+[客户端打包与交付](../docs/部署与运维/客户端打包与交付.md)；每个对外 API 的可运行案例见
+[使用案例](examples/README.md)。
+
+## 配置服务地址与 Token
+
+安装客户端 wheel 后运行：
+
+```bash
+source "$(dirname "$(command -v ffdata)")/configure_ffdata.sh"
+```
+
+脚本会交互式设置 `FFDATA_BASE_URL` 与 `FFDATA_TOKEN`，Token 输入不回显，并将两者写入
+`~/.bash_profile`（仅当前用户可读）。因此新的 Bash 终端及其他项目都能直接读取配置；若当前使用
+的是 zsh 等其他 shell，可执行 `source ~/.bash_profile` 加载。

ffdata-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "ffdata"
+version = "0.2.0"
+description = "ffdata lightweight Python client for governed financial-data APIs"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "httpx>=0.28.0",
+    "pandas>=3.0.5",
+    "polars>=1.43.2",
+    "pyarrow>=21.0.0",
+    "pydantic>=2.11.0",
+]
+
+[project.scripts]
+ffdata = "ffdata.cli:main"
+
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+script-files = ["scripts/configure_ffdata.sh"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ffdata", "ffdata.*", "ffdata_common", "ffdata_common.*"]

ffdata-0.2.0/scripts/configure_ffdata.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# 配置 ffdata 客户端所需的服务地址与研究员 Token。
+# 请使用 source 执行本脚本，使环境变量立即对当前终端生效：
+#   source client/scripts/configure_ffdata.sh
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  printf '%s\n' "请使用 source 执行本脚本：source client/scripts/configure_ffdata.sh" >&2
+  exit 1
+fi
+
+printf '%s' 'ffdata 服务地址 [http://127.0.0.1:8000]: '
+IFS= read -r FFDATA_SETUP_BASE_URL
+FFDATA_SETUP_BASE_URL=${FFDATA_SETUP_BASE_URL:-http://127.0.0.1:8000}
+
+case "$FFDATA_SETUP_BASE_URL" in
+  http://*|https://*) ;;
+  *)
+    printf '%s\n' '服务地址必须以 http:// 或 https:// 开头。' >&2
+    return 1
+    ;;
+esac
+
+printf '%s' '研究员 Token（输入不回显）: '
+IFS= read -r -s FFDATA_SETUP_TOKEN
+printf '\n'
+if [[ -z "$FFDATA_SETUP_TOKEN" ]]; then
+  printf '%s\n' 'Token 不能为空。' >&2
+  return 1
+fi
+
+export FFDATA_BASE_URL="$FFDATA_SETUP_BASE_URL"
+export FFDATA_TOKEN="$FFDATA_SETUP_TOKEN"
+
+FFDATA_SETUP_PROFILE="$HOME/.bash_profile"
+FFDATA_SETUP_TEMP_FILE=$(mktemp "$HOME/.bash_profile.ffdata.XXXXXX")
+
+if [[ -f "$FFDATA_SETUP_PROFILE" ]]; then
+  awk '
+    /^# >>> ffdata environment >>>$/ { in_ffdata_block = 1; next }
+    /^# <<< ffdata environment <<</ { in_ffdata_block = 0; next }
+    !in_ffdata_block { print }
+  ' "$FFDATA_SETUP_PROFILE" > "$FFDATA_SETUP_TEMP_FILE"
+fi
+
+{
+  printf '\n# >>> ffdata environment >>>\n'
+  printf 'export FFDATA_BASE_URL=%q\n' "$FFDATA_BASE_URL"
+  printf 'export FFDATA_TOKEN=%q\n' "$FFDATA_TOKEN"
+  printf '# <<< ffdata environment <<<\n'
+} >> "$FFDATA_SETUP_TEMP_FILE"
+
+mv "$FFDATA_SETUP_TEMP_FILE" "$FFDATA_SETUP_PROFILE"
+chmod 600 "$FFDATA_SETUP_PROFILE"
+
+printf '%s\n' '当前终端已设置 FFDATA_BASE_URL 与 FFDATA_TOKEN。'
+printf '%s\n' "已写入 $FFDATA_SETUP_PROFILE（仅当前用户可读）。"
+printf '%s\n' '新的 Bash 终端会自动加载；使用其他 shell 时可执行：source ~/.bash_profile'
+
+unset FFDATA_SETUP_BASE_URL FFDATA_SETUP_TOKEN FFDATA_SETUP_PROFILE FFDATA_SETUP_TEMP_FILE

ffdata-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ffdata-0.2.0/src/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-0.2.0/src/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()