5.2 KiB
| sidebar_label | title | description |
|---|---|---|
| Python | TDengine Python 连接器 | taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API，使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装，分别对应 tasopy 的两个子模块：taos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范 (PEP 249) 的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas |
taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API，使得 Python 应用可以很方便地使用 TDengine。
taospy 对 REST 接口进行了封装，还提供了符合 Python 数据访问规范 (PEP 249) 的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas。
Python 连接器的源码托管在 GitHub。
连接方式
taospy主要提供三种形式的连接器。TDengine Cloud 支持 REST 连接和 WebSocket 连接两种方式
- 原生连接，对应 taospy 包的 taos 模块。通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
- REST 连接，对应 taospy 包的 taosrest 模块。通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。
- WebSocket 连接，对应 taos-ws-py 包，可以选装。通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。
:::note IMPORTANT
-
使用客户端驱动提供的原生接口直接与服务端建立的连接，下文中称为“原生连接”.
-
使用 taosAdapter 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。 :::
关于如何建立连接的详细介绍请参考：开发指南 - 建立连接-Python
示例程序
下面以智能电表为例，展示如何使用 Python 连接器在名为 power 的数据库中，创建一个名为 meters 的超级表（STABLE），插入并查询数据。meters 表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。
:::note IMPORTANT
- 在执行下面样例代码的之前，您必须先在 TDengine Cloud - 数据浏览器 页面创建一个名为 power 的数据库
- 如何在代码中建立和 TDengine Cloud 的连接，请参考 开发指南 - 建立连接。 :::
使用 TaosRestConnection 类
{{#include docs/examples/python/reference_connection.py:example}}
使用 TaosRestCursor 类
TaosRestCursor 类是对 PEP249 Cursor 接口的实现。
{{#include docs/examples/python/reference_cursor.py:basic}}
cursor.execute：用来执行任意 SQL 语句。cursor.rowcount：对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。cursor.description：返回字段的描述信息。关于描述信息的具体格式请参考TaosRestCursor。
使用 RestClient 类
RestClient 类是对于 REST API 的直接封装。它只包含一个 sql() 方法用于执行任意 SQL 语句，并返回执行结果。
{{#include docs/examples/python/reference_rest_client.py}}
对于 sql() 方法更详细的介绍，请参考 RestClient。
其它说明
异常处理
所有数据库操作如果出现异常，都会直接抛出来。由应用程序负责异常处理。比如：
{{#include docs/examples/python/handle_exception.py}}
关于纳秒 (nanosecond)
由于目前 Python 对 nanosecond 支持的不完善 (见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。
- parsing-datetime-strings-containing-nanoseconds
- PEP 564 -- Support for the Python nanosecond timestamp
重要更新
API 参考
更多关于 Python 连接器的详细介绍请参考连接器-Python
常见问题
欢迎提问或报告问题。