wherobots-python-dbapi 0.4.0__tar.gz → 0.5.0__tar.gz

{wherobots_python_dbapi-0.4.0 → wherobots_python_dbapi-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wherobots-python-dbapi
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python DB-API driver for Wherobots DB
 License: Apache 2.0
 Author: Maxime Petazzoni
@@ -44,6 +44,11 @@ $ pip install git+https://github.com/wherobots/wherobots-python-dbapi-driver
 
 ## 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
@@ -59,8 +64,8 @@ with connect(
     print(results)
 ```
 
-The `Cursor` also supports the context manager protocol, so you can use
-it within a `with` statement when needed:
+The `Cursor` supports the context manager protocol, so you can use it
+within a `with` statement when needed:
 
 ```python
 with connect(...) as conn:
@@ -73,3 +78,30 @@ 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).
+
+The only supported Wherobots compute region for now is `aws-us-west-2`,
+in AWS's Oregon (`us-west-2`) region.
+
+### 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.
+

wherobots_python_dbapi-0.5.0/README.md

@@ -0,0 +1,83 @@
+# wherobots-python-dbapi-driver
+
+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
+
+If you use [Poetry](https://python-poetry.org) in your project, add the
+dependency with `poetry add`:
+
+```
+$ poetry add git+https://github.com/wherobots/wherobots-python-dbapi-driver
+```
+
+Otherwise, just `pip install` it:
+
+```
+$ pip install git+https://github.com/wherobots/wherobots-python-dbapi-driver
+```
+
+## 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.SEDONA,
+        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).
+
+The only supported Wherobots compute region for now is `aws-us-west-2`,
+in AWS's Oregon (`us-west-2`) region.
+
+### 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.

{wherobots_python_dbapi-0.4.0 → wherobots_python_dbapi-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wherobots-python-dbapi"
-version = "0.4.0"
+version = "0.5.0"
 description = "Python DB-API driver for Wherobots DB"
 authors = ["Maxime Petazzoni <max@wherobots.com>"]
 license = "Apache 2.0"

{wherobots_python_dbapi-0.4.0 → wherobots_python_dbapi-0.5.0}/wherobots/db/connection.py

@@ -1,9 +1,10 @@
 import json
 import logging
+import textwrap
 import threading
 import uuid
 from dataclasses import dataclass
-from typing import Callable, Any
+from typing import Any, Callable, Union
 
 import cbor2
 import pyarrow
@@ -18,13 +19,11 @@ from wherobots.db.constants import (
     ExecutionState,
     ResultsFormat,
     DataCompression,
+    GeometryRepresentation,
 )
 from wherobots.db.cursor import Cursor
 from wherobots.db.errors import NotSupportedError, OperationalError
 
-_DEFAULT_RESULTS_FORMAT = ResultsFormat.ARROW
-_DEFAULT_DATA_COMPRESSION = DataCompression.BROTLI
-
 
 @dataclass
 class Query:
@@ -53,9 +52,16 @@ class Connection:
         self,
         ws: websockets.sync.client.ClientConnection,
         read_timeout: float = DEFAULT_READ_TIMEOUT_SECONDS,
+        results_format: Union[ResultsFormat, None] = None,
+        data_compression: Union[DataCompression, None] = None,
+        geometry_representation: Union[GeometryRepresentation, None] = None,
     ):
         self.__ws = ws
         self.__read_timeout = read_timeout
+        self.__results_format = results_format
+        self.__data_compression = data_compression
+        self.__geometry_representation = geometry_representation
+
         self.__queries: dict[str, Query] = {}
         self.__thread = threading.Thread(
             target=self.__main_loop, daemon=True, name="wherobots-connection"
@@ -155,9 +161,7 @@ class Connection:
                     query.handler(reader.read_pandas())
             else:
                 query.handler(
-                    OperationalError(
-                        f"Unsupported results format {result_format}"
-                    )
+                    OperationalError(f"Unsupported results format {result_format}")
                 )
         elif kind == EventKind.ERROR:
             query.state = ExecutionState.FAILED
@@ -167,7 +171,9 @@ class Connection:
             logging.warning("Received unknown %s event!", kind)
 
     def __send(self, message: dict[str, Any]) -> None:
-        self.__ws.send(json.dumps(message))
+        request = json.dumps(message)
+        logging.debug("Request: %s", request)
+        self.__ws.send(request)
 
     def __recv(self) -> dict[str, Any]:
         frame = self.__ws.recv(timeout=self.__read_timeout)
@@ -194,6 +200,10 @@ class Connection:
             state=ExecutionState.EXECUTION_REQUESTED,
             handler=handler,
         )
+
+        logging.info(
+            "Executing SQL query %s: %s", execution_id, textwrap.shorten(sql, width=60)
+        )
         self.__send(request)
         return execution_id
 
@@ -205,9 +215,14 @@ class Connection:
         request = {
             "kind": RequestKind.RETRIEVE_RESULTS.value,
             "execution_id": execution_id,
-            "format": _DEFAULT_RESULTS_FORMAT.value,
-            "compression": _DEFAULT_DATA_COMPRESSION.value,
         }
+        if self.__results_format:
+            request["format"] = self.__results_format.value
+        if self.__data_compression:
+            request["compression"] = self.__data_compression.value
+        if self.__geometry_representation:
+            request["geometry"] = self.__geometry_representation.value
+
         query.state = ExecutionState.RESULTS_REQUESTED
         logging.info("Requesting results from %s ...", execution_id)
         self.__send(request)

{wherobots_python_dbapi-0.4.0 → wherobots_python_dbapi-0.5.0}/wherobots/db/constants.py

@@ -5,13 +5,14 @@ from .region import Region
 from .runtime import Runtime
 
 
-DEFAULT_ENDPOINT: str = "api.wherobots.services"  # "api.cloud.wherobots.com"
-STAGING_ENDPOINT: str = "api.staging.wherobots.services"  # "api.staging.wherobots.com"
+DEFAULT_ENDPOINT: str = "api.cloud.wherobots.com"  # "api.cloud.wherobots.com"
+STAGING_ENDPOINT: str = "api.staging.wherobots.com"  # "api.staging.wherobots.com"
 DEFAULT_RUNTIME: Runtime = Runtime.SEDONA
 DEFAULT_REGION: Region = Region.AWS_US_WEST_2
 DEFAULT_READ_TIMEOUT_SECONDS: float = 0.25
 DEFAULT_SESSION_WAIT_TIMEOUT_SECONDS: float = 300
 MAX_MESSAGE_SIZE: int = 100 * 2**20  # 100MiB
+PROTOCOL_VERSION: str = "1.0.0"
 
 
 class ExecutionState(LowercaseStrEnum):
@@ -58,3 +59,11 @@ class ResultsFormat(LowercaseStrEnum):
 
 class DataCompression(LowercaseStrEnum):
     BROTLI = auto()
+
+
+class GeometryRepresentation(LowercaseStrEnum):
+    WKT = auto()
+    WKB = auto()
+    EWKT = auto()
+    EWKB = auto()
+    GEOJSON = auto()

{wherobots_python_dbapi-0.4.0 → wherobots_python_dbapi-0.5.0}/wherobots/db/driver.py

@@ -4,11 +4,13 @@ A PEP-0249 compatible driver for interfacing with Wherobots DB.
 """
 
 import logging
+import os
 import urllib.parse
 import queue
 import requests
 import tenacity
 import threading
+from typing import Union
 import websockets.sync.client
 
 from .constants import (
@@ -18,6 +20,10 @@ from .constants import (
     DEFAULT_READ_TIMEOUT_SECONDS,
     DEFAULT_SESSION_WAIT_TIMEOUT_SECONDS,
     MAX_MESSAGE_SIZE,
+    PROTOCOL_VERSION,
+    ResultsFormat,
+    DataCompression,
+    GeometryRepresentation,
 )
 from .errors import (
     InterfaceError,
@@ -40,6 +46,9 @@ def connect(
     region: Region = None,
     wait_timeout: float = DEFAULT_SESSION_WAIT_TIMEOUT_SECONDS,
     read_timeout: float = DEFAULT_READ_TIMEOUT_SECONDS,
+    results_format: Union[ResultsFormat, None] = None,
+    data_compression: Union[DataCompression, None] = None,
+    geometry_representation: Union[GeometryRepresentation, None] = None,
 ) -> Connection:
     if not token and not api_key:
         raise ValueError("At least one of `token` or `api_key` is required")
@@ -113,6 +122,9 @@ def connect(
         uri=http_to_ws(session_uri),
         headers=headers,
         read_timeout=read_timeout,
+        results_format=results_format,
+        data_compression=data_compression,
+        geometry_representation=geometry_representation,
     )
 
 
@@ -125,18 +137,27 @@ def http_to_ws(uri: str) -> str:
     return str(urllib.parse.urlunparse(parsed))
 
 
+def append_protocol(uri: str, protocol: str) -> str:
+    """Appends the protocol version to the URI."""
+    return urllib.parse.urljoin(os.path.join(uri, ""), protocol)
+
+
 def connect_direct(
     uri: str,
     headers: dict[str, str] = None,
     read_timeout: float = DEFAULT_READ_TIMEOUT_SECONDS,
+    results_format: Union[ResultsFormat, None] = None,
+    data_compression: Union[DataCompression, None] = None,
+    geometry_representation: Union[GeometryRepresentation, None] = None,
 ) -> Connection:
     q = queue.SimpleQueue()
+    uri_with_protocol = append_protocol(uri, PROTOCOL_VERSION)
 
     def create_ws_connection():
         try:
-            logging.info("Connecting to SQL session at %s ...", uri)
+            logging.info("Connecting to SQL session at %s ...", uri_with_protocol)
             ws = websockets.sync.client.connect(
-                uri=uri,
+                uri=uri_with_protocol,
                 additional_headers=headers,
                 max_size=MAX_MESSAGE_SIZE,
             )
@@ -156,4 +177,10 @@ def connect_direct(
     if isinstance(result, Exception):
         raise InterfaceError("Failed to connect to SQL session!") from result
 
-    return Connection(result, read_timeout)
+    return Connection(
+        result,
+        read_timeout=read_timeout,
+        results_format=results_format,
+        data_compression=data_compression,
+        geometry_representation=geometry_representation,
+    )

wherobots_python_dbapi-0.4.0/README.md

@@ -1,51 +0,0 @@
-# wherobots-python-dbapi-driver
-
-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
-
-If you use [Poetry](https://python-poetry.org) in your project, add the
-dependency with `poetry add`:
-
-```
-$ poetry add git+https://github.com/wherobots/wherobots-python-dbapi-driver
-```
-
-Otherwise, just `pip install` it:
-
-```
-$ pip install git+https://github.com/wherobots/wherobots-python-dbapi-driver
-```
-
-## Usage
-
-```python
-from wherobots.db import connect
-from wherobots.db.region import Region
-from wherobots.db.runtime import Runtime
-
-with connect(
-        api_key='...',
-        runtime=Runtime.SEDONA,
-        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` also 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()`.