{"id":20578087,"url":"https://github.com/timeplus-io/proton-python-driver","last_synced_at":"2025-08-21T17:32:08.120Z","repository":{"id":196459550,"uuid":"470773731","full_name":"timeplus-io/proton-python-driver","owner":"timeplus-io","description":"Python driver for Timeplus Enterprise or Timeplus Proton","archived":false,"fork":false,"pushed_at":"2024-10-24T09:49:37.000Z","size":1541,"stargazers_count":12,"open_issues_count":17,"forks_count":4,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2024-10-25T00:29:15.026Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://timeplus.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timeplus-io.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-16T22:42:49.000Z","updated_at":"2024-10-24T06:02:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"7732ec2d-74cb-483a-a449-64d661812811","html_url":"https://github.com/timeplus-io/proton-python-driver","commit_stats":{"total_commits":438,"total_committers":48,"mean_commits":9.125,"dds":0.2168949771689498,"last_synced_commit":"0f0ee09f4994e8ea2a268ad426a53a451c69484b"},"previous_names":["timeplus-io/proton-python-driver"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timeplus-io%2Fproton-python-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timeplus-io%2Fproton-python-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timeplus-io%2Fproton-python-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timeplus-io%2Fproton-python-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timeplus-io","download_url":"https://codeload.github.com/timeplus-io/proton-python-driver/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230523761,"owners_count":18239445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T06:10:26.634Z","updated_at":"2024-12-20T02:07:01.120Z","avatar_url":"https://github.com/timeplus-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Timeplus Python Driver\n=============================\n\nIntroduction\n------------\n\n`Timeplus \u003chttps://github.com/timeplus-io/proton\u003e`_ is a unified streaming and historical data processing engine in a single binary.\n\nThis project provides python driver to interact with Timeplus Proton or Timeplus Enterprise, the code is based on https://github.com/mymarilyn/clickhouse-driver.  \n\n\nInstallation\n------------\nTimeplus Python Driver currently supports the following versions of Python: 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13.\n\nInstalling with pip\nWe recommend creating a virtual environment when installing Python dependencies. For more information on setting up a virtual environment, see the `Python documentation \u003chttps://docs.python.org/3.9/tutorial/venv.html\u003e`_.\n\n.. code-block:: shell\n\n   pip install proton-driver --extra-index-url https://d.timeplus.com/simple/\n\n\nQuick Start\n------------\n\n1. Run Timeplus Proton with docker. Make sure the port 8463 is exposed.\n\n.. code-block:: shell\n\n  docker run -d -p 8463:8463 --pull always --name proton d.timeplus.com/timeplus-io/proton:latest\n\n2. Run following python code \n\n.. code-block:: python\n\n   from proton_driver import connect\n   with connect(\"proton://default:@localhost:8463/default\") as conn:\n     with conn.cursor() as cursor:\n       cursor.execute(\"select 1\")\n       print(cursor.fetchone())\n\nabove code should return ``(1,)`` , which shows that everything is working fine now.\n\nStreaming Query\n----------------\n\n.. code-block:: python\n\n  from proton_driver import client\n\n  c = client.Client(host='127.0.0.1', port=8463)\n\n  # create a random stream if not exist\n  c.execute(\"CREATE RANDOM STREAM IF NOT EXISTS\"\n            \" devices(\"\n            \" device string default 'device'||to_string(rand()%4), \"\n            \" temperature float default rand()%1000/10\"\n            \")\")\n  # query the stream and return in a iterator\n  rows = c.execute_iter(\n      \"SELECT device, count(*), min(temperature), max(temperature) \"\n      \"FROM devices GROUP BY device\",\n  )\n  for row in rows:\n      print(row)\n\n\nthe output of the code will be something like following, as for streaming query is unbounded, you can add your flow control to terminate the loop.\n\n.. code-block:: shell\n\n  ('device0', 747, 0.0, 99.5999984741211)\n  ('device1', 723, 0.10000000149011612, 99.30000305175781)\n  ('device3', 768, 0.30000001192092896, 99.9000015258789)\n  ('device2', 762, 0.20000000298023224, 99.80000305175781)\n  ('device0', 1258, 0.0, 99.5999984741211)\n  ('device1', 1216, 0.10000000149011612, 99.69999694824219)\n  ('device3', 1276, 0.30000001192092896, 99.9000015258789)\n  ('device2', 1250, 0.20000000298023224, 99.80000305175781)\n\nInsert Data\n------------\n.. code-block:: python\n\n  from proton_driver import client\n\n  c = client.Client(host='127.0.0.1', port=8463)\n\n  # create a random stream if not exist\n  c.execute(\"INSERT INTO proton_stream (raw) VALUES\",rows) #rows is an array of arrays\n\nPandas DataFrame\n----------------\nBig fan of Pandas? We too! You can mix SQL and Pandas API together. Also you can converting query results to a variety of formats(e.g. Numpy Array, Pandas DataFrame, Polars DataFrame, Arrow Table) by DBAPI.\n\n\n.. code-block:: python\n\n   import pandas as pd\n   import time\n   \n   from proton_driver import client\n   \n   if __name__ == \"__main__\":\n       c = client.Client(host='127.0.0.1', port=8463)\n   \n       # setup the test stream\n       c.execute(\"drop stream if exists test\")\n       c.execute(\"\"\"create stream test (\n                       year int16,\n                       first_name string\n                   )\"\"\")\n       # add some data\n       df = pd.DataFrame.from_records([\n           {'year': 1994, 'first_name': 'Vova'},\n           {'year': 1995, 'first_name': 'Anja'},\n           {'year': 1996, 'first_name': 'Vasja'},\n           {'year': 1997, 'first_name': 'Petja'},\n       ])\n       c.insert_dataframe(\n           'INSERT INTO \"test\" (year, first_name) VALUES',\n           df,\n           settings=dict(use_numpy=True),\n       )\n       # or c.execute(\"INSERT INTO test(year, first_name) VALUES\", df.to_dict('records'))\n       time.sleep(3) # wait for 3 sec to make sure data available in historical store\n   \n       df = c.query_dataframe('SELECT * FROM table(test)')\n       print(df)\n       print(df.describe())\n\n       # Converting query results to a variety of formats with dbapi\n       with connect('proton://localhost') as conn:\n           with conn.cursor() as cur:\n               cur.execute('SELECT * FROM table(test)')\n               print(cur.df()) # Pandas DataFrame\n\n               cur.execute('SELECT * FROM table(test)')\n               print(cur.fetchnumpy()) # Numpy Arrays\n\n               cur.execute('SELECT * FROM table(test)')\n               print(cur.pl()) # Polars DataFrame\n\n               cur.execute('SELECT * FROM table(test)')\n               print(cur.arrow()) # Arrow Table","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimeplus-io%2Fproton-python-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimeplus-io%2Fproton-python-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimeplus-io%2Fproton-python-driver/lists"}