# pqquotation


快速获取新浪/腾讯/东方财富的全市场行情，网络正常的情况下只需要 `200+ms`。本软件基于 [easyquotation](https://github.com/shidenggui/easyquotation)改进而来。

## 功能
* 获取新浪的免费实时行情
* 获取腾讯财经的免费实时行情
* 获取东方财富的免费实时行情
* 获取集思路的数据
* 智能轮询机制: sina → tencent → dc 循环轮询访问数据，避免被屏蔽
* 高可用性保障
   - 10秒超时控制: 避免长时间阻塞，快速响应
   - 超时快速切换: 超时错误立即切换数据源，无需等待多次失败
   - 后台健康检查: 失败的数据源每30秒自动探测，恢复后立即启用
   - 性能监控: 实时统计各数据源的成功率和响应时间
   - 线程安全: 支持多线程并发访问
* 支持的股票代码格式多:
   - 数字格式: 000001, 600000, 430047
   - 前缀格式: sz000001, sh600000, bj430047
   - 国标格式: 000001.SZ, 600000.SH, 430047.BJ
* 结果返回的股票代码默认格式是国标格式，例如 000001.SZ。也可以通过如下的函数设置输出数据的股票代码格式
   - `pqquotation.enable_national_format_globally()`   # 国标格式, 000001.SZ, 600000.SH, 430047.BJ
   - `pqquotation.enable_prefix_format_globally()`  #前缀格式， sz000001, sh600000, bj430047
   - `pqquotation.enable_digit_format_globally()`    # 数字格式， 000001, 600000, 430047

## 安装

```python
pip install pqquotation
```

## 用法

### 引入:

```python
import pqquotation
```

### 选择行情

```python
quotation = pqquotation.use('sina') # 新浪 ['sina'], 腾讯 ['tencent', 'qq'], 东方财富 ['dc', 'eastmoney']
```

### 获取所有股票行情

```python
# prefix 指定返回行情的股票代码是否带 sz/sh/bj 市场前缀
quotation.market_snapshot(prefix=True) 
```

**return**

```python
 {'sh000159': {'name': '国际实业', # 股票名
  'buy': 8.87, # 竞买价
  'sell': 8.88, # 竞卖价
  'now': 8.88, # 现价
  'open': 8.99, # 开盘价
  'close': 8.96, # 昨日收盘价
  'high': 9.15, # 今日最高价
  'low': 8.83, # 今日最低价
  'turnover': 22545048, # 交易股数
  'volume': 202704887.74， # 交易金额
  'ask1': 8.88, # 卖一价
  'ask1_volume': 111900, # 卖一量
  'ask2': 8.89,
  'ask2_volume': 54700,
  'bid1': 8.87, # 买一价
  'bid1_volume': 21800, # 买一量
  ...
  'bid2': 8.86, 
  'bid2_volume': 78400,
  'date': '2016-02-19',
  'time': '14:30:00',
  ...},
  ......
}
```

#### 单只股票

```python
quotation.real('162411') # 支持直接指定前缀，如 'sh000001'
```

#### 多只股票

```python
quotation.real(['000001', '162411']) 
```

#### 多个服务器轮询调用（RoundRobin 高可用模式）

核心特性:
1. 智能轮询: sina → tencent → dc 循环轮询，负载均衡
2. 10秒超时: 每个HTTP请求最多等待10秒，避免长时间阻塞
3. 快速切换: 超时错误立即切换，无需等待多次失败
4. 健康检查: 后台线程每30秒自动探测失败的数据源
5. 自动恢复: 数据源恢复后立即重新启用
6. 性能统计: 记录每个数据源的成功/失败次数和响应时间
7. 格式统一: 自动将不同数据源的格式标准化
8. 线程安全: 支持多线程并发访问
9. 多种别名: 支持 'rr'、'roundrobin'、'round-robin'

**基本使用:**

```python
import pqquotation

# 方式1: 默认配置（推荐 - 启用健康检查）
rr = pqquotation.use('roundrobin')
data = rr.real(['000001', '000002', '600000'])

# 方式2: 禁用健康检查（节省资源）
rr = pqquotation.use('roundrobin', enable_health_check=False)
data = rr.real('000001')
```

**高级功能:**

```python
# 查看数据源健康状态
health = rr.get_health_summary()
print(health)  # 输出: 数据源状态: 3/3 可用

# 查看详细统计信息
stats = rr.get_source_stats()
print(f"可用数据源: {stats['available_sources']}")
print(f"失败数据源: {stats['failed_sources']}")

# 查看各数据源性能
for source_name, source_stats in stats['sources'].items():
    print(f"{source_name}: 成功{source_stats['success']}次, "
          f"失败{source_stats['failure']}次, "
          f"平均响应{source_stats['avg_response_time']:.3f}秒")

# 手动重置失败状态（通常不需要，健康检查会自动处理）
rr.reset_failed_sources()

# 自定义健康检查参数（高级用法）
rr._health_check_interval = 15  # 改为15秒检查一次
rr._probe_timeout = 3  # 探测超时改为3秒

# 手动控制健康检查线程
rr.stop_health_check()      # 停止健康检查
rr.restart_health_check()   # 重启健康检查
```

**改进效果对比:**

| 场景 | 改进前 | 改进后 |
|------|--------|--------|
| HTTP请求超时 | 无限等待或60-120秒 | **10秒** ⚡ |
| 超时后切换 | 需要3次失败（可能90秒+） | **立即切换** 🚀 |
| 失败源恢复 | 被动等待5分钟 | **30秒自动探测** 🏥 |
| 用户体验 | 可能等待数分钟 | 最多10秒 😍 |

**查看完整文档:**

```python
import pqquotation
help(pqquotation.use)  # 查看详细文档
```



#### 同时获取指数和行情

```python
# 获取相同代码的指数和股票时 prefix 必须为 True
quotation.real(['sh000001', 'sz000001'], prefix=True)
```

### 更新内置全市场股票代码

```python
easyquotation.update_stock_codes()
```


### 港股日k线图
*[腾讯日k线图](http://web.ifzq.gtimg.cn/appstock/app/hkfqkline/get?_var=kline_dayqfq&param=hk00700,day,,,350,qfq&r=0.7773272375526847)*

```python

import easyquotation
quotation  = easyquotation.use("daykline")
data = quotation.real(['00001','00700'])
print(data)
```

```python
{
    '00001': [
                ['2017-10-09', '352.00', '349.00', '353.00', '348.60', '13455864.00'], # [日期, 今开, 今收, 最高, 最低, 成交量 ]
                ['2017-10-10', '350.80', '351.20', '352.60', '349.80', '10088970.00'],
               ]
    '00700':[
        
    ]           
     }
}
```

### 腾讯港股实时行情 
*[腾讯控股实时行情](http://sqt.gtimg.cn/utf8/q=r_hk00700)*
```python

import easyquotation
quotation = easyquotation.use("hkquote")
data = quotation.real(['00001','00700'])
print(data)
```

```python
{
    '00001': 
        {
            'stock_code': '00001', # 股票代码
            'lotSize': '"100', # 每手数量
            'name': '长和', # 股票名称
            'price': '97.20', # 股票当前价格
            'lastPrice': '97.75', # 股票昨天收盘价格
            'openPrice': '97.75', # 股票今天开盘价格
            'amount': '1641463.0', # 股票成交量 
            'time': '2017/11/29 15:38:58', # 当前时间
            'high': '98.05', # 当天最高价格
            'low': '97.15' # 当天最低价格
        }, 
    '00700': 
        {
            'stock_code': '00700', 
            'lotSize': '"100',
            'name': '腾讯控股', 
            'price': '413.20', 
            'lastPrice': '419.20', 
            'openPrice': '422.20', 
            'amount': '21351010.0', 
            'time': '2017/11/29 15:39:01', 
            'high': '422.80',
            'low': '412.40'
        }
}
```

### 选择 [jsl](https://www.jisilu.cn)（集思录） 行情

```python
quotation = easyquotation.use('jsl') 
```

#### 设置 cookie (可选)

不设置的话获取相关数据有限制

```python
quotation.set_cookie('从浏览器获取的集思录 Cookie')
```


#### 指数ETF查询接口

**TIP :** 尚未包含黄金ETF和货币ETF

*[集思录ETF源网页](https://www.jisilu.cn/data/etf/#tlink_2)*

```python
quotation.etfindex(index_id="", min_volume=0, max_discount=None, min_discount=None)
```

**return**

```python
{
    "510050": {
        "fund_id": "510050",                # 代码
        "fund_nm": "50ETF",                 # 名称
        "price": "2.066",                   # 现价
        "increase_rt": "0.34%",             # 涨幅
        "volume": "71290.96",               # 成交额(万元)
        "index_nm": "上证50",                # 指数
        "pe": "9.038",                      # 指数PE
        "pb": "1.151",                      # 指数PB
        "index_increase_rt": "0.45%",       # 指数涨幅
        "estimate_value": "2.0733",         # 估值
        "fund_nav": "2.0730",               # 净值
        "nav_dt": "2016-03-11",             # 净值日期
        "discount_rt": "-0.34%",            # 溢价率
        "creation_unit": "90",              # 最小申赎单位(万份)
        "amount": "1315800",                # 份额
        "unit_total": "271.84",             # 规模(亿元)
        "index_id": "000016",               # 指数代码
        "last_time": "15:00:00",            # 价格最后时间(未确定)
        "last_est_time": "23:50:02",        # 估值最后时间(未确定)
    }
}
```

## 高可用性增强

为了解决生产环境中数据源超时、失败等问题，进行了全面的高可用性改进：

### HTTP 超时控制
**问题**: 原有代码中 HTTP 请求没有超时限制，可能导致长时间阻塞

**解决方案**:
- 所有 HTTP 请求添加 10 秒超时限制
- 超时时间可配置，灵活适应不同场景
- 避免因网络问题导致程序假死

**效果**: 请求最多等待 10 秒，避免无限等待

### 超时快速切换
**问题**: 原有机制需要连续失败 3 次才标记数据源不可用，可能等待 90 秒以上

**解决方案**:
- 识别超时错误类型（`requests.exceptions.Timeout`）
- 超时错误立即标记数据源不可用
- 普通错误仍使用 3 次失败阈值
- 立即尝试下一个可用数据源

**效果**: 超时后立即切换（从 90 秒降低到 10 秒）

### 后台健康检查
**问题**: 失败的数据源需要被动等待 5 分钟才重试，即使已经恢复也无法及时使用

**解决方案**:
- 启动独立的守护线程进行后台健康检查
- 每 30 秒自动探测失败的数据源
- 使用轻量级探测（单只股票，5 秒超时）
- 探测成功后立即恢复数据源
- 线程安全，支持多线程并发访问

**效果**: 数据源恢复时间从 5 分钟缩短到 30 秒

**配置选项**:
```python
# 启用健康检查（默认）
rr = pqquotation.use('roundrobin', enable_health_check=True)

# 禁用健康检查（节省资源）
rr = pqquotation.use('roundrobin', enable_health_check=False)

# 自定义健康检查参数
rr._health_check_interval = 15  # 检查间隔（秒）
rr._probe_timeout = 3           # 探测超时（秒）
```

### API 改进: 参数化配置
**改进**: `use()` 函数支持可选参数传递

**新功能**:
- 支持 `**kwargs` 传递参数给 RoundRobin
- 详细的文档字符串（1800+ 字符）
- 6 个使用示例
- 完全向后兼容

**使用**:
```python
# 查看完整文档
help(pqquotation.use)
```


## TODO
* [x] 检查数据源 sina，qq，dc，访问数据是否完毕，数据是否一致。sina和dc的数据比较一致，qq的volume字段有些问题
* [x] 增加自动切换服务器的功能，避免长时间连接一个服务器导致屏蔽连接
* [x] 支持多种股票代码格式，支持结果中股票代码格式设置
* [x] HTTP 超时控制，避免长时间阻塞
* [x] 超时快速切换，立即故障转移
* [x] 后台健康检查，自动恢复失败的数据源
* [x] API 参数化配置，灵活控制行为

