本页按任务列出常用行情函数。右侧目录直接显示函数名；点击函数标题下方的链接，可进入对应独立 API 页面查看完整参数、返回说明、运行环境和官方来源。

## 历史与 K 线数据

### ContextInfo.get_market_data_ex

推荐用于获取单个或多个证券的 K 线、Tick 和历史行情数据，可指定字段、周期、起止时间、数量及复权方式。

#### 调用语法

```python
ContextInfo.get_market_data_ex(
    fields=[], stock_code=[], period='follow',
    start_time='', end_time='', count=-1,
    dividend_type='follow', fill_data=True, subscribe=True,
)
```

#### 关键参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `fields` | `list` | 数据字段，如 `open`、`high`、`low`、`close`、`volume`、`amount` |
| `stock_code` | `list[str]` | 合约代码列表，如 `['000001.SZ', '600000.SH']` |
| `period` | `str` | `tick`、`1m`、`5m`、`15m`、`1h`、`1d`、`1w`、`l2quote` 等 |
| `start_time` | `str` | 开始时间，格式为 `YYYYMMDD` 或 `YYYYMMDDhhmmss` |
| `end_time` | `str` | 结束时间；空字符串表示截止到最新数据 |
| `count` | `int` | 返回的数据条数，`-1` 表示按时间范围获取 |
| `dividend_type` | `str` | `none`、`front`、`back`、`front_ratio`、`back_ratio` |
| `fill_data` | `bool` | 是否填充缺失数据 |
| `subscribe` | `bool` | 是否同时订阅行情；只读本地数据时设为 `False` |

#### 返回值

返回以证券代码为键的 `dict`。每个证券通常对应一个 `pandas.DataFrame`，索引为时间，列为所请求字段。

#### 使用注意

- 不建议在 `init` 中调用；在 `init` 中只能读取本地已有数据。
- 历史数据为空时，先检查对应证券和基础周期是否已下载。
- Level-2 周期需要对应行情权限。
- `subscribe=False` 不会发起订阅，只读取本地已有数据。

```python
def handlebar(ContextInfo):
    data = ContextInfo.get_market_data_ex(
        fields=['open', 'high', 'low', 'close', 'volume'],
        stock_code=['000001.SZ'],
        period='1d',
        count=20,
        dividend_type='front',
        fill_data=True,
        subscribe=False,
    )
    print(data)
```

[查看 `ContextInfo.get_market_data_ex` 完整参数与返回说明](docs/qmt/builtin-python/api-reference/contextinfo-get-market-data-ex/index.html)

### download_history_data

将指定证券、周期和时间范围的历史行情下载到本地。历史数据为空时，应先确认客户端已完成数据下载。

#### 调用语法与参数

```python
download_history_data(stockcode, period, startTime, endTime)
```

| 参数 | 类型 | 说明 |
|---|---|---|
| `stockcode` | `str` | 证券代码，如 `600000.SH` |
| `period` | `str` | 基础周期支持 `tick`、`1m`、`5m`、`1d` |
| `startTime` | `str` | 起始时间，可为空 |
| `endTime` | `str` | 结束时间，可为空 |

返回值为 `None`。获取 `15m` 等合成周期历史数据时，应下载其基础周期，例如 `15m` 由 `5m` 合成。

```python
download_history_data('000001.SZ', '1d', '20240101', '20241231')
```

[查看 `download_history_data` 完整说明](docs/qmt/builtin-python/api-reference/download-history-data/index.html)

### ContextInfo.get_history_data（不推荐）

旧版历史行情接口。官方目录已标记为“不推荐”，新代码优先使用 `ContextInfo.get_market_data_ex`。

#### 调用语法与返回值

```python
ContextInfo.get_history_data(len, period, field, dividend_type=0, skip_paused=True)
```

调用前需要先通过 `ContextInfo.set_universe()` 设置股票池。返回 `dict`，键为证券代码，值为按时间从早到晚排列的行情列表。

