SiriDB - Connector
==================
The SiriDB Connector is a self-contained Python driver for communicating with SiriDB servers.
This manual describes how to install and configure SiriDB Connector for Python 3, and how to use it to develop database applications.
---------------------------------------
* [Installation](#installation)
* [Quick usage](#quick-usage)
* [SiriDBClient](#siridbclient)
* [connect](#siridbclientconnect)
* [insert](#siridbclientinsert)
* [query](#siridbclientquery)
* [close](#siridbclientclose)
* [Exception codes](#exception-codes)
* [Version info](#version-info)
---------------------------------------
## Installation
------------
From PyPI (recommended)
```
pip install siridb-connector
```
From source code
```
python setup.py install
```
## Quick usage
-------
```python
import asyncio
import time
import random
from siridb.connector import SiriDBClient
async def example(siri):
# Start connecting to SiriDB.
# .connect() returns a list of all connections referring to the supplied
# hostlist. The list can contain exceptions in case a connection could not
# be made.
await siri.connect()
try:
# insert
ts = int(time.time())
value = random.random()
await siri.insert({'some_measurement': [[ts, value]]})
# query
resp = await siri.query('select * from "some_measurement"')
print(resp)
finally:
# Close all SiriDB connections.
siri.close()
siri = SiriDBClient(
username='iris',
password='siri',
dbname='dbtest',
hostlist=[('localhost', 9000)], # Multiple connections are supported
keepalive=True)
asyncio.run(example(siri))
```
## SiriDBClient
Create a new SiriDB Client. This creates a new client but `.connect()` must be used to connect.
```python
siri = SiriDBClient(
username=<username>,
password=<password>,
dbname=<dbname>,
hostlist=[(<host>, <port>, {weight: 1}, {backup: False})],
loop=None,
keepalive=True,
timeout=10,
inactive_time=30,
max_wait_retry=90)
```
Arguments:
* __username__: User with permissions to use the database.
* __password__: Password for the given username.
* __dbname__: Name of the database.
* __hostlist__: List with SiriDB servers (all servers or a subset of
servers can be in this list).
*Example:*
```python
hostlist=[ ('server1.local', 9000, {'weight': 3}),
('server2.local', 9001),
('backup1.local', 9002, {'backup': True}) ]
```
Each server should at least have a hostname and port
number. Optionally you can provide a dictionary with
extra options.
Available Options:
- __weight__ : Should be a value between 1 and 9. A higher
value gives the server more weight so it will
be more likely chosen. (default 1)
- __backup__ : Should be either True or False. When True the
server will be marked as backup server and
will only be chosen if no other server is
available. (default: False)
Keyword arguments:
* __loop__: Asyncio loop. When 'None' the default event loop will be used.
* __keepalive__: When 'True' keep-alive packages are send every 45 seconds.
* __timeout__: Maximum time to complete a process, otherwise it will be cancelled.
* __inactive_time__: When a server is temporary unavailable, for
example the server could be paused, we mark the server as inactive after x seconds.
* __max_wait_retry__: When the reconnect loop starts, we try to reconnect in 1 second, then 2 seconds, 4, 8 and so on until max_wait_retry is reached and then use this value to retry again.
******************************************************************************
### SiriDBClient.connect
Start connecting to SiriDB. `.connect()` returns a list of all connections referring to the supplied hostlist. The list can contain exceptions in case a connection could not be made.
Optionally the keyword argument `timeout` can be set. This will constrain the search time for a connection. Exceeding the timeout will raise an `.TimeoutError`.
```python
siri.connect(timeout=None)
```
### SiriDBClient.insert
Insert time series data into SiriDB. Requires a 'dictionary' with at least one series.
Optionally the `timeout` can be adjusted (default: 300).
```python
siri.insert(data, timeout=300)
```
### SiriDBClient.query
Query data out of the database. Requires a string containing the query. More about the query language can be found [here](https://siridb.net/documentation/). The documentation about the query language will inform you about a number of useful aggregation and filter functions, different ways of visualizing and grouping the requested data, and how to make changes to the set up of the database. Optionally a `time_precision` (`SECOND`, `MICROSECOND`, `MILLISECOND`, `NANOSECOND`) can be set. The default `None` sets the precision to seconds. Futhermore the `timeout` can be adjusted (default: 60).
```python
from siridb.connector import (SECOND,
MICROSECOND,
MILLISECOND,
NANOSECOND)
siri.query(query, time_precision=None, timeout=60)
```
### SiriDBClient.close
Close the connection.
```python
siri.close()
```
Check if the connection is closed.
```python
siri.is_closed
```
## Exception codes
The following exceptions can be returned:
- `AuthenticationError`:
*Raised when credentials are invalid or insufficient.*
- `IndexError`:
*Raised when the database does not exist (anymore).*
- `InsertError` (can only be raised when using the `.insert()` method):
*Make sure the data is correct because this only happens when SiriDB could not process the request.*
- `OverflowError` (can only be raised when using the `.insert()` method):
*Raised when integer values cannot not be packed due to an overflow error (integer values should be signed and not more than 63 bits).*
- `PoolError`:
*SiriDB has no online server for at least one required pool. Try again later after some reasonable delay.*
- `QueryError` (can only be raised when using the `.query()` method):
*Make sure the query is correct because this only happens when SiriDB could not process the query. Consult the [documentation](https://siridb.net/documentation/#help_select) about the query language can be found.*
- `RuntimeError`:
*Raised when a general error message is received. This should no happen unless a new bug is discovered.*
- `ServerError`:
*Raised when a server could not perform the request, you could try another server if one is available. Consult the [documentation](https://siridb.net/documentation/#help_list_servers) how to get additional status information about the servers.*
- `TimeoutError`:
*Raised when a process lasts longer than the `timeout` period*
- `TypeError`:
*Raised when an unknown package is received (might be caused by running a different SiriDB version).*
- `UserAuthError`:
*The user as no rights to perform the insert or query. Consult the [documentation](https://siridb.net/documentation/#help_access) how to change the access rights.*
Raw data
{
"_id": null,
"home_page": "https://github.com/SiriDB/siridb-connector",
"name": "siridb-connector",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "siridb, connector, database, client",
"author": "Jeroen van der Heijden",
"author_email": "jeroen@cesbit.com",
"download_url": "https://files.pythonhosted.org/packages/01/32/b532ca8ad3116dd548bc91e6f19276d939919c97a97159063ef5f4972e92/siridb-connector-2.1.6.tar.gz",
"platform": null,
"description": "SiriDB - Connector\n==================\n\nThe SiriDB Connector is a self-contained Python driver for communicating with SiriDB servers.\nThis manual describes how to install and configure SiriDB Connector for Python 3, and how to use it to develop database applications.\n\n\n---------------------------------------\n * [Installation](#installation)\n * [Quick usage](#quick-usage)\n * [SiriDBClient](#siridbclient)\n * [connect](#siridbclientconnect)\n * [insert](#siridbclientinsert)\n * [query](#siridbclientquery)\n * [close](#siridbclientclose)\n * [Exception codes](#exception-codes)\n * [Version info](#version-info)\n\n---------------------------------------\n\n## Installation\n------------\n\nFrom PyPI (recommended)\n\n```\npip install siridb-connector\n```\n\nFrom source code\n\n```\npython setup.py install\n```\n\n\n## Quick usage\n-------\n\n```python\nimport asyncio\nimport time\nimport random\nfrom siridb.connector import SiriDBClient\n\nasync def example(siri):\n # Start connecting to SiriDB.\n # .connect() returns a list of all connections referring to the supplied\n # hostlist. The list can contain exceptions in case a connection could not\n # be made.\n await siri.connect()\n\n try:\n # insert\n ts = int(time.time())\n value = random.random()\n await siri.insert({'some_measurement': [[ts, value]]})\n\n # query\n resp = await siri.query('select * from \"some_measurement\"')\n print(resp)\n\n finally:\n # Close all SiriDB connections.\n siri.close()\n\n\nsiri = SiriDBClient(\n username='iris',\n password='siri',\n dbname='dbtest',\n hostlist=[('localhost', 9000)], # Multiple connections are supported\n keepalive=True)\n\nasyncio.run(example(siri))\n```\n\n\n## SiriDBClient\nCreate a new SiriDB Client. This creates a new client but `.connect()` must be used to connect.\n\n```python\nsiri = SiriDBClient(\n username=<username>,\n password=<password>,\n dbname=<dbname>,\n hostlist=[(<host>, <port>, {weight: 1}, {backup: False})],\n loop=None,\n keepalive=True,\n timeout=10,\n inactive_time=30,\n max_wait_retry=90)\n```\n\nArguments:\n* __username__: User with permissions to use the database.\n* __password__: Password for the given username.\n* __dbname__: Name of the database.\n* __hostlist__: List with SiriDB servers (all servers or a subset of\nservers can be in this list).\n\n\n *Example:*\n ```python\n hostlist=[ ('server1.local', 9000, {'weight': 3}),\n ('server2.local', 9001),\n ('backup1.local', 9002, {'backup': True}) ]\n ```\n Each server should at least have a hostname and port\n number. Optionally you can provide a dictionary with\n extra options.\n\n Available Options:\n - __weight__ : Should be a value between 1 and 9. A higher\n value gives the server more weight so it will\n be more likely chosen. (default 1)\n - __backup__ : Should be either True or False. When True the\n server will be marked as backup server and\n will only be chosen if no other server is\n available. (default: False)\n\n\nKeyword arguments:\n* __loop__: Asyncio loop. When 'None' the default event loop will be used.\n* __keepalive__: When 'True' keep-alive packages are send every 45 seconds.\n* __timeout__: Maximum time to complete a process, otherwise it will be cancelled.\n* __inactive_time__: When a server is temporary unavailable, for\nexample the server could be paused, we mark the server as inactive after x seconds.\n* __max_wait_retry__: When the reconnect loop starts, we try to reconnect in 1 second, then 2 seconds, 4, 8 and so on until max_wait_retry is reached and then use this value to retry again.\n******************************************************************************\n\n### SiriDBClient.connect\n\nStart connecting to SiriDB. `.connect()` returns a list of all connections referring to the supplied hostlist. The list can contain exceptions in case a connection could not be made.\n\nOptionally the keyword argument `timeout` can be set. This will constrain the search time for a connection. Exceeding the timeout will raise an `.TimeoutError`.\n\n```python\nsiri.connect(timeout=None)\n```\n\n### SiriDBClient.insert\n\nInsert time series data into SiriDB. Requires a 'dictionary' with at least one series.\nOptionally the `timeout` can be adjusted (default: 300).\n\n```python\nsiri.insert(data, timeout=300)\n```\n\n### SiriDBClient.query\n\nQuery data out of the database. Requires a string containing the query. More about the query language can be found [here](https://siridb.net/documentation/). The documentation about the query language will inform you about a number of useful aggregation and filter functions, different ways of visualizing and grouping the requested data, and how to make changes to the set up of the database. Optionally a `time_precision` (`SECOND`, `MICROSECOND`, `MILLISECOND`, `NANOSECOND`) can be set. The default `None` sets the precision to seconds. Futhermore the `timeout` can be adjusted (default: 60).\n\n```python\nfrom siridb.connector import (SECOND,\n MICROSECOND,\n MILLISECOND,\n NANOSECOND)\n\nsiri.query(query, time_precision=None, timeout=60)\n```\n\n### SiriDBClient.close\n\nClose the connection.\n\n```python\nsiri.close()\n```\n\nCheck if the connection is closed.\n\n```python\nsiri.is_closed\n```\n\n## Exception codes\n\nThe following exceptions can be returned:\n\n- `AuthenticationError`:\n *Raised when credentials are invalid or insufficient.*\n- `IndexError`:\n*Raised when the database does not exist (anymore).*\n- `InsertError` (can only be raised when using the `.insert()` method):\n *Make sure the data is correct because this only happens when SiriDB could not process the request.*\n- `OverflowError` (can only be raised when using the `.insert()` method):\n *Raised when integer values cannot not be packed due to an overflow error (integer values should be signed and not more than 63 bits).*\n- `PoolError`:\n *SiriDB has no online server for at least one required pool. Try again later after some reasonable delay.*\n- `QueryError` (can only be raised when using the `.query()` method):\n *Make sure the query is correct because this only happens when SiriDB could not process the query. Consult the [documentation](https://siridb.net/documentation/#help_select) about the query language can be found.*\n- `RuntimeError`:\n *Raised when a general error message is received. This should no happen unless a new bug is discovered.*\n- `ServerError`:\n *Raised when a server could not perform the request, you could try another server if one is available. Consult the [documentation](https://siridb.net/documentation/#help_list_servers) how to get additional status information about the servers.*\n- `TimeoutError`:\n *Raised when a process lasts longer than the `timeout` period*\n- `TypeError`:\n *Raised when an unknown package is received (might be caused by running a different SiriDB version).*\n- `UserAuthError`:\n *The user as no rights to perform the insert or query. Consult the [documentation](https://siridb.net/documentation/#help_access) how to change the access rights.*",
"bugtrack_url": null,
"license": null,
"summary": "SiriDB Connector",
"version": "2.1.6",
"project_urls": {
"Download": "https://github.com/SiriDB/siridb-connector/tarball/2.1.6",
"Homepage": "https://github.com/SiriDB/siridb-connector"
},
"split_keywords": [
"siridb",
" connector",
" database",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0132b532ca8ad3116dd548bc91e6f19276d939919c97a97159063ef5f4972e92",
"md5": "7eade1b07c9741ed887a25510098216e",
"sha256": "9cb1fe84d219450f2868b4ee13d35737d747332d0adae74fb409d529a34b100e"
},
"downloads": -1,
"filename": "siridb-connector-2.1.6.tar.gz",
"has_sig": false,
"md5_digest": "7eade1b07c9741ed887a25510098216e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16204,
"upload_time": "2024-09-04T09:20:43",
"upload_time_iso_8601": "2024-09-04T09:20:43.286635Z",
"url": "https://files.pythonhosted.org/packages/01/32/b532ca8ad3116dd548bc91e6f19276d939919c97a97159063ef5f4972e92/siridb-connector-2.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 09:20:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SiriDB",
"github_project": "siridb-connector",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "siridb-connector"
}
JSON
