mirror of
https://github.com/taosdata/TDengine
synced 2026-05-24 10:09:01 +00:00
98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
---
|
||
sidebar_label: Python
|
||
title: TDengine Python 连接器
|
||
description: "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)](https://peps.python.org/pep-0249/) 的编程接口。这使得 `taospy` 和很多第三方工具集成变得简单，比如 [SQLAlchemy](https://www.sqlalchemy.org/) 和 [pandas](https://pandas.pydata.org/)。
|
||
|
||
Python 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-python)。
|
||
|
||
## 连接方式
|
||
|
||
`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
|
||
|
||
1. 使用客户端驱动提供的原生接口直接与服务端建立的连接，下文中称为“原生连接”.
|
||
|
||
2. 使用 taosAdapter 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。
|
||
:::
|
||
|
||
关于如何建立连接的详细介绍请参考：[开发指南 - 建立连接-Python](../01-connect/01-python.md)
|
||
|
||
## 示例程序
|
||
|
||
下面以智能电表为例，展示如何使用 Python 连接器在名为 power 的数据库中，创建一个名为 meters 的超级表（STABLE），插入并查询数据。meters 表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。
|
||
|
||
:::note IMPORTANT
|
||
|
||
1. 在执行下面样例代码的之前，您必须先在 [TDengine Cloud - 数据浏览器](https://cloud.taosdata.com/explorer) 页面创建一个名为 power 的数据库
|
||
2. 如何在代码中建立和 TDengine Cloud 的连接，请参考 [开发指南 - 建立连接](../../connect/)。
|
||
:::
|
||
|
||
### 使用 TaosRestConnection 类
|
||
|
||
```python
|
||
{{#include docs/examples/python/reference_connection.py:example}}
|
||
```
|
||
|
||
### 使用 TaosRestCursor 类
|
||
|
||
`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。
|
||
|
||
```python
|
||
{{#include docs/examples/python/reference_cursor.py:basic}}
|
||
```
|
||
|
||
* `cursor.execute` ：用来执行任意 SQL 语句。
|
||
* `cursor.rowcount`：对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。
|
||
* `cursor.description` ：返回字段的描述信息。关于描述信息的具体格式请参考[TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html)。
|
||
|
||
#### 使用 RestClient 类
|
||
|
||
`RestClient` 类是对于 [REST API](../rest-api) 的直接封装。它只包含一个 `sql()` 方法用于执行任意 SQL 语句，并返回执行结果。
|
||
|
||
```python
|
||
{{#include docs/examples/python/reference_rest_client.py}}
|
||
```
|
||
|
||
对于 `sql()` 方法更详细的介绍，请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
|
||
|
||
## 其它说明
|
||
|
||
### 异常处理
|
||
|
||
所有数据库操作如果出现异常，都会直接抛出来。由应用程序负责异常处理。比如：
|
||
|
||
```python
|
||
{{#include docs/examples/python/handle_exception.py}}
|
||
```
|
||
|
||
### 关于纳秒 (nanosecond)
|
||
|
||
由于目前 Python 对 nanosecond 支持的不完善 (见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。
|
||
|
||
1. [parsing-datetime-strings-containing-nanoseconds](https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds)
|
||
2. [PEP 564 -- Support for the Python nanosecond timestamp](https://www.python.org/dev/peps/pep-0564/)
|
||
|
||
## 重要更新
|
||
|
||
[**Release Notes**](https://github.com/taosdata/taos-connector-python/releases)
|
||
|
||
## API 参考
|
||
|
||
* [连接器-Python-Api 参考](https://docs.taosdata.com/reference/connector/python/#api-参考)
|
||
* [taos](https://docs.taosdata.com/api/taospy/taos/)
|
||
* [taosrest](https://docs.taosdata.com/api/taospy/taosrest)
|
||
|
||
更多关于 Python 连接器的详细介绍请参考[连接器-Python](https://docs.taosdata.com/reference/connector/python)
|
||
|
||
## 常见问题
|
||
|
||
欢迎[提问或报告问题](https://github.com/taosdata/taos-connector-python/issues)。
|