| Name | wherobots-python-dbapi JSON |
| Version |
0.19.0
JSON |
| download |
| home_page | None |
| Summary | Python DB-API driver for Wherobots DB |
| upload_time | 2025-08-28 04:21:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ~=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# wherobots-python-dbapi
Python DB-API implementation for Wherobots DB. This package implements a
PEP-0249 compatible driver to programmatically connect to a Wherobots DB
runtime and execute Spatial SQL queries.
## Installation
To add this library as a dependency in your Python project, use `uv add`
or `poetry add` as appropriate:
```
# For uv-managed projects
$ uv add wherobots-python-dbapi
# For poetry-managed projects
$ poetry add wherobots-python-dbapi
```
Otherwise, just `pip install` it:
```
$ pip install wherobots-python-dbapi
```
## Usage
### Basic usage
Basic usage follows the typical pattern of establishing the connection,
acquiring a cursor, and executing SQL queries through it:
```python
from wherobots.db import connect
from wherobots.db.region import Region
from wherobots.db.runtime import Runtime
with connect(
api_key='...',
runtime=Runtime.TINY,
region=Region.AWS_US_WEST_2) as conn:
curr = conn.cursor()
curr.execute("SHOW SCHEMAS IN wherobots_open_data")
results = curr.fetchall()
print(results)
```
The `Cursor` supports the context manager protocol, so you can use it
within a `with` statement when needed:
```python
with connect(...) as conn:
with conn.cursor() as curr:
curr.execute(...)
results = curr.fetchall()
```
It also implements the `close()` method, as suggested by the PEP-2049
specification, to support situations where the cursor is wrapped in a
`contextmanager.closing()`.
### Runtime and region selection
You can chose the Wherobots runtime you want to use using the `runtime`
parameter, passing in one of the `Runtime` enum values. For more
information on runtime sizing and selection, please consult the
[Wherobots product documentation](https://docs.wherobots.com).
You must also specify in which region your SQL session should execute
into. Wherobots Cloud supports the following compute regions:
* `aws-us-east-1`: AWS US East 1 (N. Virginia)
* `aws-us-west-2`: AWS US West 2 (Oregon)
* `aws-eu-west-1`: AWS EU West 1 (Ireland)
* `aws-ap-south-1`: AWS AP South 1 (Mumbai)
> [!IMPORTANT]
> The `aws-us-west-2` region is available to all Wherobots Cloud users
> and customers; other regions are currently reserved to Professional
> Edition customers.
### Advanced parameters
The `connect()` method takes some additional parameters that advanced
users may find useful:
* `results_format`: one of the `ResultsFormat` enum values;
Arrow encoding is the default and most efficient format for
receiving query results.
* `data_compression`: one of the `DataCompression` enum values; Brotli
compression is the default and the most efficient compression
algorithm for receiving query results.
* `geometry_representation`: one of the `GeometryRepresentation` enum
values; selects the encoding of geometry columns returned to the
client application. The default is EWKT (string) and the most
convenient for human inspection while still being usable by
libraries like Shapely.
* `version`: one of the WherobotsDB runtime versions that is available
to you, if you need to pin your usage to a particular, supported
WherobotsDB version. Defaults to `"latest"`.
* `session_type`: `"single"` or `"multi"`; if set to `"single"`, then
each call to `connect()` establishes an exclusive connection to a
distinct and dedicated Wherobots runtime; if set to "multi", then
multiple `connect()` calls with the same arguments and credentials
will connect to the same shared Wherobots runtime; `"multi"` is the
default.
Consider multi-session for potential cost savings, but be mindful of
performance impacts from shared resources. You might need to adjust
cluster size if slowdowns occur, which could affect overall cost.
Raw data
{
"_id": null,
"home_page": null,
"name": "wherobots-python-dbapi",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Maxime Petazzoni <max@wherobots.com>",
"download_url": "https://files.pythonhosted.org/packages/46/52/89d00db9bf66381e6b6dfb42ed0d7b97231ebe1ad88ad1a0a15205a74c65/wherobots_python_dbapi-0.19.0.tar.gz",
"platform": null,
"description": "# wherobots-python-dbapi\n\nPython DB-API implementation for Wherobots DB. This package implements a\nPEP-0249 compatible driver to programmatically connect to a Wherobots DB\nruntime and execute Spatial SQL queries.\n\n## Installation\n\nTo add this library as a dependency in your Python project, use `uv add`\nor `poetry add` as appropriate:\n\n```\n# For uv-managed projects\n$ uv add wherobots-python-dbapi\n\n# For poetry-managed projects\n$ poetry add wherobots-python-dbapi\n```\n\nOtherwise, just `pip install` it:\n\n```\n$ pip install wherobots-python-dbapi\n```\n\n## Usage\n\n### Basic usage\n\nBasic usage follows the typical pattern of establishing the connection,\nacquiring a cursor, and executing SQL queries through it:\n\n```python\nfrom wherobots.db import connect\nfrom wherobots.db.region import Region\nfrom wherobots.db.runtime import Runtime\n\nwith connect(\n api_key='...',\n runtime=Runtime.TINY,\n region=Region.AWS_US_WEST_2) as conn:\n curr = conn.cursor()\n curr.execute(\"SHOW SCHEMAS IN wherobots_open_data\")\n results = curr.fetchall()\n print(results)\n```\n\nThe `Cursor` supports the context manager protocol, so you can use it\nwithin a `with` statement when needed:\n\n```python\nwith connect(...) as conn:\n with conn.cursor() as curr:\n curr.execute(...)\n results = curr.fetchall()\n```\n\nIt also implements the `close()` method, as suggested by the PEP-2049\nspecification, to support situations where the cursor is wrapped in a\n`contextmanager.closing()`.\n\n### Runtime and region selection\n\nYou can chose the Wherobots runtime you want to use using the `runtime`\nparameter, passing in one of the `Runtime` enum values. For more\ninformation on runtime sizing and selection, please consult the\n[Wherobots product documentation](https://docs.wherobots.com).\n\nYou must also specify in which region your SQL session should execute\ninto. Wherobots Cloud supports the following compute regions:\n\n* `aws-us-east-1`: AWS US East 1 (N. Virginia)\n* `aws-us-west-2`: AWS US West 2 (Oregon)\n* `aws-eu-west-1`: AWS EU West 1 (Ireland)\n* `aws-ap-south-1`: AWS AP South 1 (Mumbai)\n\n> [!IMPORTANT]\n> The `aws-us-west-2` region is available to all Wherobots Cloud users\n> and customers; other regions are currently reserved to Professional\n> Edition customers.\n\n### Advanced parameters\n\nThe `connect()` method takes some additional parameters that advanced\nusers may find useful:\n\n* `results_format`: one of the `ResultsFormat` enum values;\n Arrow encoding is the default and most efficient format for\n receiving query results.\n* `data_compression`: one of the `DataCompression` enum values; Brotli\n compression is the default and the most efficient compression\n algorithm for receiving query results.\n* `geometry_representation`: one of the `GeometryRepresentation` enum\n values; selects the encoding of geometry columns returned to the\n client application. The default is EWKT (string) and the most\n convenient for human inspection while still being usable by\n libraries like Shapely.\n* `version`: one of the WherobotsDB runtime versions that is available\n to you, if you need to pin your usage to a particular, supported\n WherobotsDB version. Defaults to `\"latest\"`.\n* `session_type`: `\"single\"` or `\"multi\"`; if set to `\"single\"`, then\n each call to `connect()` establishes an exclusive connection to a\n distinct and dedicated Wherobots runtime; if set to \"multi\", then\n multiple `connect()` calls with the same arguments and credentials\n will connect to the same shared Wherobots runtime; `\"multi\"` is the\n default.\n\n Consider multi-session for potential cost savings, but be mindful of\n performance impacts from shared resources. You might need to adjust\n cluster size if slowdowns occur, which could affect overall cost.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python DB-API driver for Wherobots DB",
"version": "0.19.0",
"project_urls": {
"Homepage": "https://github.com/wherobots/wherobots-python-dbapi-driver",
"Tracker": "https://github.com/wherobots/wherobots-python-dbapi-driver/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a7fb63ea670eee6740d2d277bcbbe2ddcbc24f75c7b0486240c11144c055c90e",
"md5": "81320e042c9c2e0393557077de6910e2",
"sha256": "10c96ef6bb559023d18e1eb1d22125349395d4c9a04f9486b2a52ab5b87e187c"
},
"downloads": -1,
"filename": "wherobots_python_dbapi-0.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81320e042c9c2e0393557077de6910e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 16696,
"upload_time": "2025-08-28T04:21:33",
"upload_time_iso_8601": "2025-08-28T04:21:33.468442Z",
"url": "https://files.pythonhosted.org/packages/a7/fb/63ea670eee6740d2d277bcbbe2ddcbc24f75c7b0486240c11144c055c90e/wherobots_python_dbapi-0.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "465289d00db9bf66381e6b6dfb42ed0d7b97231ebe1ad88ad1a0a15205a74c65",
"md5": "92e539bc309db4fb1d1bc92335f5fef9",
"sha256": "7ce10c163bece5a393a5256d1027c7c36303496135940392b6087ecd6591a361"
},
"downloads": -1,
"filename": "wherobots_python_dbapi-0.19.0.tar.gz",
"has_sig": false,
"md5_digest": "92e539bc309db4fb1d1bc92335f5fef9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 14580,
"upload_time": "2025-08-28T04:21:34",
"upload_time_iso_8601": "2025-08-28T04:21:34.583103Z",
"url": "https://files.pythonhosted.org/packages/46/52/89d00db9bf66381e6b6dfb42ed0d7b97231ebe1ad88ad1a0a15205a74c65/wherobots_python_dbapi-0.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 04:21:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wherobots",
"github_project": "wherobots-python-dbapi-driver",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wherobots-python-dbapi"
}
