From 8f1d2dbfd00b0c35b6cd8613fb1356a55a749da6 Mon Sep 17 00:00:00 2001 From: dingbo Date: Tue, 7 Jun 2022 18:15:15 +0800 Subject: [PATCH] docs: add python reference --- docs-en/05-develop/01-connect/01-python.md | 2 +- docs-en/09-connector/java.md | 5 +- docs-en/09-connector/python.md | 80 ++++++++++++++++++- docs-examples/python/connect_cloud_example.py | 45 +++++++++++ .../python/rest_client_cloud_example.py | 12 +++ 5 files changed, 141 insertions(+), 3 deletions(-) create mode 100644 docs-examples/python/connect_cloud_example.py create mode 100644 docs-examples/python/rest_client_cloud_example.py diff --git a/docs-en/05-develop/01-connect/01-python.md b/docs-en/05-develop/01-connect/01-python.md index d6e59c9e3b..a67a35ba6a 100644 --- a/docs-en/05-develop/01-connect/01-python.md +++ b/docs-en/05-develop/01-connect/01-python.md @@ -41,4 +41,4 @@ token = os.environ["TDENGINE_CLOUD_TOKEN"] conn = taosrest.connect(url=url, token=token) ``` -The client connection is then established. +The client connection is then established. For how to write data and query data, please refer to [basic usage](/connector/python#basic-usage). diff --git a/docs-en/09-connector/java.md b/docs-en/09-connector/java.md index e62d5f08d1..eb6b667143 100644 --- a/docs-en/09-connector/java.md +++ b/docs-en/09-connector/java.md @@ -1 +1,4 @@ -# Java Connector \ No newline at end of file +--- +sidebar_label: Java +title: TDengine Java Connector +--- \ No newline at end of file diff --git a/docs-en/09-connector/python.md b/docs-en/09-connector/python.md index 1afe0af62b..16e8e1d85d 100644 --- a/docs-en/09-connector/python.md +++ b/docs-en/09-connector/python.md @@ -1 +1,79 @@ -# Python Connector +--- +sidebar_label: Python +title: TDengine Python Connector +--- + + +`taospy` is the official Python connector for TDengine. `taospy` provides a rich set of APIs that makes it easy for Python applications to access TDengine. `taospy` wraps both the [native interface](/reference/connector/cpp) and [REST interface](/reference/rest-api) of TDengine, which correspond to the `taos` and `taosrest` modules of the `taospy` package, respectively. But for cloud users using `taosrest` is enough. +In addition to wrapping the native and REST interfaces, `taospy` also provides a set of programming interfaces that conforms to the [Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/). It is easy to integrate `taospy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). + +The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python). + +## Installation + +### Preparation + +1. Install Python. Python >= 3.6 is recommended. If Python is not available on your system, refer to the [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) to install it. +2. Install [pip](https://pypi.org/project/pip/). In most cases, the Python installer comes with the pip utility. If not, please refer to [pip documentation](https://pip.pypa.io/en/stable/installation/) to install it. + +### Install via pip + +``` +pip3 install taospy>=2.3.3 +``` + +### Installation verification + +Verifying that the `taosrest` module can be imported successfully. This can be done in the Python Interactive Shell by typing. + +```python +import taosrest +``` + +## Establish connection + +```python +{{#include docs-examples/python/connect_cloud_example.py:connect}} +``` + +All arguments to the `connect()` function are optional keyword arguments. The following are the connection parameters specified. + +- `url`： The cloud URL. +- `token`: The cloud token. +- `timeout`: HTTP request timeout in seconds. The default is `socket._GLOBAL_DEFAULT_TIMEOUT`. Usually, no configuration is needed. + +## Sample program + +### Use of TaosRestCursor class + +The ``TaosRestCursor`` class is an implementation of the PEP249 Cursor interface. + +```python title="Use of TaosRestCursor" +{{#include docs-examples/python/connect_cloud_example.py:basic}} +``` +- `cursor.execute` : Used to execute arbitrary SQL statements. +- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set. +- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information. + +### Use of the RestClient class + +The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result. + +```python title="Use of RestClient" +{{#include docs-examples/python/rest_client_cloud_example.py}} +``` + +For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html). + +## Important Update + +| Connector version | Important Update | Release date | +| ----------------- | ----------------------------------------- | ------------ | +| 2.3.3 | support connect to TDengine Cloud Service | 2022-06-06 | + +[**Release Notes**] (https://github.com/taosdata/taos-connector-python/releases) + +## API Reference + +- [taos](https://docs.taosdata.com/api/taospy/taos/) +- [taosrest](https://docs.taosdata.com/api/taospy/taosrest) diff --git a/docs-examples/python/connect_cloud_example.py b/docs-examples/python/connect_cloud_example.py new file mode 100644 index 0000000000..493ff98eaf --- /dev/null +++ b/docs-examples/python/connect_cloud_example.py @@ -0,0 +1,45 @@ +# ANCHOR: connect +import taosrest +import os + +url = os.environ["TDENGINE_CLOUD_URL"] +token = os.environ["TDENGINE_CLOUD_TOKEN"] + +conn = taosrest.connect(url=url, token=token) + +# ANCHOR_END: connect +# ANCHOR: basic +from taosrest import TaosRestCursor +# create STable +cursor: TaosRestCursor = conn.cursor() +cursor.execute("DROP DATABASE IF EXISTS power") +cursor.execute("CREATE DATABASE power") +cursor.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") + +# insert data +cursor.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)""") +print("inserted row count:", cursor.rowcount) + +# query data +cursor.execute("SELECT * FROM power.meters LIMIT 3") +# get total rows +print("queried row count:", cursor.rowcount) +# get column names from cursor +column_names = [meta[0] for meta in cursor.description] +# get rows +data: list[tuple] = cursor.fetchall() +print(column_names) +for row in data: + print(row) + +# output: +# inserted row count: 8 +# queried row count: 3 +# ['ts', 'current', 'voltage', 'phase', 'location', 'groupid'] +# [datetime.datetime(2018, 10, 3, 14, 38, 5, 500000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 11.8, 221, 0.28, 'california.losangeles', 2] +# [datetime.datetime(2018, 10, 3, 14, 38, 16, 600000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 13.4, 223, 0.29, 'california.losangeles', 2] +# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.8, 223, 0.29, 'california.losangeles', 3] +# ANCHOR_END: basic diff --git a/docs-examples/python/rest_client_cloud_example.py b/docs-examples/python/rest_client_cloud_example.py new file mode 100644 index 0000000000..83a2b9ff4d --- /dev/null +++ b/docs-examples/python/rest_client_cloud_example.py @@ -0,0 +1,12 @@ +import os +from taosrest import RestClient + +url = os.environ["TDENGINE_CLOUD_URL"] +token = os.environ["TDENGINE_CLOUD_TOKEN"] + +client = RestClient(url, token) +res: dict = client.sql("SELECT ts, current FROM power.meters LIMIT 1") +print(res) + +# output: +# {'status': 'succ', 'head': ['ts', 'current'], 'column_meta': [['ts', 9, 8], ['current', 6, 4]], 'data': [[datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3]], 'rows': 1} -- GitLab