wherobots-python-dbapi 0.26.1__py3-none-any.whl → 0.28.0__py3-none-any.whl

wherobots/db/driver.py

@@ -11,6 +11,7 @@ from packaging.version import Version
 import platform
 import requests
 import tenacity
+import threading
 from typing import Final, Union, Dict
 import urllib.parse
 import websockets.exceptions
@@ -20,8 +21,6 @@ import certifi
 from .connection import Connection
 from .constants import (
     DEFAULT_ENDPOINT,
-    DEFAULT_REGION,
-    DEFAULT_RUNTIME,
     DEFAULT_READ_TIMEOUT_SECONDS,
     DEFAULT_SESSION_TYPE,
     DEFAULT_SESSION_WAIT_TIMEOUT_SECONDS,
@@ -51,6 +50,9 @@ paramstyle: Final[str] = PARAM_STYLE
 # This follows the industry-standard set used by urllib3.util.Retry's status_forcelist.
 TRANSIENT_HTTP_STATUS_CODES = {429, 502, 503, 504}
 
+# Default timeout for individual HTTP requests (connect + read), in seconds.
+DEFAULT_HTTP_TIMEOUT = 30
+
 
 def gen_user_agent_header():
     try:
@@ -68,8 +70,8 @@ def connect(
     host: str = DEFAULT_ENDPOINT,
     token: Union[str, None] = None,
     api_key: Union[str, None] = None,
-    runtime: Union[Runtime, None] = None,
-    region: Union[Region, None] = None,
+    runtime: Union[str, Runtime, None] = None,
+    region: Union[str, Region, None] = None,
     version: Union[str, None] = None,
     wait_timeout: float = DEFAULT_SESSION_WAIT_TIMEOUT_SECONDS,
     read_timeout: float = DEFAULT_READ_TIMEOUT_SECONDS,
@@ -79,7 +81,22 @@ def connect(
     results_format: Union[ResultsFormat, None] = None,
     data_compression: Union[DataCompression, None] = None,
     geometry_representation: Union[GeometryRepresentation, None] = None,
+    cancel_event: Union[threading.Event, None] = None,
 ) -> Connection:
+    """Create a connection to a Wherobots SQL session.
+
+    :param runtime: The compute runtime to use. Accepts a ``Runtime`` enum value
+        or a raw string; strings are passed to the API as-is. Override the
+        default runtime set for your organization — only set this if you need a
+        specific runtime instead of the one your administrator has configured.
+        When omitted, your organization's default runtime is used.
+    :param region: The compute region to run in. Accepts a ``Region`` enum value
+        or a raw string (e.g. a BYOC region such as ``byoc-acme-us-east-1``);
+        strings are passed to the API as-is. Override the default region set for
+        your organization — only set this if you intend to use a specific region
+        instead of the one your administrator has configured. When omitted, your
+        organization's default region is used.
+    """
     if not token and not api_key:
         raise ValueError("At least one of `token` or `api_key` is required")
     if token and api_key:
@@ -92,16 +109,20 @@ def connect(
         headers["X-API-Key"] = api_key
 
     host = host or DEFAULT_ENDPOINT
-    runtime = runtime or DEFAULT_RUNTIME
-    region = region or DEFAULT_REGION
     session_type = session_type or DEFAULT_SESSION_TYPE
 
+    # Normalize enum values to their string form and pass raw strings through
+    # untouched. When omitted (None) the field is dropped from the request so
+    # the API applies the organization's configured default.
+    runtime_id = runtime.value if isinstance(runtime, Runtime) else runtime
+    region_name = region.value if isinstance(region, Region) else region
+
     logging.info(
         "Requesting %s%s runtime %sin %s from %s ...",
         "new " if force_new else "",
-        runtime.value,
+        runtime_id or "org-default",
         f"running {version} " if version else "",
-        region.value,
+        region_name or "org-default",
         host,
     )
 
@@ -109,17 +130,22 @@ def connect(
     if not host.startswith("http:"):
         host = f"https://{host}"
 
+    _check_cancelled(cancel_event)
+
     try:
         resp = requests.post(
             url=f"{host}/sql/session",
-            params={"region": region.value, "force_new": force_new},
+            # `requests` omits query params whose value is None, so an omitted
+            # region is simply not sent and the API applies the org default.
+            params={"region": region_name, "force_new": force_new},
             json={
-                "runtimeId": runtime.value,
+                "runtimeId": runtime_id,
                 "shutdownAfterInactiveSeconds": shutdown_after_inactive_seconds,
                 "version": version,
                 "sessionType": session_type.value,
             },
             headers=headers,
+            timeout=DEFAULT_HTTP_TIMEOUT,
         )
         resp.raise_for_status()
     except requests.HTTPError as e:
@@ -149,10 +175,12 @@ def connect(
             )
             | tenacity.retry_if_exception_type(tenacity.TryAgain)
         ),
+        before_sleep=lambda _: _check_cancelled(cancel_event),
         reraise=True,
     )
     def get_session_uri() -> str:
-        r = requests.get(session_id_url, headers=headers)
+        _check_cancelled(cancel_event)
+        r = requests.get(session_id_url, headers=headers, timeout=DEFAULT_HTTP_TIMEOUT)
         r.raise_for_status()
         payload = r.json()
         status = AppStatus(payload.get("status"))
@@ -169,6 +197,8 @@ def connect(
         logging.info("Getting SQL session status from %s ...", session_id_url)
         session_uri = get_session_uri()
         logging.debug("SQL session URI from app status: %s", session_uri)
+    except InterfaceError:
+        raise
     except Exception as e:
         raise InterfaceError("Could not acquire SQL session!", e)
 
@@ -179,9 +209,16 @@ def connect(
         results_format=results_format,
         data_compression=data_compression,
         geometry_representation=geometry_representation,
+        cancel_event=cancel_event,
     )
 
 
+def _check_cancelled(cancel_event: Union[threading.Event, None]) -> None:
+    """Raise InterfaceError if the cancel event is set."""
+    if cancel_event is not None and cancel_event.is_set():
+        raise InterfaceError("Connection cancelled by caller")
+
+
 def http_to_ws(uri: str) -> str:
     """Converts an HTTP URI to a WebSocket URI."""
     parsed = urllib.parse.urlparse(uri)
@@ -199,6 +236,7 @@ def connect_direct(
     results_format: Union[ResultsFormat, None] = None,
     data_compression: Union[DataCompression, None] = None,
     geometry_representation: Union[GeometryRepresentation, None] = None,
+    cancel_event: Union[threading.Event, None] = None,
 ) -> Connection:
     uri_with_protocol = f"{uri}/{protocol}"
     ssl_context = ssl.create_default_context()
@@ -215,19 +253,24 @@ def connect_direct(
                 websockets.exceptions.InvalidHandshake,
             )
         ),
+        before_sleep=lambda _: _check_cancelled(cancel_event),
         reraise=True,
     )
     def ws_connect() -> websockets.sync.client.ClientConnection:
+        _check_cancelled(cancel_event)
         logging.info("Connecting to SQL session at %s ...", uri_with_protocol)
         return websockets.sync.client.connect(
             uri=uri_with_protocol,
             additional_headers=headers,
             max_size=MAX_MESSAGE_SIZE,
+            open_timeout=DEFAULT_HTTP_TIMEOUT,
             ssl=ssl_context,
         )
 
     try:
         ws = ws_connect()
+    except InterfaceError:
+        raise
     except Exception as e:
         raise InterfaceError("Failed to connect to SQL session!") from e
 

{wherobots_python_dbapi-0.26.1.dist-info → wherobots_python_dbapi-0.28.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-dbapi
-Version: 0.26.1
+Version: 0.28.0
 Summary: Python DB-API driver for Wherobots DB
 Project-URL: Homepage, https://github.com/wherobots/wherobots-python-dbapi-driver
 Project-URL: Tracker, https://github.com/wherobots/wherobots-python-dbapi-driver/issues
@@ -107,6 +107,16 @@ with connect(
     print(results)
 ```
 
+`runtime` and `region` are optional and accept either the provided enums (handy
+for autocomplete) or a plain string — strings are passed to the API as-is, so
+new or BYOC regions (e.g. `region="byoc-acme-us-east-1"`) work without an SDK
+upgrade. When omitted, your organization's configured defaults are used:
+
+```python
+with connect(api_key='...') as conn:  # uses your org's default runtime + region
+    ...
+```
+
 The `Cursor` supports the context manager protocol, so you can use it
 within a `with` statement when needed:
 
@@ -285,3 +295,9 @@ users may find useful:
     your expected time between queries and effectively get a continuously
     running SQL session runtime without any complex connection management
     in your application.
+* `cancel_event`: a `threading.Event` that, when set, causes the
+    connection attempt to abort promptly with an `InterfaceError`. This
+    is useful when `connect()` is running in a background thread and the
+    caller needs to interrupt it (e.g. on client disconnect or timeout).
+    The event is checked before each HTTP request, between retry
+    attempts, and before the WebSocket handshake.

{wherobots_python_dbapi-0.26.1.dist-info → wherobots_python_dbapi-0.28.0.dist-info}/RECORD

@@ -3,14 +3,14 @@ wherobots/db/__init__.py,sha256=HN_uGOUMor80GB3rZIqnPcYWDAia7QAC-y9HfGKnegs,744
 wherobots/db/connection.py,sha256=BWQwVzFgujEwPKvhDePM9q45M2opCk6Jq998L0ekMyY,12795
 wherobots/db/constants.py,sha256=qV-6CmOya7-f-DoRMzcDzlhcmV5PkLCcqG5TFIsxQ7o,744
 wherobots/db/cursor.py,sha256=Z0rNdhJ985IP9XnZpjrCzvM0OqDFVgCNfJn8lrbijAo,6809
-wherobots/db/driver.py,sha256=2DAkWSQQOijDY3Zbufbk7j8X0yYkrqhLU_kvrNa7P2s,8002
+wherobots/db/driver.py,sha256=fHfYtujvafmAnJh9uf_0oZUNVtyf8XLsgs9sqfiDMk4,10304
 wherobots/db/errors.py,sha256=G8a-DB6pgB0pUld59Wyq8PuywL-JWxGJfvrr-g8BPuU,310
 wherobots/db/models.py,sha256=uk0EqZMH_RFkQusSw2AvyFivGvGJBu_WYP8FHa6JJGM,4178
 wherobots/db/region.py,sha256=GoFzazvgOjE1kVVT1QKAsRK88c_1XSAebR3ME4foSlQ,400
 wherobots/db/runtime.py,sha256=eAR1oJEtssgkp-IRPTLOrlPI-_5SM_ASw6T6hQ_qF4I,985
 wherobots/db/session_type.py,sha256=jZNwCl0nxvY-0reIn8RR_-fIYSSvIcaGx_4pRc71Lww,137
 wherobots/db/types.py,sha256=WXKT_gbdQCH2_yXD_FECk0BpB7yfNWOLewCfax0U_Lk,2516
-wherobots_python_dbapi-0.26.1.dist-info/METADATA,sha256=ILRnl_hGC_RlRgzuttJxSw9ubkJMAjVMVmMEb8G8V-M,10328
-wherobots_python_dbapi-0.26.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-wherobots_python_dbapi-0.26.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-wherobots_python_dbapi-0.26.1.dist-info/RECORD,,
+wherobots_python_dbapi-0.28.0.dist-info/METADATA,sha256=qUqbExsrE8Q6GwBE8f_mWL8-yNnGAp4vY1qgc_2OU0c,11142
+wherobots_python_dbapi-0.28.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wherobots_python_dbapi-0.28.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+wherobots_python_dbapi-0.28.0.dist-info/RECORD,,