Metadata-Version: 2.4
Name: tgsdk-python
Version: 1.0.6
Summary: Python futures market data and direct CTP trading SDK
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: pandas<4,>=2.2
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# tgsdk-python

面向期货策略开发的 Python SDK，提供合约查询、实时行情、持续更新的 K 线和直连 CTP 交易。
通过简洁的同步接口，策略可以持续读取行情、计算指标并响应数据变化。

## 快速开始

安装：

```bash
pip install tgsdk-python
```

获取行情和 K 线：

```python
from tgsdk import TgApi

with TgApi() as api:
    # 请替换为当前有效的合约代码。
    symbol = "SHFE.au2610"
    quote = api.watch_quote(symbol)
    klines = api.watch_kline(symbol, "1m", data_length=200)

    while api.wait_update():
        if quote.is_changing("last_price"):
            print("最新价", quote.data().last_price)

        if klines.is_changing("timestamp"):
            print("新 K 线", klines.data().iloc[-1].to_dict())
```

连接交易账户并读取资金：

```python
from tgsdk import TgApi, CtpAccount

ctp_account = CtpAccount(
    broker_id="期货公司代码",
    user_id="资金账号",
    password="交易密码",
    front_url="tcp://期货公司提供的地址:端口",
    app_id="期货公司提供的 AppID",
    auth_code="期货公司提供的授权码",
)

with TgApi(ctp_account) as api:
    account = api.watch_account()
    while api.wait_update():
        if account.is_changing("available"):
            print("柜台可用资金", account.data().available)
```

## 系统架构

```mermaid
flowchart TD
    Broker[期货公司交易柜台]
    Market[官方期货行情系统]
    SDK[tgsdk]

    Broker <-->|直连 CTP| SDK
    Market -->|行情接口| SDK

    classDef source fill:#f3f4f6,stroke:#9ca3af,color:#111;
    classDef sdk fill:#dbeafe,stroke:#598bea,stroke-width:2px,color:#111;

    class Broker,Market source;
    class SDK sdk;
```

- **策略始终运行在用户本地环境中，策略代码与交易信号计算均保留在本地。**
- **交易连接由本地 SDK 直接建立到期货公司柜台，交易账号、密码和委托不经过行情服务。**

## 主要功能

- **合约查询**：按交易所、品种、是否主力筛选合约，获取合约详细信息。
- **实时行情**：通过 Quote 对象读取最新价格、成交量、持仓量和盘口。
- **K 线序列**：通过 pandas DataFrame 获取历史与实时 K 线，支持八种固定周期。
- **CTP 交易**：读取资金、持仓、订单与成交，支持限价下单、撤单，以及普通平仓、平今和平昨。
- **统一更新**：使用 `wait_update()` 推进更新，通过观察句柄的 `is_changing()` 判断变化、`data()` 读取快照。
- **连接管理**：自动连接官方数据服务，支持断线重连和订阅恢复。

完整接口、周期取值、数据字段和使用约定见 [SDK 使用指南](docs/usage.md)。使用本软件前请阅读安装包内的 `DISCLAIMER.md`。
