---
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 的平台。

## 版本选择

建议使用 Python >= 3.6。无论使用什么版本的 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.2.5
```

</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 版本，仍需注意验证。最简单的验证方式是， 查看 `taospy` 最终的安装位置是否正确。在命令再次输入 `pip3 isntall taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Widnows 上：

```
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.2.5)
```

:::

## 建立连接

### 连通性测试

在用连接器建立连接之前，建议先做本地到 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 <br/> 如果不同提供此参数，则会连接客户端配置文件中的 firstEP                   | 无                                                         | 本次连接 |
| user     | 用户名                                                                                             | root                                                       | 本次连接 |
| passowrd | 密码                                                                                               | taosdata                                                   | 本次连接 |
| database | 默认使用的数据库，<br/> 如果有值那么这个数据库必须存在                                             | 无                                                         | 本次连接 |
| port     | 要连接的数据节点的起始端口，即 serverPort 配置。<br/> 只有在提供了 host 参数的时候，这个参数才生效 | 6030                                                       | 本次连接 |
| config   | 客户端配置文件路径                                                                                 | 1. Windows: `C:\TDengine\cfg` <br/> 2. Linux: `/etc/taos/` | 本进程   |
| timezone | 客户端时区                                                                                         | 客户端配置文件中 timezone                                  | 本进程   |

:::warning
当参数的作为范围是进程级别时，只有建立第一个连接时提供的参数生效。也就是说： 同一个进程的两个连接，必须使用相同的客户端配置。但这并不妨碍同一进程连接两个不同的集群，因为 host 参数是连接级别的。
:::

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

:::

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

</TabItem>
</Tabs>

## 开发指南

### 基本使用

### 与 pandas 一起使用

### 其它示例程序

| 示例程序链接                                                                                                  | 示例程序内容            |
| ------------------------------------------------------------------------------------------------------------- | ----------------------- |
| [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)   | 同步订阅                |

## 其它说明

### 关于纳秒 (nanosecond) 在 Python 连接器中的说明

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

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

### 关于 TaosCursor 类的说明

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

## 常见问题


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


## 重要更新

| 连接器版本 | 主要更新 | 发布日期 |
| ---------- | -------- | -------- |
| 2.3.0      |          |          |
| 2.2.5      |          |          |
| 2.2.4      |          |          |
| 2.2.3      |          |          |

要了解更多，请参考：[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 功能，不仅指查询数据。