python.mdx

---
sidebar_position: 3
sidebar_label: Python
title: Python Connector
description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：tasos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas"
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

`taospy` 是 TDengine 的官方 Python 连接器。`taospy` 提供了丰富的 API， 使得 python 应用可以很方便地使用 TDengine。`tasopy` 对 TDengine 的[原生接口](/reference/connector/cpp)和 [REST 接口](/reference/rest-api)都进行了封装， 分别对应 `tasopy` 包的 `taos` 模块 和 `taosrest` 模块。
除了对原生接口和 REST 接口的封装，`taospy` 还提供了符合 [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)。

## 支持的平台

- 原生连接[^1][支持的平台](/reference/connector/#支持的平台)和 TDengine 客户端支持的平台一致。
- REST 连接[^2]支持所有能运行 Python 的平台。

## 版本选择

无论使用什么版本的 TDengine 都建议使用最新版本的 `tasopy`。

## 支持的功能

- 原生连接[^1]支持 TDeingine 的所有核心功能， 包括： 连接管理、查询[^3]、参数绑定、订阅、无模式写入（Schemaless）。
- REST 连接[^2]目前仅支持查询功能[^3]。

## 安装

### 准备

1. 安装 Python。建议使用 Python >= 3.6。如果系统上还没有 Python 可参考 [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) 安装。
2. 安装 [pip](https://pypi.org/project/pip/)。大部分情况下 Python 的安装包都自带了 pip 工具， 如果没有请参考 [pip docuemntation](https://pip.pypa.io/en/stable/installation/) 安装。
3. 如果使用原生连接，还需[安装客户端驱动](../#安装客户端驱动)。客户端软件包含了 TDengine 客户端动态链接库(libtaos.so 或 taos.dll) 和 TDengine CLI。

### 使用 pip 安装

#### 卸载旧版本

如果以前安装过旧版本的 Python 连接器, 请提前卸载。

```
pip3 uninstall taos taospy
```

:::note
较早的 TDengine 客户端软件包含了 Python 连接器。如果从客户端软件的安装目录安装了 Python 连接器，那么对应的 Python 包名是 `taos`。 所以上述卸载命令包含了 `taos`， 不存在也没关系。

:::

#### 安装 `tasopy`

<Tabs>
<TabItem label="从 PyPI 安装" value="pypi">

安装最新版本

```
pip3 install taospy
```

也可以指定某个特定版本安装。

```
pip3 install taospy==2.3.0
```

</TabItem>
<TabItem label="从 GitHub 安装" value="github">

```
pip3 install git+https://github.com/taosdata/taos-connector-python.git
```

</TabItem>
</Tabs>

### 安装验证

<Tabs groupId="connect" default="native">
<TabItem value="native" label="原生连接">

对于原生连接，需要验证客户端驱动和 Python 连接器本身是否都正确安装。如果能成功导入 `taos` 模块，则说明已经正确安装了客户端驱动和 Python 连接器。可在 Python 交互式 Shell 中输入：

```python
import taos
```

</TabItem>
<TabItem  value="rest" label="REST 连接">

对于 REST 连接，只需验证是否能成功导入 `taosrest` 模块。可在 Python 交互式 Shell 中输入：

```python
import taosrest
```

</TabItem>
</Tabs>

:::tip
如果系统上有多个版本的 Python，则可能有多个 `pip` 命令。要确保使用的 `pip` 命令路径是正确的。上面我们用 `pip3` 命令安装，排除了使用 Python 2.x 版本对应的 `pip` 的可能性。但是如果系统上有多个 Python 3.x 版本，仍需检查安装路径是否正确。最简单的验证方式是，在命令再次输入 `pip3 install taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Windows 上：

```
C:\> pip3 install taospy
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Requirement already satisfied: taospy in c:\users\username\appdata\local\programs\python\python310\lib\site-packages (2.3.0)
```

:::

## 建立连接

### 连通性测试

在用连接器建立连接之前，建议先测试本地 TDengine CLI 到 TDengine 集群的连通性。

<Tabs>
<TabItem value="native" label="原生连接">

请确保 TDengine 集群已经启动， 且集群中机器的 FQDN （如果启动的是单机版，FQDN 默认为 hostname）在本机能够解析, 可用 ping 命令进行测试：

```
ping <FQDN>
```

然后测试用 TDengine CLI 能否正常连接集群：

```
taos -h <FQDN> -p <PORT>
```

上面的 FQDN 可以为集群中任意一个 dnode 的 FQDN， PORT 为这个 dnode 对应的 serverPort。

</TabItem>
<TabItem value="rest" label="REST 连接" groupId="connect">

对于 REST 连接， 除了确保集群已经启动，还要确保 taosAdapter 组件已经启动。可以使用如下 curl 命令测试：

```
curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
```

上面的 FQDN 为运行 taosAdapter 的机器的 FQDN， PORT 为 taosAdapter 配置的监听端口， 默认为 6041。
如果测试成功，会输出服务器版本信息，比如：

```json
{
  "status": "succ",
  "head": ["server_version()"],
  "column_meta": [["server_version()", 8, 8]],
  "data": [["2.4.0.16"]],
  "rows": 1
}
```

</TabItem>
</Tabs>

### 使用连接器建立连接

以下示例代码假设 TDengine 安装在本机， 且 FQDN 和 serverPort 都使用了默认配置。

<Tabs>
<TabItem value="native" label="原生连接" groupId="connect">

```python
{{#include docs-examples/python/connect_native_reference.py}}
```

`connect` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明：

- `host` ： 要连接的节点的 FQDN。 没有默认值。如果不同提供此参数，则会连接客户端配置文件中的 firstEP。
- `user` ：TDengine 用户名。 默认值是 root。
- `password` ： TDengine 用户密码。 默认值是 taosdata。
- `port` ： 要连接的数据节点的起始端口，即 serverPort 配置。默认值是 6030。只有在提供了 host 参数的时候，这个参数才生效。
- `config` ： 客户端配置文件路径。 在 Windows 系统上默认是 `C:\TDengine\cfg`。 在 Linux 系统上默认是 `/etc/taos/`。
- `timezone` ： 查询结果中 TIMESTAMP 类型的数据，转换为 python 的 datetime 对象时使用的时区。默认为本地时区。

:::warning
`config` 和 `timezone` 都是进程级别的配置。建议一个进程建立的所有连接都使用相同的参数值。否则可能产生无法预知的错误。
:::

:::tip
`connect` 函数返回 `taos.TaosConnection` 实例。 在客户端多线程的场景下，推荐每个线程申请一个独立的连接实例，而不建议多线程共享一个连接。

:::

</TabItem>
<TabItem value="rest" label="REST 连接">

```python
{{#include docs-examples/python/connect_rest_examples.py:connect}}
```

`connect` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明：

- `host`： 要连接的主机。默认是 localhost。
- `user`： TDenigne 用户名。默认是 root。
- `password`： TDeingine 用户密码。默认是 taosdata。
- `port`: taosAdapter REST 服务监听端口。默认是 6041.
- `timeout`: HTTP 请求超时时间。单位为秒。默认为 `socket._GLOBAL_DEFAULT_TIMEOUT`。 一般无需配置。

:::note

:::

</TabItem>
</Tabs>

## 示例程序

### 基本使用

<Tabs default="native" groupId="connect">
<TabItem value="native" label="原生连接">

##### TaosConnection 类的使用

`TaosConnection` 类既包含对 PEP249 Connection 接口的实现(如：`cursor`方法和 `close` 方法)，也包含很多扩展功能（如： `execute`、 `query`、`schemaless_insert` 和 `subscribe` 方法。

```python title="execute 方法"
{{#include docs-examples/python/connection_usage_native_reference.py:insert}}
```

```python title="query 方法"
{{#include docs-examples/python/connection_usage_native_reference.py:query}}
```

:::tip
查询结果只能获取一次。比如上面的示例中 `featch_all` 和 `fetch_all_into_dict` 只能用一个。重复获取得到的结果为空列表。
:::

##### TaosResult 类的使用

上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `featch_all` 和 `fetch_all_into_dict`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。

```python title="blocks_iter 方法"
{{#include docs-examples/python/result_set_examples.py}}
```
##### TaosCursor 类的使用

`TaosConnection` 类和 `TaosResult` 类已经实现了原生接口的所有功能。如果你对 PEP249 规范中的接口比较熟悉也可以使用 `TaosCursor` 类提供的方法。

```python title="TaosCursor 的使用"
{{#include docs-examples/python/cursor_usage_native_reference.py}}
```

:::note
TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线程的场景下，这个游标实例必须保持线程独享，不能跨线程共享使用，否则会导致返回结果出现错误。

:::

</TabItem>
<TabItem value="rest" label="REST 连接">

#####  TaosRestCursor 类的使用

`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。

```python title="TaosRestCursor 的使用"
{{#include docs-examples/python/connect_rest_examples.py:basic}}
```
- `cursor.execute` ： 用来执行任意 SQL 语句。
- `cursor.rowcount`： 对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。
- `cursor.description` ： 返回字段的描述信息。关于描述信息的具体格式请参考[TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html)。

##### RestClient 类的使用

`RestClient` 类是对于 [REST API](/reference/rest-api) 的直接封装。它只包含一个 `sql()` 方法用于执行任意 SQL 语句， 并返回执行结果。

```python title="RestClient 的使用"
{{#include docs-examples/python/rest_client_example.py}}
```

对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。



</TabItem>
</Tabs>

### 与 pandas 一起使用

<Tabs default="native" groupId="connect">
<TabItem value="native" label="原生连接">

```python
{{#include docs-examples/python/conn_native_pandas.py}}
```

</TabItem>
<TabItem value="rest" label="REST 连接">

```python
{{#include docs-examples/python/conn_rest_pandas.py}}
```

</TabItem>
</Tabs>

### 其它示例程序

| 示例程序链接                                                                                                  | 示例程序内容            |
| ------------------------------------------------------------------------------------------------------------- | ----------------------- |
| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py)           | 参数绑定， 一次绑定多行 |
| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py)               | 参数绑定，一次绑定一行  |
| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py)       | InfluxDB 行协议写入     |
| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py)               | 使用 JSON 类型的标签    |
| [subscribe-async.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-async.py) | 异步订阅                |
| [subscribe-sync.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-sync.py)   | 同步订阅                |

## 其它说明 

### 异常处理

所有数据库操作如果出现异常，都会直接抛出来。由应用程序负责异常处理。比如：

```python
{{#include docs-examples/python/handle_exception.py}}
```

### 关于纳秒 (nanosecond)

由于目前 Python 对 nanosecond 支持的不完善(见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。

1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/


## 常见问题

欢迎[提问或报告问题](https://github.com/taosdata/taos-connector-python/issues)。

## 重要更新

| 连接器版本 | 重要更新                                                                          | 发布日期   |
| ---------- | --------------------------------------------------------------------------------- | ---------- |
| 2.3.0      | 1. support TDengine REST API <br/> 2. remove support for Python version below 3.6 | 2022-04-27 |
| 2.2.5      | support timezone option when connect                                              | 2022-04-13 |
| 2.2.2      | support sqlalchemy dialect plugin                                                 | 2022-03-28 |


[**Release Notes**](https://github.com/taosdata/taos-connector-python/releases)

## API 参考

- [taos](https://docs.taosdata.com/api/taospy/taos/)
- [taosrest](https://docs.taosdata.com/api/taospy/taosrest)

[^1]: 原生连接指使用客户端驱动提供的原生 API 直接与服务端建立的连接。当使用 taos 模块时，cnnect 函数返回的连接就是原生连接。
[^2]: REST 连接指使用 taosAdapter 提供的 REST API 与服务端建立的连接。当使用 taosrest 模块时， connect 函数返回的连接就是 REST 连接。
[^3]: 查询功能指执行 SQL 功能，不仅指查询数据。