spts 0.1.0

通用数据查询 SDK — 远程客户端，零外部依赖

spts

通用数据查询 SDK（远程客户端），零外部依赖，仅需 Python 标准库。

指向已部署的查询服务即可获取金融数据，无需数据库密码或 Tushare token。

安装

pip install spts

快速上手

from spts import RemoteClient

client = RemoteClient("https://your-server.com")
result = client.query(
    api_name="daily_basic",
    ts_code="000001.SZ",
    start_date="20180101",
    end_date="20181231",
    limit=100,
)

print(result["source"])       # "database" 或 "tushare"
print(result["columns"])      # ["ts_code", "trade_date", "close", ...]
print(result["rows"])         # [[...], ...]
print(result["row_count"])    # 行数

也可以使用预置的默认客户端和快捷函数：

from spts import set_default_base_url, query_remote

set_default_base_url("https://your-server.com")
result = query_remote(api_name="daily_basic", ts_code="000001.SZ", ...)

支持的接口

api_name	说明
stock_basic	股票基础信息列表
daily	股票日线行情
daily_basic	股票每日指标
moneyflow_dc	个股资金流向（DC）
fina_indicator	财务指标数据
income	利润表
balancesheet	资产负债表
cashflow	现金流量表
fina_audit	财务审计意见

API 参考

RemoteClient(base_url, timeout=30)

参数	类型	说明
base_url	str	查询服务地址，如 "http://your-server.com"
timeout	int	请求超时秒数，默认 30

query(api_name, fields=None, params=None, limit=None, **kwargs) → dict

调用远程 GET /api/new_query 查询数据。

参数	类型	说明
api_name	str	接口/表名，如 "daily", "cashflow"
fields	str | list | None	返回字段，逗号分隔或列表
params	dict | None	过滤参数字典
limit	int | None	返回行数上限
**kwargs	Any	其他关键字参数作为过滤条件传入

返回结构：

{
    "api_name": "daily_basic",
    "source": "database",           # "database" | "tushare"
    "fields": None,
    "columns": ["ts_code", ...],
    "rows": [[...], ...],
    "row_count": 100,
    # "fallback_reason": "..."      # 仅降级到 Tushare 时出现
}

两种传参方式等价：

# 方式 1：直接传 **kwargs
client.query(api_name="daily", ts_code="000001.SZ", start_date="20240101")

# 方式 2：用 params 字典
client.query(api_name="daily", params={"ts_code": "000001.SZ", "start_date": "20240101"})

ping() → bool

检测远程服务是否可达。

set_default_base_url(url)

设置模块级默认服务地址，之后 query_remote() 无需每次传入 base_url。

query_remote(api_name, fields=None, params=None, limit=None, base_url=None) → dict

模块级快捷查询函数，参数同 RemoteClient.query()。

client

模块级默认 RemoteClient 实例，初始指向 http://localhost:9000。可通过 from spts import client 直接使用：

from spts import client

result = client.query(api_name="daily", ts_code="000001.SZ")

数据分级策略

服务端采用数据库优先 → Tushare 降级策略：

1. 优先以 api_name 作为表名在 PostgreSQL 中查询
2. 若结果为空或查询异常，自动降级调用 Tushare API 获取数据

返回结果的 source 字段指示实际数据来源（"database" 或 "tushare"）。

License

MIT