```python
history = ContextInfo.get_history_data(20, '1d', 'close', 0, True)
```

[查看 `ContextInfo.get_history_data` 兼容说明](docs/qmt/builtin-python/api-reference/contextinfo-get-history-data/index.html)

## 实时与全推行情

### ContextInfo.get_full_tick

主动获取指定证券的最新全推快照，适合读取最新价、成交量和买卖盘等实时字段。

#### 调用语法与返回值

```python
ContextInfo.get_full_tick(stock_code=[])
```

`stock_code` 为证券代码列表。返回外层以证券代码为键的 `dict`，每个值为该证券最新 Tick 字段字典。

> 该函数不能用于回测，只能获取最新分笔，不能获取历史分笔。

```python
ticks = ContextInfo.get_full_tick(['000001.SZ', '600000.SH'])
print(ticks.get('000001.SZ'))
```

[查看 `ContextInfo.get_full_tick` 完整字段说明](docs/qmt/builtin-python/api-reference/contextinfo-get-full-tick/index.html)

### ContextInfo.subscribe_whole_quote

订阅证券列表的全推行情。适合需要行情变化后持续处理数据的场景；不再使用时应取消订阅。

#### 调用语法与返回值

```python
ContextInfo.subscribe_whole_quote(code_list, callback=None)
```

`code_list` 可以是市场列表（如 `['SH', 'SZ']`）或证券代码列表。`callback` 接收增量推送数据。函数返回整数订阅号，后续用于取消订阅。

```python
def on_quote(data):
    print(data)

subscription = ContextInfo.subscribe_whole_quote(
    ['000001.SZ', '600000.SH'],
    on_quote,
)
```

[查看 `ContextInfo.subscribe_whole_quote` 完整说明](docs/qmt/builtin-python/api-reference/contextinfo-subscribe-whole-quote/index.html)

### ContextInfo.unsubscribe_quote

根据订阅返回的标识取消行情订阅，避免策略停止使用数据后仍保留无效订阅。

#### 调用语法

```python
ContextInfo.unsubscribe_quote(subId)
```

`subId` 是订阅函数返回的整数订阅号。应先判断订阅号有效，再执行取消操作。

```python
ContextInfo.unsubscribe_quote(subscription)
```

[查看 `ContextInfo.unsubscribe_quote` 完整说明](docs/qmt/builtin-python/api-reference/contextinfo-unsubscribe-quote/index.html)

## 证券与板块数据

### ContextInfo.get_stock_list_in_sector

获取指定板块的成分证券列表，可用于建立股票池或批量请求行情。

#### 调用语法与返回值

```python
ContextInfo.get_stock_list_in_sector(sectorname, realtime)
```

`sectorname` 是客户端板块名称，支持官方板块与自定义板块。返回证券代码列表，例如 `['000001.SZ', '600000.SH']`。当前官方原型列出 `realtime` 参数，但官方示例省略了该参数，可能存在客户端版本差异；使用时应以实际版本为准。官方说明要求在 `after_init` 或 `handlebar` 中调用。

```python
stocks = ContextInfo.get_stock_list_in_sector('沪深300', True)
print(stocks[:10])
```

[查看 `ContextInfo.get_stock_list_in_sector` 完整说明](docs/qmt/builtin-python/api-reference/contextinfo-get-stock-list-in-sector/index.html)

## 选择函数

| 需求 | 推荐函数 |
|---|---|
| 获取历史 K 线或多证券行情 | `ContextInfo.get_market_data_ex` |
| 获取最新全推快照 | `ContextInfo.get_full_tick` |
| 持续接收全推行情 | `ContextInfo.subscribe_whole_quote` |
| 取消行情订阅 | `ContextInfo.unsubscribe_quote` |
| 下载本地历史数据 | `download_history_data` |
| 获取板块成分 | `ContextInfo.get_stock_list_in_sector` |

版本、权限和不同运行模式的限制，请以对应函数独立页面中的官方说明为准。