Metadata-Version: 2.4
Name: tgsdk-python
Version: 1.0.2
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 交易。
通过简洁的同步接口，策略可以持续读取行情、计算指标并响应数据变化。

需要 Python 3.12 及以上版本。CTP 交易支持 64 位 Windows/Linux（x86_64）和 macOS（Apple Silicon），需安装对应平台的发行包。
发行 wheel 保留包入口 `tgsdk/__init__.py`；其余模块编译为原生扩展，并通过同名 `.pyi` 提供接口提示。

## 快速开始

安装：

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

获取行情和 K 线：

```python
from tgsdk import TgApi

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

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

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

Quote 和 K 线对象只需获取一次，之后原位更新。对 K 线的变化判断只检查最新一行：
`timestamp` 变化表示出现新 K 线，`close` 变化表示最新一行收盘价实际改变。

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

```python
from tgsdk import TgApi, CtpAccount

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

with TgApi(account) as api:
    funds = api.get_account()
    positions = api.get_position()
    while api.wait_update():
        if api.is_changing(funds, "available"):
            print("柜台可用资金", funds.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()` 判断关注字段的变化。
- **连接管理**：自动连接官方数据服务，支持断线重连和订阅恢复。

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