Metadata-Version: 2.4
Name: qdata-quote
Version: 0.4.0
Summary: 实时行情采集服务，支持新浪和腾讯数据源
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# qdata-quote

实时 A 股行情采集服务，支持新浪和腾讯两个数据源。性能超越 easyquotation 约 8-10%。

## 安装

```bash
pip install qdata-quote
```

## 快速开始

```python
from qdata_quote import QuoteService

# 默认加载全市场股票列表（初始化时自动从网络刷新）
service = QuoteService()

# 同步获取指定股票行情
df = service.get_real_sync(["000001", "600000"])
print(df)

# 同步获取全市场行情快照
df_all = service.get_all_sync()

# 异步获取（高性能路径）
import asyncio
df = asyncio.run(service.get_real(["000001", "600000"]))
df_all = asyncio.run(service.get_all())
```

## 自定义股票列表

```python
from qdata_quote import QuoteService

# 传入自定义股票列表（不会自动刷新）
service = QuoteService(codes=["000001", "600000", "300750"])

# 随时替换股票列表（切换为自定义模式，不再接受 refresh）
service.set_stock_codes(["000001", "600000"])

# 刷新全市场股票列表（仅在使用默认列表时生效）
service.refresh_stock_codes()
```

## 获取股票代码

```python
from qdata_quote import get_stock_codes

# 读取缓存（如果没有缓存则自动获取）
codes = get_stock_codes()

# 强制从网络刷新
codes = get_stock_codes(refresh=True)
```

缓存文件位置：`~/.qdata_quote/stock_codes.json`

## 数据源

支持两个数据源，通过 `source` 参数指定：

```python
# 新浪源（默认）
df = service.get_real_sync(["000001"], source="sina")

# 腾讯源（字段更丰富）
df = service.get_real_sync(["000001"], source="tencent")
```

| 数据源 | 每批数量 | 特点 |
|--------|---------|------|
| sina | 800 只/批 | 速度快，基础字段齐全 |
| tencent | 60 只/批 | 额外提供涨跌、市盈率、市值、量比等 |

## 返回格式

返回统一的 `pandas.DataFrame`，index 为带后缀的股票代码（如 `600000.SH`、`000001.SZ`、`830789.BJ`）。

### 股票代码格式

- **输出统一后缀格式**：`<6位代码>.<交易所>`，交易所后缀大写 —— `.SH`（上交所）、`.SZ`（深交所）、`.BJ`（北交所）。
- **输入兼容两种写法**：纯代码（`000001`）或带后缀（`000001.SZ`）均可，大小写不敏感。
- `get_stock_codes()` 返回的默认列表同样为后缀格式。

### 字段列表

| 字段 | 类型 | 新浪 | 腾讯 | 说明 |
|------|------|:----:|:----:|------|
| code | str | ✅ | ✅ | 股票代码（index） |
| name | str | ✅ | ✅ | 股票名称 |
| open | float | ✅ | ✅ | 开盘价 |
| close | float | ✅ | ✅ | 昨收价 |
| now | float | ✅ | ✅ | 当前价 |
| high | float | ✅ | ✅ | 最高价 |
| low | float | ✅ | ✅ | 最低价 |
| buy | float | ✅ | - | 买一价 |
| sell | float | ✅ | - | 卖一价 |
| volume | float | ✅ | ✅ | 成交量（股） |
| turnover | float | ✅ | ✅ | 成交额（元） |
| bid1 ~ bid5 | float | ✅ | ✅ | 买一到买五价 |
| bid1_volume ~ bid5_volume | float | ✅ | ✅ | 买一到买五量（股） |
| ask1 ~ ask5 | float | ✅ | ✅ | 卖一到卖五价 |
| ask1_volume ~ ask5_volume | float | ✅ | ✅ | 卖一到卖五量（股） |
| datetime | str | ✅ | ✅ | 行情时间 |
| change | float | - | ✅ | 涨跌额 |
| change_pct | float | - | ✅ | 涨跌幅(%) |
| amplitude | float | - | ✅ | 振幅 |
| pe_dynamic | float | - | ✅ | 动态市盈率 |
| pe_static | float | - | ✅ | 静态市盈率 |
| pb | float | - | ✅ | 市净率 |
| total_market_cap | float | - | ✅ | 总市值 |
| circulating_market_cap | float | - | ✅ | 流通市值 |
| volume_ratio | float | - | ✅ | 量比 |
| bid_ask_ratio | float | - | ✅ | 委比 |
| avg_price | float | - | ✅ | 均价 |
| limit_up | float | - | ✅ | 涨停价 |
| limit_down | float | - | ✅ | 跌停价 |

✅ 表示有数据，- 表示 NaN。腾讯源提供更丰富的衍生指标。

## 会话管理

建议使用上下文管理器复用连接，在频繁轮询场景下性能更佳：

```python
# 同步
with QuoteService() as service:
    df = service.get_all_sync()

# 异步
async with QuoteService() as service:
    df = await service.get_all()
```

## 性能对比

与 easyquotation 对比（5500+ 只股票）：

| 数据源 | easyquotation | qdata_quote sync | qdata_quote async |
|--------|--------------|-------------------|-------------------|
| 新浪 | ~710ms | **~640ms** | **~640ms** |
| 腾讯 | ~1830ms | **~1720ms** | **~1680ms** |

- 同步引擎：`requests` + `ThreadPoolExecutor` 并发请求
- 异步引擎：`aiohttp` + `asyncio.gather` 并发请求
- 解析优化：文本合并后一次性正则匹配，元组直接构建 DataFrame

## 运行基准测试

```bash
python -m qdata_quote.bench
```

## 依赖

- Python >= 3.10
- requests >= 2.28
- aiohttp >= 3.9
- pandas >= 2.0
