Metadata-Version: 2.4
Name: stock-gateway
Version: 0.1.3
Summary: A-share data aggregation SDK with explicit gateway APIs.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: requests>=2.31.0
Requires-Dist: thsdk>=1.7.18
Requires-Dist: mootdx>=0.11.7
Requires-Dist: lxml>=6.1.1

# Stock Gateway

A 股数据采集、聚合、研究和复盘辅助 Python SDK。项目对外提供显式网关方法，例如 `get_quote()`、`get_kline()`、`get_depth()`，调用方无需直接关心底层数据源 provider。

> 本 SDK 用于数据获取和研究辅助，不提供投资建议，也不是自动交易系统。

## 安装

```bash
pip install stock-gateway
```

指定版本：

```bash
pip install stock-gateway==0.1.3
```

运行环境：

- Python `>=3.11`
- 默认依赖：`pandas`、`requests`、`thsdk`、`mootdx`、`lxml`
- 使用 `thsdk` provider 时建议配置 `THS_USERNAME`、`THS_PASSWORD`；可选配置 `THS_MAC`

## 快速开始

```python
from stock_gateway import StockGateway

gateway = StockGateway()

quote = gateway.get_quote("300498")
print(quote.ok, quote.provider, quote.error)
print(quote.data)

kline = gateway.get_kline("300498", interval="day", count=120)
print(kline.ok, kline.provider, kline.error)
print(kline.data)
```

使用完真实 provider 后，可以关闭 provider 持有的连接：

```python
for provider in gateway.providers.values():
    close = getattr(provider, "close", None) or getattr(provider, "disconnect", None)
    if callable(close):
        close()
```

## 返回值

所有接口返回 `GatewayResult`：

| 字段 | 含义 |
| --- | --- |
| `ok` | 请求是否成功 |
| `data` | 标准化后的数据，常见为 `pandas.DataFrame`、`dict`、`list` 或 `bytes` |
| `provider` | 实际命中的数据源 |
| `schema` | 标准化字段 schema |
| `warnings` | 警告信息，例如兼容降级说明 |
| `fallback_chain` | provider 尝试和降级链路 |
| `error` | 失败时的错误信息 |
| `raw` | provider 原始结果，便于调试 |
| `symbol` / `normalized_symbol` | 输入代码和标准化代码信息 |
| `latency_ms` | 最终命中 provider 的耗时 |

示例：

```python
result = gateway.get_quote(["600519", "300498"])

if result.ok:
    print(result.data)
else:
    print(result.error)

for attempt in result.fallback_chain:
    print(attempt.provider, attempt.status, attempt.error_type, attempt.error)
```

## 股票代码

常用接口可直接传 6 位 A 股代码：

```python
gateway.get_quote("600519")
gateway.get_kline("300498", interval="1m", count=260)
```

SDK 会在内部转换为各 provider 需要的代码格式，例如腾讯、新浪、东方财富、同花顺和通达信格式。

## Provider 与降级

默认 `provider="auto"`，SDK 会按接口策略选择 provider，并在语义兼容时自动降级。降级过程会写入 `fallback_chain`，不会静默换源。

```python
result = gateway.get_kline("300498", interval="day")
print(result.provider)
print([(item.provider, item.status) for item in result.fallback_chain])
```

也可以指定 provider 并关闭降级：

```python
result = gateway.get_quote("300498", provider="tencent", fallback=False)
```

常见 provider 名称包括：

- `thsdk`
- `mootdx`
- `tencent`
- `sina`
- `baidu`
- `eastmoney`
- `cninfo`
- `ths_hot`
- `jiuyangongshe`
- `timor`

## 已实现接口

### 行情与交易数据

| 方法 | 用途 |
| --- | --- |
| `get_quote(codes, provider="auto", fallback=True)` | 实时行情，支持单代码或代码列表 |
| `get_kline(code, interval="day", count=None, start=None, end=None, adjust=None, provider="auto", fallback=True)` | K 线数据，支持日线和常见分钟周期 |
| `get_depth(code, provider="auto", fallback=True)` | 盘口深度 |
| `get_intraday(code, date=None, provider="auto", fallback=True)` | 日内分时 |
| `get_transaction(code, date=None, provider="auto", fallback=True)` | 逐笔成交 |
| `get_chart_image(code, period="daily", provider="auto", fallback=True)` | 走势图图片 bytes |

### 新闻、公告与资讯

| 方法 | 用途 |
| --- | --- |
| `get_stock_news(code, limit=20, provider="auto", fallback=True)` | 个股新闻 |
| `get_global_news(limit=50, provider="auto", fallback=True)` | 全市场资讯 |
| `get_announcements(code, limit=30, provider="auto", fallback=True)` | 公司公告 |

### 资金、筹码与交易异动

