Metadata-Version: 2.4
Name: spts
Version: 0.1.0
Summary: 通用数据查询 SDK — 远程客户端，零外部依赖
Author-email: Your Name <you@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/pg-ops-service-sdk
Project-URL: Repository, https://github.com/your-org/pg-ops-service-sdk
Keywords: data-query,sdk,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# spts

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

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

## 安装

```bash
pip install spts
```

## 快速上手

```python
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"])    # 行数
```

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

```python
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` | 其他关键字参数作为过滤条件传入 |

返回结构：

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

两种传参方式等价：

```python
# 方式 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` 直接使用：

```python
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
