tgsdk-python 1.0.1__cp313-cp313-win_amd64.whl

tgsdk/DISCLAIMER.md

@@ -0,0 +1,9 @@
+# 免责声明
+
+tgsdk 仅提供期货行情访问与交易接口工具，不构成投资建议、收益承诺或交易结果保证。
+
+期货交易具有较高风险。因网络中断、行情延迟、交易柜台异常、交易所规则变化、程序错误、用户策略或操作等原因造成的委托失败、重复委托、成交差异、资金损失及其他直接或间接损失，由用户自行承担。
+
+用户应在充分测试并理解接口行为后使用本软件，并自行遵守适用的法律法规、交易所规则及期货公司要求。
+
+本软件及其安装包为闭源软件。除权利人明确书面授权外，不授予复制、修改、反向工程、再发布、转售或以其他方式处置本软件的权利。

tgsdk/__init__.py

@@ -0,0 +1,20 @@
+"""期货行情与直连 CTP 交易 SDK。"""
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_1():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'tgsdk_python.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_1()
+del _delvewheel_patch_1_13_1
+# end delvewheel patch
+
+from .api import TgApi
+from .data import KlinePeriod, Quote, TgError
+from .trading_data import CtpAccount, Account, Position, Order, Trade
+
+__all__ = ["TgApi", "KlinePeriod", "Quote", "TgError", "CtpAccount", "Account", "Position", "Order", "Trade"]
+__version__ = "1.0.1"

tgsdk/api.pyi

