test: add python demo for websocket (#20209)

* test: add python demo for websocket

* fix test

* fix test

* fix test

docs/en/14-reference/03-connector/07-python.mdx

@@ -228,6 +228,16 @@ All arguments to the `connect()` function are optional keyword arguments. The fo
 - `password`: TDengine user password. The default is `taosdata`.
 - `timeout`: HTTP request timeout. Enter a value in seconds. The default is `socket._GLOBAL_DEFAULT_TIMEOUT`. Usually, no configuration is needed.
 
+</TabItem>
+
+<TabItem value="websocket" label="WebSocket connection">
+
+```python
+{{#include docs/examples/python/connect_websocket_examples.py:connect}}
+```
+
+The parameter of `connect()` is the url of TDengine, and the protocol is `taosws` or `ws`.
+
 </TabItem>
 </Tabs>
 
@@ -298,7 +308,15 @@ The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-ap
 
 For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).
 
+</TabItem>
+<TabItem value="websocket" label="WebSocket connection">
+
+```python
+{{#include docs/examples/python/connect_websocket_examples.py:basic}}
+```
 
+- `conn.execute`: can use to execute arbitrary SQL statements, and return the number of rows affected.
+- `conn.query`: can use to execute query SQL statements, and return the query results.
 
 </TabItem>
 </Tabs>
@@ -319,6 +337,13 @@ For a more detailed description of the `sql()` method, please refer to [RestClie
 {{#include docs/examples/python/conn_rest_pandas.py}}
 ```
 
+</TabItem>
+<TabItem value="websocket" label="WebSocket connection">
+
+```python
+{{#include docs/examples/python/conn_websocket_pandas.py}}
+```
+
 </TabItem>
 </Tabs>
 

docs/examples/python/conn_websocket_pandas.py

+import pandas
+from sqlalchemy import create_engine, text
+import taos
+
+taos_conn = taos.connect()
+taos_conn.execute('drop database if exists power')
+taos_conn.execute('create database if not exists power')
+taos_conn.execute("use power")
+taos_conn.execute(
+    "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)")
+# insert data
+taos_conn.execute("""INSERT INTO power.d1001 USING power.meters TAGS('California.SanFrancisco', 2) 
+VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) 
+('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
+    power.d1002 USING power.meters TAGS('California.SanFrancisco', 3) 
+    VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
+    power.d1003 USING power.meters TAGS('California.LosAngeles', 2) 
+    VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
+    power.d1004 USING power.meters TAGS('California.LosAngeles', 3) 
+    VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)""")
+
+engine = create_engine("taosws://root:taosdata@localhost:6041")
+conn = engine.connect()
+df: pandas.DataFrame = pandas.read_sql(text("SELECT * FROM power.meters"), conn)
+conn.close()
+
+# print index
+print(df.index)
+# print data type  of element in ts column
+print(type(df.ts[0]))
+print(df.head(3))
+
+# output:
+# RangeIndex(start=0, stop=8, step=1)
+# <class 'pandas._libs.tslibs.timestamps.Timestamp'>
+#                        ts  current  ...                 location  groupid
+# 0 2018-10-03 14:38:05.000     10.3  ...  California.SanFrancisco        2
+# 1 2018-10-03 14:38:15.000     12.6  ...  California.SanFrancisco        2
+# 2 2018-10-03 14:38:16.800     12.3  ...  California.SanFrancisco        2

docs/examples/python/connect_websocket_examples.py

+# ANCHOR: connect
+import taosws
+
+conn = taosws.connect("taosws://root:taosdata@localhost:6041")
+# ANCHOR_END: connect
+
+# ANCHOR: basic
+conn.execute("drop database if exists connwspy")
+conn.execute("create database if not exists connwspy")
+conn.execute("use connwspy")
+conn.execute("create table if not exists stb (ts timestamp, c1 int) tags (t1 int)")
+conn.execute("create table if not exists tb1 using stb tags (1)")
+conn.execute("insert into tb1 values (now, 1)")
+conn.execute("insert into tb1 values (now, 2)")
+conn.execute("insert into tb1 values (now, 3)")
+
+r = conn.execute("select * from stb")
+result = conn.query("select * from stb")
+num_of_fields = result.field_count
+print(num_of_fields)
+
+for row in result:
+    print(row)
+
+# output:
+# 3
+# ('2023-02-28 15:56:13.329 +08:00', 1, 1)
+# ('2023-02-28 15:56:13.333 +08:00', 2, 1)
+# ('2023-02-28 15:56:13.337 +08:00', 3, 1)

docs/zh/08-connector/30-python.mdx

@@ -229,6 +229,16 @@ curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
 - `password`： TDengine 用户密码。默认是 taosdata。
 - `timeout`: HTTP 请求超时时间。单位为秒。默认为 `socket._GLOBAL_DEFAULT_TIMEOUT`。 一般无需配置。
 
+</TabItem>
+
+<TabItem value="websocket" label="WebSocket 连接">
+
+```python
+{{#include docs/examples/python/connect_websocket_examples.py:connect}}
+```
+
+`connect()` 函数参数为连接 url，协议为 `taosws` 或 `ws`
+
 </TabItem>
 </Tabs>
 
@@ -298,8 +308,15 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
 ```
 
 对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
+</TabItem>
+<TabItem value="websocket" label="WebSocket 连接">
 
+```python
+{{#include docs/examples/python/connect_websocket_examples.py:basic}}
+```
 
+- `conn.execute`: 用来执行任意 SQL 语句，返回影响的行数
+- `conn.query`: 用来执行查询 SQL 语句，返回查询结果
 
 </TabItem>
 </Tabs>
@@ -320,6 +337,13 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
 {{#include docs/examples/python/conn_rest_pandas.py}}
 ```
 
+</TabItem>
+<TabItem value="websocket" label="WebSocket 连接">
+
+```python
+{{#include docs/examples/python/conn_websocket_pandas.py}}
+```
+
 </TabItem>
 </Tabs>
 
@@ -335,15 +359,17 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
 ```python
 {{#include docs/examples/python/tmq_example.py}}
 ```
+
 </TabItem>
 
-<TabItem value="rest" label="websocket 连接">
+<TabItem value="websocket" label="WebSocket 连接">
 
 除了原生的连接方式，Python 连接器还支持通过 websocket 订阅 TMQ 数据。
 
 ```python
 {{#include docs/examples/python/tmq_websocket_example.py}}
 ```
+
 </TabItem>
 </Tabs>
 
@@ -366,7 +392,7 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
 ```python
 {{#include docs/examples/python/handle_exception.py}}
 ```
-
+``
 ### 关于纳秒 (nanosecond)
 
 由于目前 Python 对 nanosecond 支持的不完善(见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。

tests/docs-examples-test/python.sh

@@ -85,3 +85,9 @@ python3 fast_write_example.py
 pip3 install kafka-python
 python3 kafka_example_consumer.py
 
+# 21
+pip3 install taos-ws-py
+python3 conn_websocket_pandas.py
+
+# 22
+python3 connect_websocket_examples.py