跳到主要内容

Python SDK 快速开始

Python 子项目适合 Python 应用、Notebook、研究脚本和本地 DuckDB 工作流。它包含两条路径：

  • 远程 toolkit：获取最新行情、财报、估值、指数、基金和特色数据。
  • marketdb：管理本地历史行情、复权数据、面板和只读 SQL 研究数据集。
GitHub · Python 源码

打开 Python 子项目，查看最新源码、README 和目录结构。

GitHub · 可执行示例

直接查看可运行的 Python 示例和使用场景。

当前安装方式

Python 子项目当前从 GitHub monorepo 源码安装，不是独立 PyPI 包。下面的命令都在仓库根目录执行。

完成后你将拥有​

  • 可直接执行的远程金融数据 JSON CLI。
  • 可在 Python 中调用的远程 client 函数。
  • 可选的本地 DuckDB 数据库和 MarketDB Python API。

前置条件​

  • Python 3.11 或更高版本。
  • Git 和 pip。
  • 从 API Key 管理 创建的 Key（仅远程取数需要）。

检查环境：

python --version
git --version
python -m pip --version

第 1 步：获取源码并安装​

建议先创建独立虚拟环境：

git clone https://github.com/HiThink-Tech/Financial-API.git
cd Financial-API
python -m venv .venv

激活虚拟环境。PowerShell：

.\.venv\Scripts\Activate.ps1

macOS/Linux：

source .venv/bin/activate

然后从 monorepo 根目录安装 Python 子项目：

python -m pip install -e ./python

验证安装和脚本入口：

python python/toolkit/fuyao/scripts/fuyao.py --help
marketdb --help

第 2 步：配置 API Key​

只在当前 PowerShell 进程中设置：

$secureKey = Read-Host 'API Key' -AsSecureString
$key = [System.Net.NetworkCredential]::new('', $secureKey).Password
$env:HITHINK_FINANCE_API_KEY = $key
Remove-Variable key, secureKey

macOS/Linux Shell：

read -rsp 'API Key: ' HITHINK_FINANCE_API_KEY; echo
export HITHINK_FINANCE_API_KEY

Python toolkit 也会读取用户级 hithink-finance/credentials.env。不要将真实 Key 写入示例脚本、Notebook、项目 .env、日志或 Git。

第 3 步：完成首次远程查询​

先用名称搜索唯一标准证券代码 thscode：

python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"

确认返回的 thscode 为 600519.SH 后，查询最新行情：

python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH

成功判定​

首次接入成功应同时满足：

  1. 进程退出码为 0。
  2. stdout 是可解析的 JSON，而不是 HTML 或认证错误。
  3. 响应中存在 600519.SH 的真实数据记录。

远程 JSON CLI 的退出码为：0 成功、2 上游业务错误、3 本地参数错误、4 环境或运行错误。

第 4 步：在 Python 代码中调用​

远程 client 是仓库内的轻量适配模块。在仓库根目录新建脚本时，可显式加入模块路径：

import sys
from pathlib import Path

sys.path.insert(0, str(Path("python/toolkit/fuyao/scripts").resolve()))

from fuyao_client import prices_snapshot, tickers_search

hit = tickers_search("贵州茅台", limit=1)[0]
snapshot = prices_snapshot([hit["thscode"]])
print(snapshot)

调用前应先将名称或不完整代码消歧为唯一 thscode，不要猜测 .SH、.SZ 或 .BJ 后缀。上游业务错误会通过 FuyaoApiError 暴露 code、message 和 request_id。

可选：初始化本地 marketdb​

marketdb 适合长期历史行情、复权、全市场面板和 SQL 研究。如果只需要最新数据，可以跳过本节。

python python/bootstrap.py
marketdb status --json --db data/market.duckdb
marketdb validate --json --db data/market.duckdb

bootstrap.py 会安装包、初始化数据库并按配置同步数据，可能耗时较长。请等待命令完整结束后再查询同一数据库。

Python 代码可直接读取已初始化的本地库：

from marketdb import MarketDB

with MarketDB.open("data/market.duckdb") as db:
    daily = db.get_daily("600519.SH", start="2025-01-01", adjust="forward")
    print(daily.tail())

常见问题​

ModuleNotFoundError​

确认已激活安装时使用的虚拟环境，并且命令从 monorepo 根目录执行。远程 fuyao_client.py 还需要按上面示例加入其脚本目录。

返回认证错误​

确认当前 Python 进程已继承 HITHINK_FINANCE_API_KEY。新开终端后，用户级环境变量才会自动进入新进程。

结果过大​

全市场、多年、多标的或分页全集应写入 JSON、CSV 或 Parquet 文件，只在终端保留路径、行数、时间窗口和摘要。长期全市场研究优先使用 marketdb。

下一步​