Metadata-Version: 2.4
Name: insight-proxy-client
Version: 0.0.4
Summary: insight_proxy 的 Python 客户端，兼容 Insight 6.1.2 数据接口
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: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas<3,>=1.5
Requires-Dist: numpy<3,>=1.23

# insight-proxy-client

`insight-proxy-client` 是 **insight_proxy Socket 转接服务的 Python 客户端**，
以 **Insight 6.1.2** 为数据接口兼容基准，支持 Python **3.9、3.10、3.11、3.12**。
发行包名是 `insight-proxy-client`，导入路径是 `insight_proxy.com.insight`。
这是独立适配程序，并非华泰官方 SDK。

## 目录

- [安装与升级](#安装与升级)
- [快速开始](#快速开始)
- [连接与关闭](#连接与关闭)
- [接口示例的公共参数](#接口示例的公共参数)
- [查询接口](#查询接口)：全部 80 个
- [订阅接口](#订阅接口)：11 个数据订阅函数与本地 sync
- [回放接口](#回放接口)：全部 2 个
- [回调接口](#回调接口)：全部 13 个
- [返回值与错误处理](#返回值与错误处理)
- [控制台日志](#控制台日志)
- [兼容范围](#兼容范围)

## 安装与升级

```shell
python -m pip install --upgrade insight-proxy-client==0.0.4
```

安装时自动安装 pandas 和 NumPy。客户端无需官方 SDK 或原生 DLL，
需要连接单独部署、已登录 Insight 且具备相应数据权限的 insight_proxy 服务端。
本包不包含服务端 EXE、证书或账号密码。
旧合并包 `insight_proxy` 与本包提供相同导入路径，请使用独立客户端环境，避免混装。

## 快速开始

下面的完整程序查询股票日线，再订阅股票、期货和 ETF Tick，按回车结束。

```python
from datetime import datetime
from insight_proxy.com.insight import Client
from insight_proxy.com.insight.market_service import market_service


class Market(market_service):
    def on_subscribe_tick(self, result):
        print("收到 Tick：", result)

    def on_query_response(self, result):
        print("收到异步查询结果：", result)

    def on_query_margin_response(self, result):
        print("收到异步融券查询结果：", result)


# 默认 host="127.0.0.1", port=8765, token="123456"
with Client(Market()) as client:
    frame = client.query.get_kline(
        "601688.SH",
        [datetime(2026, 10, 19), datetime(2026, 10, 26, 23, 59, 59)],
        frequency="daily", fq="none",
    )
    print(frame)
    client.subscribe.subscribe_tick_by_id(
        ["601688.SH", "IF2611.CF", "510300.SH"], mode="coverage"
    )
    input("按回车结束订阅并关闭连接。")
```

文中的证券、日期、合约为固定示例，运行时应选择有数据且有权限的范围；
期货实时订阅应使用有效合约。空结果不一定是连接错误，也可能是时间范围、标的或权限问题。

## 连接与关闭

### 不传参数

```python
from insight_proxy.com.insight import Client

client = Client()
client.connect()
try:
    print(client.query.get_stock_info(htsc_code="601688.SH"))
finally:
    client.close()
```

### 只传 market_service 实例

```python
from insight_proxy.com.insight import Client
from insight_proxy.com.insight.market_service import market_service

with Client(market_service()) as client:
    print(client.query.get_stock_info(htsc_code="601688.SH"))

# 使用上面定义的 Market()，可接收自定义回调处理。
with Client(Market()) as client:
    print(client.query.get_stock_info(htsc_code="601688.SH"))
```

构造 Client 不连接网络，调用 `.connect()` 才建立连接；`with` 自动连接和关闭。
默认 `host="127.0.0.1", port=8765, token="123456"`，服务端 token 应与客户端一致。
可以显式覆盖连接参数：

```python
with Client(Market(), host="127.0.0.1", port=8765, token="123456", timeout=30) as client:
    print(client.query.get_stock_info(htsc_code="601688.SH"))
```

### 模块级连接

```python
from insight_proxy.com.insight import connect, close, query, subscribe, playback

connect()  # 也支持 connect(Market())；默认参数与 Client 相同
try:
    print(query.get_stock_info(htsc_code="601688.SH"))
finally:
    close()
```

模块级 `connect()` 返回已连接的 Client；一个进程只保留一个模块级默认会话。
显式 Client 使用 `client.query`、`client.subscribe` 和 `client.playback`。
服务端 0.5.0 起支持多个 Client 共享一次华泰登录，查询和订阅回调分别路由；旧版服务端仍为独占模式。
关闭后重新连接应创建新的 Client。同一进程需要多个连接时，请使用多个显式 Client 对象。

## 接口示例的公共参数

下面的接口示例是**按需选用的调用片段**，不要一次执行全部接口。
先运行公共参数和连接代码，执行需要的片段，再在 `finally` 中调用 `close()`。
这里的 `Market` 是快速开始中的类；订阅其他数据或回放时，使用回调章节的 `FullMarket`。

```python
from datetime import datetime
from insight_proxy.com.insight import connect, close, query, subscribe, playback

STOCK = "601688.SH"
FUTURE = "IF2611.CF"
ETF = "510300.SH"
HK_STOCK = "00700.HK"
INDEX = "000300.SH"
BOND = "111002.SH"
REPO = "204001.SH"
INDUSTRY_CODE = "110000"  # 从 get_industries 的结果选取有效行业代码
START = datetime(2026, 10, 19)
END = datetime(2026, 10, 26, 23, 59, 59)
DAY = datetime(2026, 10, 26)
DAY_END = datetime(2026, 10, 26, 23, 59, 59)
FIN_START = datetime(2026, 1, 1)
FIN_END = datetime(2026, 6, 30)

connect(Market())
```

大多数历史查询日期参数是两个 `datetime` 组成的列表；单个日期、月份字符串等特例以各接口为准。
不要用字符串日期代替 `datetime`。研报编号、经济指标编号和港股行业代码需从对应目录结果选择，
下面的相关示例会提示输入实际编号。


## 查询接口

覆盖全部 80 个公开查询函数。大多数函数同步返回 DataFrame；特殊返回和异步接口在对应示例注明。


### query_fin_info：通用金融数据查询

签名：`query.query_fin_info(query_type, params)`

示例为日 K 线的底层查询类型。其他 query_type 与字段组合须按官方数据字典填写，返回结构由原 SDK 决定。


```python
result = query.query_fin_info(
    query_type=1002070003,
    params={'HTSC_SECURITY_IDS': STOCK, 'START_TIME': START.strftime("%Y%m%d%H%M%S"), 'END_TIME': END.strftime("%Y%m%d%H%M%S"), 'EMD_PERIOD_TYPE': 'Period1D', 'EXRIGHTS_TYPE': 'NoExrights'},
)
```


### get_kline：K线行情

签名：`query.get_kline(htsc_code=None, time=None, frequency='daily', fq='pre')`


```python
result = query.get_kline(htsc_code=STOCK, time=[START, END], frequency='daily', fq='none')
```

股票、期货分钟与日频示例：

```python
stock_minute = query.get_kline(STOCK, [DAY, DAY_END], frequency="1min", fq="none")
future_minute = query.get_kline(FUTURE, [DAY, DAY_END], frequency="1min", fq="none")
stock_daily = query.get_kline(STOCK, [START, END], frequency="daily", fq="none")
future_daily = query.get_kline(FUTURE, [START, END], frequency="daily", fq="none")
```


### get_derived：衍生行情

签名：`query.get_derived(htsc_code=None, trading_day=None, type=None)`


```python
result = query.get_derived(htsc_code=STOCK, trading_day=[START, END], type='amv')
```


### get_trade_distribution：成交分布

签名：`query.get_trade_distribution(htsc_code=None, trading_day=None)`


```python
result = query.get_trade_distribution(htsc_code=STOCK, trading_day=[START, END])
```


### get_chip_distribution：筹码分布

签名：`query.get_chip_distribution(htsc_code=None, trading_day=None)`


```python
result = query.get_chip_distribution(htsc_code=STOCK, trading_day=[START, END])
```


### get_money_flow：资金流向

签名：`query.get_money_flow(htsc_code=None, trading_day=None)`


```python
result = query.get_money_flow(htsc_code=STOCK, trading_day=[START, END])
```


### get_change_summary：市场涨跌概况

签名：`query.get_change_summary(market=None, trading_day=None)`


```python
result = query.get_change_summary(trading_day=[START, END], market='sh_a_share')
```


### get_billboard：市场排行榜

签名：`query.get_billboard(type=None, market=None)`


```python
result = query.get_billboard(type='inc_list', market='sh_a_share')
```


### get_stock_info：股票基础资料

签名：`query.get_stock_info(htsc_code=None, listing_date=None, listing_state=None)`


```python
result = query.get_stock_info(htsc_code=STOCK)
```


### get_all_stocks_info：市场股票资料

签名：`query.get_all_stocks_info(listing_date=None, exchange=None, listing_state=None)`

示例按上市日期过滤；如需市场全部股票，可省略 listing_date。


```python
result = query.get_all_stocks_info(exchange='XSHG', listing_date=[START, END])
```


### get_trading_days：交易日历

签名：`query.get_trading_days(exchange=None, trading_day=None, count=None)`

指定单个交易所时返回 `(交易所, pandas.Series)`；不是普通 DataFrame。未指定交易所时返回结构沿用 SDK。


```python
result = query.get_trading_days(trading_day=[START, END], exchange='XSHG')
```


### get_industries：行业分类目录

签名：`query.get_industries(classified=None)`


```python
result = query.get_industries(classified='sw_l1')
```


### get_industry：股票所属行业

签名：`query.get_industry(htsc_code=None, classified='sw')`


```python
result = query.get_industry(htsc_code=STOCK, classified='sw')
```


### get_industry_stocks：行业成分股

签名：`query.get_industry_stocks(industry_code=None, classified='sw')`


```python
result = query.get_industry_stocks(industry_code=INDUSTRY_CODE, classified='sw')
```


### get_new_share：新股资料

签名：`query.get_new_share(htsc_code=None, book_start_date_online=None, listing_date=None)`


```python
result = query.get_new_share(htsc_code=STOCK)
```


### get_daily_basic：每日基础指标

签名：`query.get_daily_basic(htsc_code=None, trading_day=None)`


```python
result = query.get_daily_basic(htsc_code=STOCK, trading_day=[START, END])
```


### get_stock_valuation：股票估值

签名：`query.get_stock_valuation(htsc_code=None, trading_day=None)`


```python
result = query.get_stock_valuation(htsc_code=STOCK, trading_day=[START, END])
```


### get_bond_info：债券基础资料

签名：`query.get_bond_info(htsc_code=None, secu_category_code=None, listing_date=None, issue_start_date=None, end_date=None)`


```python
result = query.get_bond_info(htsc_code=BOND)
```


### get_all_bonds：市场债券列表

签名：`query.get_all_bonds(exchange=None, secu_category_code=None, listing_date=None, issue_start_date=None, end_date=None)`


```python
result = query.get_all_bonds(exchange='XSHG', secu_category_code='1350')
```


### get_repo_price：回购行情

签名：`query.get_repo_price(htsc_code=None, exchange=None, trading_day=None)`


```python
result = query.get_repo_price(htsc_code=REPO, trading_day=[START, END], exchange='XSHG')
```


### get_new_con_bond：新发行可转债资料

签名：`query.get_new_con_bond(htsc_code=None, exchange=None, book_start_date_online=None, listing_date=None, issue_date=None, convert_code=None)`


```python
result = query.get_new_con_bond(htsc_code=BOND, exchange='XSHG')
```


### get_bond_price：债券行情

签名：`query.get_bond_price(htsc_code=None, exchange=None, trading_day=None)`


```python
result = query.get_bond_price(htsc_code=BOND, trading_day=[START, END], exchange='XSHG')
```


### get_con_bond_redemption：可转债赎回资料

签名：`query.get_con_bond_redemption(htsc_code=None, exchange=None, register_date=None)`


```python
result = query.get_con_bond_redemption(htsc_code=BOND, register_date=[START, END], exchange='XSHG')
```


### get_con_bond_2_shares_change：可转债转股变动

签名：`query.get_con_bond_2_shares_change(htsc_code=None, exchange=None, pub_date=None, convert_code=None)`


```python
result = query.get_con_bond_2_shares_change(htsc_code=BOND, pub_date=[START, END], exchange='XSHG')
```


### get_con_bond_2_shares：可转债转股资料

签名：`query.get_con_bond_2_shares(htsc_code=None, pub_date=None, exer_begin_date=None, exer_end_date=None, convert_code=None, exchange=None)`


```python
result = query.get_con_bond_2_shares(htsc_code=BOND, pub_date=[START, END], exchange='XSHG')
```


### get_income_statement：利润表

签名：`query.get_income_statement(htsc_code=None, end_date=None, period=None)`


```python
result = query.get_income_statement(htsc_code=STOCK, end_date=[FIN_START, FIN_END], period='Q2')
```


### get_balance_sheet：资产负债表

签名：`query.get_balance_sheet(htsc_code=None, end_date=None, period=None)`


```python
result = query.get_balance_sheet(htsc_code=STOCK, end_date=[FIN_START, FIN_END], period='Q2')
```


### get_cashflow_statement：现金流量表

签名：`query.get_cashflow_statement(htsc_code=None, end_date=None, period=None)`


```python
result = query.get_cashflow_statement(htsc_code=STOCK, end_date=[FIN_START, FIN_END], period='Q2')
```


### get_fin_indicator：财务指标

签名：`query.get_fin_indicator(htsc_code=None, end_date=None, period=None)`


```python
result = query.get_fin_indicator(htsc_code=STOCK, end_date=[FIN_START, FIN_END], period='Q2')
```


### get_newest_stock_value：最新股票市值相关数据

签名：`query.get_newest_stock_value(htsc_code=None, exchange=None)`


```python
result = query.get_newest_stock_value(htsc_code=STOCK, exchange='XSHG')
```


### get_company_info：公司基本资料

签名：`query.get_company_info(htsc_code=None, name=None)`


```python
result = query.get_company_info(htsc_code=STOCK)
```


### get_shareholder_num：股东户数

签名：`query.get_shareholder_num(htsc_code=None, name=None, end_date=None)`


```python
result = query.get_shareholder_num(htsc_code=STOCK, end_date=[START, END])
```


### get_additional_share：增发资料

签名：`query.get_additional_share(htsc_code=None, listing_date=None)`


```python
result = query.get_additional_share(htsc_code=STOCK)
```


### get_allotment_share：配股资料

签名：`query.get_allotment_share(htsc_code=None, ini_pub_date=None, is_allot_half_year=None)`


```python
result = query.get_allotment_share(htsc_code=STOCK, ini_pub_date=[START, END])
```


### get_capital_structure：股本结构

签名：`query.get_capital_structure(htsc_code=None, end_date=None)`


```python
result = query.get_capital_structure(htsc_code=STOCK, end_date=[START, END])
```


### get_dividend：分红资料

签名：`query.get_dividend(htsc_code=None, right_reg_date=None, ex_divi_date=None, divi_pay_date=None)`


```python
result = query.get_dividend(htsc_code=STOCK, right_reg_date=[START, END], ex_divi_date=[START, END])
```


### get_north_bound：北向相关数据

签名：`query.get_north_bound(htsc_code=None, trading_day=None)`


```python
result = query.get_north_bound(htsc_code=STOCK, trading_day=[START, END])
```


### get_margin_target：融资融券标的

签名：`query.get_margin_target(htsc_code=None, exchange=None)`


```python
result = query.get_margin_target(htsc_code=STOCK, exchange='XSHG')
```


### get_margin_summary：融资融券汇总

签名：`query.get_margin_summary(htsc_code=None, trading_day=None)`


```python
result = query.get_margin_summary(htsc_code=STOCK, trading_day=[START, END])
```


### get_margin_detail：市场融资融券明细

签名：`query.get_margin_detail(exchange=None, trading_day=None)`


```python
result = query.get_margin_detail(trading_day=[START, END], exchange='XSHG')
```


### get_shareholders_top10：前十大股东

签名：`query.get_shareholders_top10(htsc_code=None, change_date=None)`


```python
result = query.get_shareholders_top10(htsc_code=STOCK, change_date=[START, END])
```


### get_shareholders_floating_top10：前十大流通股东

签名：`query.get_shareholders_floating_top10(htsc_code=None, change_date=None)`


```python
result = query.get_shareholders_floating_top10(htsc_code=STOCK, change_date=[START, END])
```


### get_tick：历史Tick

签名：`query.get_tick(htsc_code=None, security_type=None, trading_day=None)`


```python
result = query.get_tick(htsc_code=STOCK, trading_day=[DAY, DAY_END], security_type='stock')
```

期货历史 Tick 示例：

```python
future_ticks = query.get_tick(FUTURE, security_type="future", trading_day=[DAY, DAY_END])
```


### get_adj_factor：复权因子

签名：`query.get_adj_factor(htsc_code=None, begin_date=None)`


```python
result = query.get_adj_factor(htsc_code=STOCK, begin_date=[START, END])
```


### get_locked_shares：限售股资料

签名：`query.get_locked_shares(htsc_code=None, listing_date=None)`


```python
result = query.get_locked_shares(htsc_code=STOCK)
```


### get_frozen_shares：冻结股份资料

签名：`query.get_frozen_shares(htsc_code=None, freezing_start_date=None)`


```python
result = query.get_frozen_shares(htsc_code=STOCK, freezing_start_date=[START, END])
```


### get_hk_industry：港股所属行业

签名：`query.get_hk_industry(htsc_code=None)`


```python
result = query.get_hk_industry(htsc_code=HK_STOCK)
```


### get_hk_industry_stocks：港股行业成分

签名：`query.get_hk_industry_stocks(industry_code=None)`


```python
print(query.get_hk_industry(htsc_code=HK_STOCK))
HK_INDUSTRY_CODE = input("请输入港股行业结果中的实际行业代码：").strip()
result = query.get_hk_industry_stocks(industry_code=HK_INDUSTRY_CODE)
```


### get_hk_daily_basic：港股每日基础指标

签名：`query.get_hk_daily_basic(htsc_code=None, trading_day=None)`


```python
result = query.get_hk_daily_basic(htsc_code=HK_STOCK, trading_day=[START, END])
```


### get_hk_stock_valuation：港股估值

签名：`query.get_hk_stock_valuation(htsc_code=None, trading_day=None)`


```python
result = query.get_hk_stock_valuation(htsc_code=HK_STOCK, trading_day=[START, END])
```


### get_hk_stock_basic_info：港股基础资料

签名：`query.get_hk_stock_basic_info(htsc_code=None, listing_date=None, listing_state=None)`


```python
result = query.get_hk_stock_basic_info(htsc_code=HK_STOCK)
```


### get_hk_dividend：港股分红

签名：`query.get_hk_dividend(htsc_code=None, ex_divi_date=None)`


```python
result = query.get_hk_dividend(htsc_code=HK_STOCK, ex_divi_date=[START, END])
```


### get_hk_index_mapping：港股指数映射

签名：`query.get_hk_index_mapping(month=None)`

month 使用 YYYY-mm 格式的字符串。


```python
result = query.get_hk_index_mapping(month="2026-10")
```


### get_main_product_info：主营产品资料

签名：`query.get_main_product_info(htsc_code=None, product_code=None, product_level=None)`


```python
result = query.get_main_product_info(htsc_code=STOCK)
```


### get_htsc_margin_target：华泰融券标的

签名：`query.get_htsc_margin_target()`


```python
result = query.get_htsc_margin_target()
```


### get_htsc_margin_by_id：按代码查询华泰融券

签名：`query.get_htsc_margin_by_id(htsc_code=None, data_type=None)`


```python
result = query.get_htsc_margin_by_id(htsc_code=STOCK, data_type='security_lending')
```


### get_htsc_margin_by_type：按类型查询华泰融券

签名：`query.get_htsc_margin_by_type(data_type=None, security_type=None, is_async=False)`

is_async=False 时同步查询；True 时通过 `on_query_margin_response` 接收结果。


```python
result = query.get_htsc_margin_by_type(
    data_type='security_lending',
    security_type='stock',
    is_async=False,
)
```

异步查询示例：

```python
query.get_htsc_margin_by_type(data_type="security_lending", security_type="stock", is_async=True)
```


### get_index_info：指数资料

签名：`query.get_index_info(htsc_code=None, trading_day=None)`


```python
result = query.get_index_info(htsc_code=INDEX, trading_day=[START, END])
```


### get_all_index：市场指数列表

签名：`query.get_all_index(exchange=None, trading_day=None)`


```python
result = query.get_all_index(trading_day=[DAY, DAY_END], exchange='XSHG')
```


### get_index_component：指数成分

签名：`query.get_index_component(htsc_code=None, name=None, stock_code=None, trading_day=None)`

trading_day 使用单个 datetime。


```python
result = query.get_index_component(htsc_code=INDEX, trading_day=DAY)
```


### get_index_component_pro：扩展指数成分

签名：`query.get_index_component_pro(htsc_code=None, name=None, stock_code=None, trading_day=None)`

trading_day 使用单个 datetime。


```python
result = query.get_index_component_pro(htsc_code=INDEX, trading_day=DAY)
```


### get_factors：因子数据

签名：`query.get_factors(htsc_code=None, factor_name=None, trading_day=None)`

因子名称及可用权限以所用数据服务为准。


```python
result = query.get_factors(htsc_code=STOCK, trading_day=[START, END], factor_name='barra_cne6_beta')
```


### get_fund_info：基金行情与净值相关序列

签名：`query.get_fund_info(htsc_code=None, trading_day=None)`

可用于 ETF 行情与净值相关序列查询。先检查返回列名，再选择需要的净值字段；客户端不重命名字段或自动排序。


```python
result = query.get_fund_info(htsc_code=ETF, trading_day=[START, END])
```


### get_fund_target：基金指标与净值相关数据

签名：`query.get_fund_target(htsc_code=None, exchange=None, end_date=None)`

用于基金指标与净值相关数据查询。字段和列名保持原 SDK 返回形式。


```python
result = query.get_fund_target(htsc_code=ETF, end_date=[START, END], exchange='XSHG')
```


### get_etf_component：ETF成分数据

签名：`query.get_etf_component(htsc_code=None, pub_date=None, trading_day=None)`


```python
result = query.get_etf_component(htsc_code=ETF, pub_date=[START, END], trading_day=[START, END])
```


### get_public_fund_portfolio：公募基金投资组合

签名：`query.get_public_fund_portfolio(htsc_code=None, name=None, exchange=None, end_date=None)`


```python
result = query.get_public_fund_portfolio(htsc_code=ETF, end_date=[FIN_START, FIN_END], exchange='XSHG')
```


### get_etf_redemption：ETF申赎数据

签名：`query.get_etf_redemption(htsc_code=None, exchange=None, trading_day=None)`


```python
result = query.get_etf_redemption(htsc_code=ETF, trading_day=[START, END], exchange='XSHG')
```


### get_basic_info：按代码查询跨品种基础资料

签名：`query.get_basic_info(htsc_code=None)`


```python
result = query.get_basic_info(htsc_code=STOCK)
```


### get_all_basic_info：按市场与品种查询基础资料

签名：`query.get_all_basic_info(security_type=None, exchange=None, today=True)`


```python
result = query.get_all_basic_info(exchange='CCFX', security_type='future', today=True)
```


### get_news：证券新闻

签名：`query.get_news(htsc_code=None, event_ids=None, pub_date=None)`


```python
result = query.get_news(htsc_code=STOCK, pub_date=[START, END])
```


### find_edb_index：经济指标目录检索

签名：`query.find_edb_index(name=None)`


```python
result = query.find_edb_index(name='国内生产总值')
```


### edb：经济指标序列

签名：`query.edb(indexes=None, pub_date=None)`


```python
print(query.find_edb_index(name="国内生产总值"))
EDB_INDEX = input("请输入上述目录中的实际指标编号：").strip()
result = query.edb(indexes=[EDB_INDEX], pub_date=[FIN_START, END])
```


### get_rpt_basicinfo_ht：华泰研报基础资料

签名：`query.get_rpt_basicinfo_ht(id=None, report_code=None, time=None, title=None, language=None, is_valid=None)`


```python
result = query.get_rpt_basicinfo_ht(time=[DAY, DAY], language='1', is_valid='1')
```


### get_rpt_stk_ht：研报关联证券

签名：`query.get_rpt_stk_ht(report_code=None)`


```python
REPORT_CODE = input("请输入 get_rpt_basicinfo_ht 返回的实际 report_code：").strip()
result = query.get_rpt_stk_ht(report_code=REPORT_CODE)
```


### get_rpt_industry_ht：研报关联行业

签名：`query.get_rpt_industry_ht(report_code=None)`


```python
REPORT_CODE = input("请输入 get_rpt_basicinfo_ht 返回的实际 report_code：").strip()
result = query.get_rpt_industry_ht(report_code=REPORT_CODE)
```


### get_rpt_author_ht：研报作者

签名：`query.get_rpt_author_ht(report_code=None)`


```python
REPORT_CODE = input("请输入 get_rpt_basicinfo_ht 返回的实际 report_code：").strip()
result = query.get_rpt_author_ht(report_code=REPORT_CODE)
```


### get_rpt_annex_ht：研报附件信息

签名：`query.get_rpt_annex_ht(report_code=None)`


```python
REPORT_CODE = input("请输入 get_rpt_basicinfo_ht 返回的实际 report_code：").strip()
result = query.get_rpt_annex_ht(report_code=REPORT_CODE)
```


### get_rpt_stkpredict_ht：研报盈利预测

签名：`query.get_rpt_stkpredict_ht(report_code=None)`


```python
REPORT_CODE = input("请输入 get_rpt_basicinfo_ht 返回的实际 report_code：").strip()
result = query.get_rpt_stkpredict_ht(report_code=REPORT_CODE)
```


### get_etf_info：异步ETF信息查询

签名：`query.get_etf_info(query)`

异步查询，结果进入 `on_query_response`，函数本身不直接返回 DataFrame。

数据回调：`on_query_response`。


```python
query.get_etf_info(query=[('XSHG', 'fund')])
```


### query_mdcontant：异步证券常量查询

签名：`query.query_mdcontant(security_idsource_and_types, security_id_list)`

方法名沿用原 SDK 拼写。异步结果进入 `on_query_response`。

数据回调：`on_query_response`。


```python
query.query_mdcontant(security_idsource_and_types=[], security_id_list=[STOCK])
```


## 订阅接口

覆盖 11 个数据订阅函数和本地 sync。推送通过回调接收，订阅函数返回不代表已收到行情。
mode 沿用 SDK：coverage 覆盖、add 增加、decrease 减少、cancel 取消。
以下示例独立选用；组合订阅时使用 add，避免后一个 coverage 覆盖之前订阅。
按市场订阅可能覆盖大量证券。K 线订阅 frequency 是列表，与查询中的字符串参数不同。


### subscribe_tick_by_id：按代码订阅Tick

签名：`subscribe.subscribe_tick_by_id(htsc_code, mode='coverage')`

数据回调：`on_subscribe_tick`。


```python
subscribe.subscribe_tick_by_id(htsc_code=STOCK, mode='add')
```

股票、期货、ETF 订阅及模式切换示例：

```python
subscribe.subscribe_tick_by_id([STOCK, FUTURE, ETF], mode="coverage")
subscribe.subscribe_tick_by_id([ETF], mode="decrease")
subscribe.subscribe_tick_by_id([ETF], mode="add")
subscribe.subscribe_tick_by_id([STOCK, FUTURE, ETF], mode="cancel")
```


### subscribe_tick_by_type：按市场与品种订阅Tick

签名：`subscribe.subscribe_tick_by_type(query=None, mode='coverage')`

数据回调：`on_subscribe_tick`。


```python
subscribe.subscribe_tick_by_type(query=[('XSHG', 'stock')], mode='add')
```


### subscribe_kline_by_id：按代码订阅K线

签名：`subscribe.subscribe_kline_by_id(htsc_code=None, frequency=None, mode='coverage')`

数据回调：`on_subscribe_kline`。


```python
subscribe.subscribe_kline_by_id(htsc_code=STOCK, frequency=['1min'], mode='add')
```


### subscribe_kline_by_type：按市场与品种订阅K线

签名：`subscribe.subscribe_kline_by_type(query=None, frequency=None, mode='coverage')`

数据回调：`on_subscribe_kline`。


```python
subscribe.subscribe_kline_by_type(query=[('XSHG', 'stock')], frequency=['1min'], mode='add')
```


### subscribe_trans_and_order_by_id：按代码订阅逐笔成交与委托

签名：`subscribe.subscribe_trans_and_order_by_id(htsc_code=None, mode='coverage')`

数据回调：`on_subscribe_trans_and_order`。


```python
subscribe.subscribe_trans_and_order_by_id(htsc_code=STOCK, mode='add')
```


### subscribe_trans_and_order_by_type：按市场与品种订阅逐笔成交与委托

签名：`subscribe.subscribe_trans_and_order_by_type(query=None, mode='coverage')`

数据回调：`on_subscribe_trans_and_order`。


```python
subscribe.subscribe_trans_and_order_by_type(query=[('XSHG', 'stock')], mode='add')
```


### subscribe_htsc_margin_by_id：按代码订阅华泰融券

签名：`subscribe.subscribe_htsc_margin_by_id(htsc_code=None, data_type=None, mode='coverage')`

数据回调：`on_subscribe_htsc_margin`。


```python
subscribe.subscribe_htsc_margin_by_id(htsc_code=STOCK, data_type='security_lending', mode='add')
```


### subscribe_htsc_margin_by_type：按类型订阅华泰融券

签名：`subscribe.subscribe_htsc_margin_by_type(security_type=None, data_type=None, mode='coverage')`

数据回调：`on_subscribe_htsc_margin`。


```python
subscribe.subscribe_htsc_margin_by_type(security_type='stock', data_type='security_lending', mode='add')
```


### subscribe_derived：订阅衍生数据

签名：`subscribe.subscribe_derived(type=None, htsc_code=None, exchange=None, frequency='1min', mode='coverage')`

数据回调：`on_subscribe_derived`。


```python
subscribe.subscribe_derived(type='north_bound', htsc_code='SCHKSBSH.HT', mode='add')
```


### subscribe_news_by_type：按市场与品种订阅新闻

签名：`subscribe.subscribe_news_by_type(query=None, mode='coverage')`

数据回调：`on_subscribe_news`。


```python
subscribe.subscribe_news_by_type(query=[('XSHG', 'stock')], mode='add')
```


### subscribe_news_by_id：按代码订阅新闻

签名：`subscribe.subscribe_news_by_id(htsc_code=None, mode='coverage')`

数据回调：`on_subscribe_news`。


```python
subscribe.subscribe_news_by_id(htsc_code=STOCK, mode='add')
```


### sync：本地交互等待

签名：`subscribe.sync()`


```python
# 在本地调用 input()，按回车后返回；后台程序可用自己的事件循环保持运行
subscribe.sync()
```


## 回放接口

回放使用原 SDK 的阻塞调用和回调。timeout 是 SDK 回放参数，不保证原生请求能被取消。
回放权限、品种和历史范围以服务端账号及上游能力为准。


### playback_tick：历史Tick回放

签名：`playback.playback_tick(htsc_code=None, replay_time=None, fq='pre', timeout=600)`

数据回调：`on_playback_tick`。


```python
playback.playback_tick(htsc_code=STOCK, replay_time=[DAY, DAY_END], fq='none', timeout=60)
```


### playback_trans_and_order：历史逐笔成交与委托回放

签名：`playback.playback_trans_and_order(htsc_code=None, replay_time=None, fq='pre', timeout=600)`

数据回调：`on_playback_trans_and_order`。


```python
playback.playback_trans_and_order(htsc_code=STOCK, replay_time=[DAY, DAY_END], fq='none', timeout=60)
```


## 回调接口

继承 market_service 并重写所需方法。下面列出全部 13 个回调，保持原方法大小写与参数名称。
回调在客户端后台线程执行，耗时处理宜转交自己的队列。

```python
from insight_proxy.com.insight.market_service import market_service


class FullMarket(market_service):
    def on_subscribe_tick(self, result):
        print("实时 Tick：", result)

    def on_subscribe_kline(self, result):
        print("实时 K 线：", result)

    def on_subscribe_trans_and_order(self, result):
        print("实时逐笔成交与委托：", result)

    def on_subscribe_derived(self, result):
        print("实时衍生数据：", result)

    def on_subscribe_htsc_margin(self, result):
        print("实时华泰融券：", result)

    def on_subscribe_news(self, result):
        print("实时新闻：", result)

    def on_playback_tick(self, result):
        print("回放 Tick：", result)

    def on_playback_trans_and_order(self, result):
        print("回放逐笔成交与委托：", result)

    def onPlaybackStatus(self, status):
        print("回放状态：", status)

    def onPlaybackResponse(self, response):
        print("回放响应：", response)

    def onPlaybackControlResponse(self, response):
        print("回放控制响应：", response)

    def on_query_response(self, result):
        print("异步查询结果：", result)

    def on_query_margin_response(self, result):
        print("异步融券查询结果：", result)
```

实例使用方式：

```python
from insight_proxy.com.insight import Client

with Client(FullMarket()) as client:
    client.query.get_etf_info([("XSHG", "fund")])
    client.query.query_mdcontant([], ["601688.SH"])
    client.query.get_htsc_margin_by_type(
        data_type="security_lending", security_type="stock", is_async=True
    )
    input("等待异步回调，按回车退出。")
```

## 返回值与错误处理

DataFrame 的重复列、列顺序、索引、dtype、缺失值，以及 Series、tuple/list、datetime、
整数精度等保持原 SDK 语义，通过类型化 JSON 传输。有些 SDK 参数校验错误返回字符串，
不能假定所有结果都可以调用 `.head()`。异步请求发出后应保持会话，立即关闭可能来不及接收回调。

```python
import queue
import pandas as pd
from insight_proxy import BridgeError
from insight_proxy.com.insight import Client, SDKError

try:
    with Client(Market()) as client:
        result = client.query.get_stock_info(htsc_code="601688.SH")
        if isinstance(result, pd.DataFrame):
            print(result.head())
        else:
            print("原 SDK 返回：", result)
        try:
            error = client.errors.get_nowait()
        except queue.Empty:
            pass
        else:
            print("后台错误：", error)
except (BridgeError, SDKError, ConnectionError, TimeoutError) as exc:
    print("连接或接口错误：", exc)
except (ValueError, TypeError) as exc:
    print("参数或原 SDK 校验异常：", exc)
```

`client.errors` 接收回调异常与后台连接故障。上述代码只检查当时已到达的错误，
长期运行的程序应持续消费队列。允许列表中的原 SDK 内置异常会恢复其类型，其他 SDK 异常以 SDKError 提供。
如果使用模块级连接，在所需调用全部完成后执行：

```python
close()
```

## 控制台日志

默认显示 INFO 日志，格式为 `时间 | 级别 | 信息`。
连接时显示服务地址、端口和认证结果；连接关闭、异常断线及上游登录状态也会提示。
查询结束打印接口名、标的数量、返回规模和耗时；订阅打印接口、操作模式、标的数量和提交结果。
例如（时间与耗时仅为示意）：

```text
2026-11-13 09:30:00 | INFO    | Socket 连接成功（已认证） | 客户端=C0001 | 地址=127.0.0.1:8765
2026-11-13 09:30:01 | INFO    | C0001 | 查询 K线 | 601688.SH | daily | 6行 | 0.12s
2026-11-13 09:30:02 | INFO    | C0001 | 订阅 Tick | LC2701.GFE | 已提交 | 0.01s
```

“已提交”不代表已经收到行情；异步查询的直接返回可能为 None，应在回调中处理结果。
内置日志不打印完整请求参数、token、密码或逐笔行情。示例回调中的 `print(result)` 由业务程序自行控制。
日志默认输出到 stderr，不修改 Python 根 logger。批量查询时可只保留警告和错误：

```python
from insight_proxy import configure_console_logging

configure_console_logging("WARNING")  # 恢复常规提示用 "INFO"
```

## 兼容范围

把原导入前缀 `insight_python.com.insight` 改为 `insight_proxy.com.insight`，
登录初始化改为 `connect()` 或 `Client(...).connect()`。
数据函数的方法名、位置参数、关键字参数、默认值和回调方法名保持 Insight 6.1.2 兼容。

覆盖 80 个查询函数、11 个数据订阅函数、1 个本地 sync、2 个回放函数和 13 个回调。
SDK 的 common 登录/日志设置、底层 GatewayInterface 与 DLL 类型不属于此客户端封装。
on_query_margin_response 补足了 SDK 实际调用但原基类未声明的回调。
业务字段含义与可用数据范围请结合 [Insight 官方文档](https://inst.htsc.com/helpOnline) 和账号权限确认。

0.0.4 增加广期所修复能力检查，并同步客户端编号和简化日志。请求广期所订阅/回放时，
旧服务端会收到明确的升级提示；股票等原有接口仍可连接旧服务端使用。
0.0.3 增加中文连接提示、上游状态提示及查询/订阅摘要，数据函数签名和返回值不变。
0.0.2 更新中文说明与完整接口示例。
示例进行了 Python 语法、参数签名和覆盖检查，不表示所有接口在当前账号下均已实盘成功。

### 广期所订阅与历史 Tick

**需要同时升级服务端至 0.5.4 或更新版本并重启。仅更新客户端不能修复服务端原生 SDK。**
服务端修复 Insight 6.1.2 的 `.GFE` 订阅白名单、实时 Tick、历史回放 Tick 和 K线市场解码。
按市场订阅使用 `XGFE`，合约代码以 `.GFE` 结尾，解码后的 `exchange` 为 `XGFE`。
历史回放中市场编号缺失时，仅对明确的 `.GFE` 期货代码补齐编号，不覆盖已有编号。
新版服务端仍兼容 0.0.2/0.0.3 客户端；这些旧客户端也能使用服务端修复后的行情。

```python
from datetime import datetime
from insight_proxy.com.insight import Client
from insight_proxy.com.insight.market_service import market_service

class GFEXMarket(market_service):
    def on_subscribe_tick(self, result):
        print("实时 Tick", result)

    def on_subscribe_kline(self, result):
        print("实时 K线", result)

    def on_playback_tick(self, result):
        print("回放 Tick", result)

with Client(GFEXMarket()) as client:
    client.subscribe.subscribe_tick_by_id(["LC2701.GFE", "SI2701.GFE", "PS2701.GFE"], mode="add")
    client.subscribe.subscribe_kline_by_id("LC2701.GFE", frequency=["1min"], mode="add")
    # 按市场订阅的替代写法（会订阅该市场全部期货，请按业务需要启用）：
    # client.subscribe.subscribe_tick_by_type([("XGFE", "future")], mode="add")
    client.playback.playback_tick(
        "LC2701.GFE",
        [datetime(2026, 11, 12, 9, 31), datetime(2026, 11, 12, 9, 32)],
        fq="none", timeout=60,
    )
    input("按回车结束订阅。")
```

请将示例合约和回放时间改为有效合约与可回放交易时段。行情仍需账号权限。
`query.get_kline` 历史 K线保持原样；同步 `query.get_tick` 的沪深代码限制不在此次修复范围，
期货历史 Tick 应使用 `playback.playback_tick`，通过 `on_playback_tick` 接收结果。