@@ -0,0 +1,139 @@
+import os
+import pandas as pd
+import types
+from .data import BAR_COLUMNS as BAR_COLUMNS, KlinePeriod as KlinePeriod, Quote as Quote, Serial as Serial, TgError as TgError, check_symbol as check_symbol, decode as decode, different as different
+from .trading import Trading as Trading
+from .trading_data import Account as Account, CtpAccount as CtpAccount, LiveMap as LiveMap, LiveObject as LiveObject, Order as Order, Position as Position, Trade as Trade
+from .transport import Transport as Transport
+from collections.abc import Mapping
+from datetime import date, datetime
+from typing import Literal, overload
+
+class TgApi:
+    """期货行情与交易接口，须在创建实例的线程中使用。
+
+    Args:
+        account: CTP 账户配置；不传时仅使用行情功能。
+        timeout: 连接和请求的超时秒数，默认 30 秒。
+
+    推荐通过 ``with TgApi(...) as api:`` 自动关闭连接。
+    实时数据统一在 ``wait_update()`` 中更新。
+    """
+    def __init__(self, account: CtpAccount | None = None, *, timeout: float = 30.0) -> None:
+        """创建 SDK 实例。account 不传时仅启用行情；timeout 为超时秒数。"""
+    def get_account(self) -> Account:
+        """获取持续更新的只读资金对象，不发起查询。
+
+        金额来自最近一次完整柜台查询；未知字段为 None。
+        使用 wait_update() 更新，未配置 CtpAccount 时抛出 RuntimeError。
+        """
+    @overload
+    def get_position(self, symbol: str) -> Position:
+        """获取指定合约的持续更新持仓对象，symbol 如 SHFE.rb2610。"""
+    @overload
+    def get_position(self, symbol: None = None) -> Mapping[str, Position]:
+        """获取全部持仓的持续更新只读集合，以合约代码为键。"""
+    @overload
+    def get_order(self, order_id: str) -> Order:
+        """按本地订单号获取持续更新的订单；未知 ID 抛出 KeyError。"""
+    @overload
+    def get_order(self, order_id: None = None) -> Mapping[str, Order]:
+        """获取当前连接订单的持续更新只读集合，以本地订单号为键。"""
+    def get_trade(self) -> Mapping[str, Trade]:
+        """获取当前连接全部真实成交的持续更新只读集合，不发起查询。
+
+        断线后集合原位清空，旧成交对象失效。
+        """
+    def insert_order(self, symbol: str, direction: Literal['BUY', 'SELL'], offset: Literal['OPEN', 'CLOSE', 'CLOSE_TODAY', 'CLOSE_YESTERDAY'], volume: int, limit_price: float) -> str:
+        """提交一笔限价委托，返回本地订单号。账户须已同步为 READY。
+
+        Args:
+            symbol: 合约代码，如 SHFE.rb2610。
+            direction: BUY 买入，SELL 卖出。
+            offset: OPEN 开仓，CLOSE 普通平仓，CLOSE_TODAY 平今，
+                CLOSE_YESTERDAY 平昨。
+            volume: 委托数量，单位为手，须为正整数。
+            limit_price: 委托价格，须符合合约最小变动价位。
+
+        每次调用只发送一笔 CTP 委托，不会自动拆分；柜台结果由 wait_update() 更新。
+        """
+    def cancel_order(self, order_id: str) -> None:
+        """撤销本地订单号对应的委托。
+
+        Args:
+            order_id: ``FrontID:SessionID:OrderRef`` 格式的本地订单号。
+
+        尚无交易所订单号时等待回报再发送。返回不表示撤单成功，
+        请通过 wait_update() 查看订单状态；断线会清除待发送的撤单。
+        """
+    def query_symbols(self, exchange_id: str | None = None, product_id: str | None = None, is_main: bool | None = None) -> list[str]:
+        """查询合约代码列表，返回一次性查询结果。
+
+        Args:
+            exchange_id: 交易所代码，如 SHFE；None 表示不限。
+            product_id: 品种代码，如 rb；None 表示不限。
+            is_main: True 仅主力，False 仅非主力，None 表示不限。
+        """
+    def query_symbol_info(self, symbol: str) -> dict:
+        """查询合约详细信息，返回一次性字典结果。
+
+        symbol 为交易所.合约，如 SHFE.rb2610。结果包含 symbol、
+        exchange_id、product_id、is_main，以及详细信息字典 data。
+        """
+    def get_quote(self, symbol: str) -> Quote:
+        """订阅合约行情，立即返回持续更新的 Quote 对象。
+
+        symbol 如 SHFE.rb2610。同一合约返回同一对象，
+        通过 wait_update() 接收行情，SDK 字段应视为只读。
+        """
+    def get_kline_serial(self, symbol: str, period: KlinePeriod, data_length: int = 200) -> pd.DataFrame:
+        """获取最近历史 K 线并订阅更新，返回固定长度的 DataFrame。
+
+        Args:
+            symbol: 合约代码，如 SHFE.rb2610。
+            period: KlinePeriod 周期常量，如 KlinePeriod.MIN_1。
+            data_length: K 线数量，范围 1–10000，默认 200。
+
+        后续数据在 wait_update() 中原位更新。可添加指标列，
+        不要修改 SDK 列、索引或行数。timestamp 为 K 线结束时间的 Unix 毫秒。
+        """
+    def download_kline_data(self, symbol: str, period: KlinePeriod, start_dt: date | datetime, end_dt: date | datetime, csv_file_name: str | os.PathLike) -> int:
+        """下载指定时间范围的 K 线到 CSV，返回写入的数据行数。
+
+        Args:
+            symbol: 合约代码，如 SHFE.rb2610。
+            period: KlinePeriod 周期常量，如 KlinePeriod.MIN_1。
+            start_dt: 起始日期或时间，包含边界；日期从当天零点起算。
+            end_dt: 结束日期或时间，包含边界；日期包含当天全天。
+            csv_file_name: CSV 文件路径，父目录须已存在。
+
+        无时区的时间按北京时间解释。成功后覆盖同名文件，失败保留原文件。
+        CSV 使用 UTF-8 BOM 编码，不含索引；无数据时仅写表头并返回 0。
+        此方法同步完成，无需调用 wait_update()。
+        """
+    def wait_update(self, deadline: float | None = None) -> bool:
+        """等待并提交一批行情或交易更新，有更新返回 True，截止超时返回 False。
+
+        Args:
+            deadline: Unix 秒绝对截止时间，如 time.time() + 10；None 表示持续等待。
+
+        同一笔成交对应的成交、订单成交量和持仓会同时提交；
+        资金来自独立查询，不保证同时更新。可仅用于交易账户。
+        """
+    def is_changing(self, obj: Quote | pd.DataFrame | LiveObject | Mapping[str, LiveObject], key: str | list[str] | None = None) -> bool:
+        """判断对象或指定字段在本次 wait_update() 中是否变化。
+
+        Args:
+            obj: 本实例返回的行情、K 线、交易对象或实时集合。
+            key: 字段名、字段名列表；None 表示检查业务字段。
+
+        K 线仅比较最新一行；检查 timestamp 可判断是否出现新 K 线。
+        交易对象默认忽略 updated_at，显式传入该字段才检查刷新时间。
+        """
+    def close(self) -> None:
+        """关闭连接并释放资源，可重复调用；不会撤销已提交的订单。
+
+        程序正常退出时会自动关闭，仍推荐使用 with 或主动调用 close()。
+        """
+    def __enter__(self) -> TgApi: ...
+    def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None) -> None: ...