| 方法 | 用途 |
| --- | --- |
| `get_fund_flow(code, period="minute", provider="auto", fallback=True)` | 资金流 |
| `get_fund_flow_120d(code, provider="auto", fallback=True)` | 近 120 日资金流 |
| `get_margin(code, provider="auto", fallback=True)` | 融资融券 |
| `get_block_trade(code, provider="auto", fallback=True)` | 大宗交易 |
| `get_holder_num(code, provider="auto", fallback=True)` | 股东户数 |
| `get_dividend(code, provider="auto", fallback=True)` | 分红送配 |
| `get_lockup_expiry(code, forward_days=90, provider="auto", fallback=True)` | 限售解禁 |
| `get_dragon_tiger(code, trade_date=None, look_back=30, provider="auto", fallback=True)` | 个股龙虎榜 |
| `get_daily_dragon_tiger(trade_date=None, provider="auto", fallback=True)` | 每日龙虎榜 |

### 指数、板块与题材

| 方法 | 用途 |
| --- | --- |
| `get_index_quote(index_code, provider="auto", fallback=True)` | 指数行情 |
| `get_index_kline(index_code, interval="day", provider="auto", fallback=True)` | 指数 K 线 |
| `get_index_list(provider="auto", fallback=True)` | 指数列表 |
| `get_sector_list(sector_type="industry", provider="auto", fallback=True)` | 板块列表 |
| `get_sector_quote(sector_code, provider="auto", fallback=True)` | 板块行情 |
| `get_sector_constituents(sector_code, provider="auto", fallback=True)` | 板块成分股 |
| `get_industry_rank(top_n=20, provider="auto", fallback=True)` | 行业涨跌排行 |
| `get_concept_blocks(code, provider="auto", fallback=True)` | 个股题材归属 |
| `get_hot_reason(date=None, provider="auto", fallback=True)` | 热点题材归因 |

### 交易日历

| 方法 | 用途 |
| --- | --- |
| `is_trading_day(date, provider="auto", fallback=True)` | 判断日期是否为交易日 |

### 财务、估值与研报

| 方法 | 用途 |
| --- | --- |
| `get_finance_snapshot(code, provider="auto", fallback=True)` | 财务快照 |
| `get_stock_info(code, provider="auto", fallback=True)` | 个股基础信息 |
| `get_reports(code, max_pages=2, provider="auto", fallback=True)` | 研报列表 |
| `download_report(record, target_dir=None, filename=None, provider="auto", fallback=True)` | 下载研报 PDF |
| `get_eps_forecast(code, provider="auto", fallback=True)` | EPS 预测 |
| `get_financial_statement(code, report_type="income", limit=8, provider="auto", fallback=True)` | 财务三表 |
| `get_valuation(code, provider="auto", fallback=True)` | 估值指标 |

### 问财与组合分析

| 方法 | 用途 |
| --- | --- |
| `query_wencai(query, provider="auto")` | 问财自然语言查询 |
| `query_wencai_base(query, provider="auto")` | 问财基础查询 |
| `screen_stocks(query, provider="auto")` | 自然语言选股 |
| `compare_stocks(codes, interval="day", count=30, provider="auto", fallback=True)` | 多股行情、走势和相关性对比 |
| `normalize_trend(codes, interval="day", count=30, provider="auto", fallback=True)` | 多股归一化走势 |
| `correlation_matrix(codes, interval="day", count=30, provider="auto", fallback=True)` | 多股收盘价相关性矩阵 |

## 环境变量

如果使用默认 `StockGateway()`，部分接口会优先或降级调用 `thsdk`。`thsdk` 连接同花顺行情服务时建议配置账号密码：

```bash
export THS_USERNAME="你的同花顺账号"
export THS_PASSWORD="你的同花顺密码"
```

如果需要固定设备标识，也可以配置：

```bash
export THS_MAC="你的 MAC 地址或 thsdk 要求的设备标识"
```

注意：

- 环境变量名大小写敏感，`thsdk` 默认读取 `THS_USERNAME`、`THS_PASSWORD`、`THS_MAC`。
- 如果部署平台使用 `ths_username`、`ths_password` 作为 secret 名称，请在启动进程前映射为大写环境变量。
- 本 SDK 不接入同花顺问财 OpenAPI，不读取 `API_KEY`，也不构造 `X-Claw-*` 请求头。
- 不要把真实账号、密码、Cookie、Token、Webhook 或本地行情缓存提交到代码仓库。
- 如果上层项目需要代理、缓存目录或日志配置，请在上层项目自行管理。

## 使用注意

- 行情、新闻、公告、财务和研报数据具有时效性，请在使用前重新拉取，并记录数据时间和 provider。
- 东方财富、同花顺热点等数据源可能触发风控，SDK 内部对相关 provider 做了串行限流；上层项目不要并发猛打接口。
- `thsdk`、`mootdx` 和网页数据源可能受本机环境、网络、交易时段和源站可用性影响；失败时优先查看 `fallback_chain` 和 `error`。
- 自动降级只发生在语义等价或兼容的数据源之间；不等价数据不会被静默替代。
- 问财相关接口通过 `thsdk` 承载，返回字段可能随查询语句和源站变化，建议保留 `raw` 便于排查。
