tsl-devkit/docs/tsl/modules/pytsl_api.md

天软 pyTSL 接口使用说明

文档类型：模块摘要 是否可直接用于生成代码：仅部分 是否含已验证可执行示例：否 是否含已验证反例：否 遇到不确定时跳转到：项目级部署文档、官方 pyTSL 详细接口文档、tsl_python_interop.md、index.md

本页用于确认 pyTSL 的接入方向和最小链路，不替代项目级部署文档或完整接口手册。

• 如果登录方式、凭证来源、环境变量、部署入口、连接上下文或返回结构没有确认，不继续生成接入代码，直接回项目级部署文档或官方 pyTSL 详细接口文档。

定位

• 官方 Python SDK，面向取数/执行/批量/异步与数据转换。

结构索引

• 安装与配置
• pyTSL 接口说明（Client / AsyncClient / async_util / Batch / Task / Const / TSResultValue）
• pyTSLPy 兼容说明
• 示例与数据类型转换
• 附录与常见问题

安装方式（摘要）

• pip install tspytsl（在线安装）
• 离线安装与手动部署

同步 / 异步怎么选

• 同步：任务短、交互简单、立即取结果时优先用 pyTSL.Client。
• 异步：任务长、需要并发或批量调度时再看 pyTSL.AsyncClient 与 async_util。
• 如果只是先打通最小链路，先用同步客户端，不要一开始就上异步。

核心类与模块

• pyTSL.Client：同步客户端
• pyTSL.AsyncClient：异步客户端
• pyTSL.async_util：异步工具函数
• TSBatch / Task：批量与任务
• TSResultValue：统一返回结果封装
• pyTSL.Const：常量与字段

关键方法（常用）

• login / logout
• exec / call / query
• download_list / download / upload / remove
• DatetimeToDouble / DoubleToDatetime
• EncodeStream / DecodeStream
• DataFrameToTSArray

最小成功路径

1. 先回项目级部署文档确认登录方式、凭证来源、环境变量和部署入口。
2. 安装 tspytsl。
3. 创建 pyTSL.Client(...)。
4. 调 login() 登录。
5. 用 query(...)、exec(...) 或 call(...) 执行任务。
6. 从返回结果里读取你真正需要的内容；常见起手是 result.dataframe()。
7. 完成后显式 logout()。

返回结果与失败处理

• 常见返回会落在 TSResultValue 这一层；真正用之前，先确认你要的是表格、标量还是其他结构。
• 最小起手路径可以先看 result.dataframe() 是否符合预期，再扩展到别的读取方式。
• 登录、查询和退出应当成对出现；不要把长期未退出的连接当默认用法。
• 如果失败，先检查安装、登录上下文、查询语句和返回结构，再决定是否切到异步客户端。
• 如果还不能确认登录方式、凭证来源或返回结构，不继续扩展接入代码，先回项目级部署文档和官方接口文档。

示例（Python）

示例里的 "user" / "password" 只表示调用外形，不代表项目里的真实登录方式或凭证来源。

代码块身份：配置片段 / 概念骨架 代码块说明：可参考最小链路，不是已验证可执行示例。

import pyTSL

c = pyTSL.Client("user", "password")
c.login()

result = c.query("select close from market where stock = 'SZ000001' end")
print(result.dataframe())

c.logout()