tgsdk/data.pyi

@@ -0,0 +1,96 @@
+from _typeshed import Incomplete
+from dataclasses import dataclass, field
+from enum import Enum
+
+class TgError(Exception):
+    """SDK 数据或交易服务异常，status 为可选的响应状态码。"""
+    status: Incomplete
+    def __init__(self, message: str, *, status: int | None = None) -> None: ...
+
+class KlinePeriod(Enum):
+    """K 线周期：MIN_1/5/10/15/30 为分钟，HOUR_1/4 为小时，DAY_1 为日线。"""
+    MIN_1 = '1m'
+    MIN_5 = '5m'
+    MIN_10 = '10m'
+    MIN_15 = '15m'
+    MIN_30 = '30m'
+    HOUR_1 = '1h'
+    HOUR_4 = '4h'
+    DAY_1 = '1d'
+
+@dataclass(eq=False)
+class Quote:
+    """持续更新的合约行情，通过 wait_update() 更新，SDK 字段应视为只读。
+
+    Attributes:
+        symbol: 合约代码，如 SHFE.rb2610。
+        trading_day: 交易日，格式 YYYYMMDD。
+        timestamp: 行情时间，Unix 毫秒。
+        open: 开盘价。
+        highest: 最高价。
+        lowest: 最低价。
+        last_price: 最新价。
+        pre_settlement: 昨结算价。
+        pre_close: 昨收盘价。
+        upper_limit: 涨停价。
+        lower_limit: 跌停价。
+        volume: 成交量。
+        turnover: 成交额。
+        open_interest: 持仓量。
+        bids: 买盘档位，每档为（价格，数量）。
+        asks: 卖盘档位，每档为（价格，数量）。
+    """
+    symbol: str
+    '合约代码，如 SHFE.rb2610。'
+    trading_day: str = ...
+    '交易日，格式 YYYYMMDD。'
+    timestamp: int = ...
+    '行情时间，Unix 毫秒。'
+    open: float = ...
+    '开盘价。'
+    highest: float = ...
+    '最高价。'
+    lowest: float = ...
+    '最低价。'
+    last_price: float = ...
+    '最新价。'
+    pre_settlement: float = ...
+    '昨结算价。'
+    pre_close: float = ...
+    '昨收盘价。'
+    upper_limit: float = ...
+    '涨停价。'
+    lower_limit: float = ...
+    '跌停价。'
+    volume: float = ...
+    '成交量。'
+    turnover: float = ...
+    '成交额。'
+    open_interest: float = ...
+    '持仓量。'
+    bids: list = field(default_factory=list)
+    '买盘档位，每档为（价格，数量）。'
+    asks: list = field(default_factory=list)
+    '卖盘档位，每档为（价格，数量）。'
+    def __setattr__(self, key, value) -> None: ...
+
+BAR_FIELDS: Incomplete
+QUOTE_FIELDS: Incomplete
+BAR_COLUMNS: Incomplete
+
+def check_symbol(symbol) -> None: ...
+def number(value): ...
+def decode(data, symbol, *, quote: bool = False):
+    """Validate a complete message before exposing any of its fields."""
+def different(old, new): ...
+
+class Serial:
+    symbol: Incomplete
+    period: Incomplete
+    length: Incomplete
+    bars: Incomplete
+    initial_generation: int
+    initial_sequence: int
+    frame: Incomplete
+    def __init__(self, symbol, period, length) -> None: ...
+    def update(self, bars): ...

tgsdk/trading.pyi

@@ -0,0 +1,62 @@
+from .data import TgError as TgError, check_symbol as check_symbol, different as different
+from .trading_data import Account as Account, LiveMap as LiveMap, Order as Order, Position as Position, Trade as Trade, empty_position as empty_position
+from _typeshed import Incomplete
+
+log: Incomplete
+TZ: Incomplete
+QUERY: Incomplete
+SYNC_STEPS: Incomplete
+ACCOUNT_FIELDS: Incomplete
+OFFSET_BY_FLAG: Incomplete
+FLAG_BY_OFFSET: Incomplete
+
+def timestamp(day, clock): ...
+def finite(value): ...
+def local_order_id(front, session, order_ref): ...
+def order_offset(value): ...
+
+class Native:
+    module: Incomplete
+    handle: Incomplete
+    def __init__(self, config, directory) -> None: ...
+    def request(self, method, data, request_id): ...
+    def poll(self): ...
+    def close(self) -> None: ...
+
+class Trading:
+    """Private protocol state is committed to user objects only by wait_update."""
+    factory: Incomplete
+    account: Incomplete
+    a: Incomplete
+    instruments: Incomplete
+    live_trade_buffer: Incomplete
+    trade_before: Incomplete
+    position_candidate: Incomplete
+    position_ready: bool
+    sync_index: int
+    last_query: Incomplete
+    last_account_refresh: float
+    phase_data: Incomplete
+    dirty: bool
+    local_changes: Incomplete
+    changed: Incomplete
+    directory: Incomplete
+    reset_pending: bool
+    cancel_pending: Incomplete
+    published_position_time: Incomplete
+    def __init__(self, config, timeout, objects, *, native_factory=...) -> None: ...
+    def get_position(self, symbol): ...
+    task: Incomplete
+    def start(self) -> None: ...
+    phase: str
+    error: Incomplete
+    async def run(self) -> None: ...
+    day: Incomplete
+    order_ref: Incomplete
+    inflight: Incomplete
+    def event(self, event) -> None: ...
+    def tick(self, now) -> None: ...
+    async def insert(self, symbol, direction, offset, volume, limit_price): ...
+    def cancel(self, order_id) -> None: ...
+    def commit(self, changes): ...
+    async def close(self) -> None: ...

tgsdk/trading_data.pyi

@@ -0,0 +1,170 @@
+from _typeshed import Incomplete
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+@dataclass(frozen=True)
+class CtpAccount:
+    """CTP 直连账户配置，交易凭据不会发送至行情服务。
+
+    Args:
+        broker_id: 期货公司代码。
+        user_id: 资金账号。
+        password: 交易密码。
+        front_url: 交易前置地址，格式为 tcp://地址:端口。
+        app_id: 期货公司提供的客户端标识。
+        auth_code: 期货公司提供的客户端授权码。
+    """
+    broker_id: str
+    '期货公司代码。'
+    user_id: str
+    '资金账号。'
+    password: str = field(repr=False)
+    '交易密码。'
+    front_url: str
+    '交易前置地址，格式为 tcp://地址:端口。'
+    app_id: str
+    '期货公司提供的客户端标识。'
+    auth_code: str = field(repr=False)
+    '期货公司提供的客户端授权码。'
+    def __post_init__(self) -> None: ...
+
+class LiveObject:
+    fields: Incomplete
+    def __init__(self, **values) -> None: ...
+    def __getattr__(self, key): ...
+    def __setattr__(self, key, value) -> None: ...
+
+class LiveMap(Mapping):
+    item_type: Incomplete
+    def __init__(self, item_type) -> None: ...
+    def __getitem__(self, key): ...
+    def __iter__(self): ...
+    def __len__(self) -> int: ...
+
+class Account(LiveObject):
+    """只读资金快照；金额单位为人民币元，未知字段为 None。
+
+    仅由完整柜台查询更新，不根据行情或成交估算资金。
+    """
+    account_id: str | None
+    '资金账号。'
+    trading_day: str | None
+    '交易日，格式 YYYYMMDD。'
+    sync_status: str
+    '同步状态：INITIALIZING、READY、DISCONNECTED、RESYNCING 或 ERROR。'
+    balance: float | None
+    '账户权益。'
+    available: float | None
+    '可用资金。'
+    margin: float | None
+    '已占用保证金。'
+    frozen_margin: float | None
+    '冻结保证金。'
+    commission: float | None
+    '当日累计实际手续费。'
+    frozen_commission: float | None
+    '冻结手续费。'
+    close_profit: float | None
+    '当日平仓盈亏。'
+    position_profit: float | None
+    '持仓盈亏。'
+    deposit: float | None
+    '当日入金。'
+    withdraw: float | None
+    '当日出金。'
+    updated_at: int | None
+    '最近一次完整查询完成的本地时间，Unix 毫秒。'
+    fields: Incomplete
+
+class Position(LiveObject):
+    """持续更新的只读持仓；数量单位为手。
+
+    登录查询建立基线，之后根据真实成交本地更新；未知数量为 None。
+    """
+    symbol: str
+    '合约代码，如 SHFE.rb2610。'
+    pos_long: int | None
+    '多头持仓。'
+    pos_short: int | None
+    '空头持仓。'
+    pos: int | None
+    '净持仓，多头减空头。'
+    pos_long_today: int | None
+    '剩余多头今仓。'
+    pos_short_today: int | None
+    '剩余空头今仓。'
+    pos_long_his: int | None
+    '剩余多头历史仓。'
+    pos_short_his: int | None
+    '剩余空头历史仓。'
+    frozen_long: int | None
+    '卖出平仓冻结的多头持仓。'
+    frozen_short: int | None
+    '买入平仓冻结的空头持仓。'
+    available_long: int | None
+    '同一查询快照中的可平多头数量。'
+    available_short: int | None
+    '同一查询快照中的可平空头数量。'
+    updated_at: int | None
+    '最近一次持仓数量或冻结状态更新时间，Unix 毫秒。'
+    fields: Incomplete
+
+class Order(LiveObject):
+    """持续更新的只读订单，断线后失效。"""
+    order_id: str
+    'FrontID:SessionID:OrderRef 格式的本地订单号。'
+    symbol: str
+    '合约代码。'
+    direction: str | None
+    'BUY 买入，SELL 卖出。'
+    offset: str | None
+    'OPEN 开仓，CLOSE 普通平仓，CLOSE_TODAY 平今，CLOSE_YESTERDAY 平昨。'
+    limit_price: float | None
+    '委托限价。'
+    volume_original: int | None
+    '原始委托数量，单位为手。'
+    volume_traded: int | None
+    '已成交数量，单位为手。'
+    volume_left: int | None
+    '未成交数量；撤单结束后仍可大于零。'
+    status: str | None
+    'ALIVE 有效，FINISHED 已结束；失效对象为 None。'
+    is_confirmed: bool
+    '当前状态是否已确认且同步有效。'
+    is_error: bool | None
+    '是否存在报单失败。'
+    last_msg: str | None
+    '最新状态说明。'
+    insert_time: int | None
+    '委托时间，Unix 毫秒。'
+    trade_records: Mapping[str, Trade]
+    '此订单的只读成交集合，与全局集合引用相同成交对象。'
+    fields: Incomplete
+
+class Trade(LiveObject):
+    """只读真实成交记录，不包含估算手续费；断线后对象失效。"""
+    trade_id: str
+    'SDK 成交 ID。'
+    exchange_trade_id: str | None
+    '交易所原始成交号。'
+    order_id: str
+    '关联的本地订单号。'
+    symbol: str
+    '合约代码。'
+    direction: str | None
+    'BUY 买入，SELL 卖出。'
+    offset: str | None
+    'OPEN 开仓，CLOSE 普通平仓，CLOSE_TODAY 平今，CLOSE_YESTERDAY 平昨。'
+    close_type: str | None
+    'TODAY 平今，HISTORY 平历史仓，UNSPECIFIED 普通平仓，None 开仓或未知。'
+    price: float | None
+    '实际成交价格。'
+    volume: int | None
+    '实际成交数量，单位为手。'
+    trade_time: int | None
+    '成交时间，Unix 毫秒。'
+    trading_day: str | None
+    '交易日，格式 YYYYMMDD。'
+    fields: Incomplete
+
+def empty_position(symbol, updated_at=None): ...

tgsdk/transport.pyi

@@ -0,0 +1,36 @@
+from .data import TgError as TgError, decode as decode
+from _typeshed import Incomplete
+
+logger: Incomplete
+
+class Transport:
+    url: Incomplete
+    ws_url: Incomplete
+    timeout: Incomplete
+    restore: Incomplete
+    session: Incomplete
+    channels: Incomplete
+    acked: Incomplete
+    incoming: Incomplete
+    changed: Incomplete
+    subscriptions_changed: Incomplete
+    ack_changed: Incomplete
+    task: Incomplete
+    generation: int
+    sequence: int
+    ready: bool
+    error: Incomplete
+    ws: Incomplete
+    def __init__(self, url, timeout, restore) -> None: ...
+    async def client(self): ...
+    async def get(self, path, params=None): ...
+    def subscribe(self, channel) -> None: ...
+    def start(self) -> None: ...
+    def raise_error(self) -> None: ...
+    async def wait_ack(self, channel) -> None: ...
+    async def send_subscriptions(self) -> None: ...
+    async def receive(self) -> None: ...
+    async def bootstrap(self) -> None: ...
+    async def run(self) -> None: ...
+    async def next_batch(self): ...
+    async def close(self) -> None: ...

tgsdk_python-1.0.1.dist-info/DELVEWHEEL

@@ -0,0 +1,2 @@
+Version: 1.13.1
+Arguments: ['C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-uigkki2f\\cp313-win_amd64\\build\\venv\\Scripts\\delvewheel', 'repair', '--ignore-existing', '-w', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-uigkki2f\\cp313-win_amd64\\repaired_wheel', '-v', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-uigkki2f\\cp313-win_amd64\\built_wheel\\tgsdk_python-1.0.1-cp313-cp313-win_amd64.whl']

tgsdk_python-1.0.1.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: tgsdk-python
+Version: 1.0.1
+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, KlinePeriod
+
+with TgApi() as api:
+    # 请替换为当前有效的合约代码。
+    symbol = "SHFE.au2609"
+    quote = api.get_quote(symbol)
+    klines = api.get_kline_serial(symbol, KlinePeriod.MIN_1, 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`。

tgsdk_python-1.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+tgsdk/api.cp313-win_amd64.pyd,sha256=6VTbfM9jIilm5gA3UJ50xZONopb9YUbnHI8a7NI2YZY,276992
+tgsdk/api.pyi,sha256=N6ZqbuhOZqtI2BX4q7dDWruNawASjJdVVps4sq-T4hA,7661
+tgsdk/data.cp313-win_amd64.pyd,sha256=KfPQnSNOh_cDKfkals7fZ2ZjGsgkfsdrR-ucO3qtr50,105984
+tgsdk/data.pyi,sha256=jdQfEtUar-h172swCTENXqNy986yNWvzPSTxg7SYQoM,2962
+tgsdk/DISCLAIMER.md,sha256=6kNOTQKd3iRKx2X80XWOF85jwbrJZB0leQGwcwRkhGA,755
+tgsdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tgsdk/thosttraderapi_se.dll,sha256=q8_3T5OloBcXkYCnxDU9Qig_Yz_7yJRwI_9iVTOv3r4,3400192
+tgsdk/trading.cp313-win_amd64.pyd,sha256=gaSfJa0Nt75A7sCOejuIw7kdBI_ETB8ZnJtq14IfKTM,361472
+tgsdk/trading.pyi,sha256=eg5scomk3oCl0dBfsYbAfXUWCI5sur3PbTcc7Pjl3ek,2066
+tgsdk/trading_data.cp313-win_amd64.pyd,sha256=0Lg2tsJNAoBekNLDyUFvcr1IORaICGn92F1YehjEUx8,73216
+tgsdk/trading_data.pyi,sha256=ugx0S5UtmLO8dlaasNa0mKUlLJVeCcGp6Qs65E6U4Y0,5723
+tgsdk/transport.cp313-win_amd64.pyd,sha256=lNLIBWCZOhs2FQscp3Bs9kIsWDzrMOWBzM6vFTJwC8k,162816
+tgsdk/transport.pyi,sha256=3xnha18kjUYdywG6Jo_LLmouJ0sqpqysRAKvsei8znQ,1111
+tgsdk/_ctp.cp313-win_amd64.pyd,sha256=6sncHVB4hO1uAkyHTciJL4h0flKIgzT_8ceXta-EmE4,64000
+tgsdk/__init__.py,sha256=MmAuH3EMJC5HHxyzT1PEECA-OlyEB2wojDNmSV6MXzw,656
+tgsdk_python-1.0.1.dist-info/DELVEWHEEL,sha256=dXhb4MRoL_CjlPknbrjc_IVDMXYsEPBIBV_Yy4I7874,432
+tgsdk_python-1.0.1.dist-info/METADATA,sha256=ji7NGZ1r-ESoQvkZShbykJ4atMckKgz1yBUbCEcwjRs,4047
+tgsdk_python-1.0.1.dist-info/RECORD,,
+tgsdk_python-1.0.1.dist-info/top_level.txt,sha256=Qa-_dytgV1Q7Lc8P1vadyaZYxLP1ydHzAglWt6cvjtM,6
+tgsdk_python-1.0.1.dist-info/WHEEL,sha256=0LUNoHxLvcpw9db_x0XozE5jW73-_GOAO7fDDJ4Xt4Q,101
+tgsdk_python.libs/msvcp140-a4c2229bdc2a2a630acdc095b4d86008.dll,sha256=pMIim9wqKmMKzcCVtNhgCOXD47x3cxdDVPPaT1vrnN4,575056

tgsdk_python-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

tgsdk_python-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+tgsdk