wherobots-python-dbapi 0.25.2__tar.gz → 0.25.4__tar.gz

{wherobots_python_dbapi-0.25.2 → wherobots_python_dbapi-0.25.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-dbapi
-Version: 0.25.2
+Version: 0.25.4
 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
@@ -13,10 +13,10 @@ Requires-Dist: packaging
 Requires-Dist: pandas
 Requires-Dist: pandas-stubs>=2.0.3.230814
 Requires-Dist: pyarrow>=14.0.2
-Requires-Dist: requests>=2.32.3
+Requires-Dist: requests>=2.31.0
 Requires-Dist: strenum<0.5,>=0.4.15
 Requires-Dist: tenacity>=8.2.3
-Requires-Dist: types-requests>=2.32.0.20241016
+Requires-Dist: types-requests>=2.31.0
 Requires-Dist: websockets>=13.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.2; extra == 'test'
@@ -28,6 +28,44 @@ 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.
 
+## PEP 249 DB-API 2.0 Compliance
+
+This driver implements the [PEP 249](https://peps.python.org/pep-0249/)
+Python Database API Specification v2.0 and exposes the following
+module-level globals:
+
+| Global | Value | Meaning |
+|---|---|---|
+| `apilevel` | `"2.0"` | Supports DB-API 2.0 |
+| `threadsafety` | `1` | Threads may share the module, but not connections |
+| `paramstyle` | `"pyformat"` | Uses `%(name)s` named parameter markers |
+
+### Parameterized queries
+
+Use `%(name)s` markers in your SQL and pass a dictionary of parameter
+values. The driver automatically quotes and escapes values based on
+their Python type (strings are single-quoted, `None` becomes `NULL`,
+booleans become `TRUE`/`FALSE`, and numeric types are passed through
+unquoted):
+
+```python
+curr.execute(
+    "SELECT * FROM places WHERE id = %(id)s AND category = %(cat)s",
+    parameters={"id": 42, "cat": "restaurant"},
+)
+# Produces: ... WHERE id = 42 AND category = 'restaurant'
+```
+
+Literal `%` characters in SQL (e.g. `LIKE` wildcards) do not need
+escaping and work alongside parameters:
+
+```python
+curr.execute(
+    "SELECT * FROM places WHERE name LIKE '%coffee%' AND city = %(city)s",
+    parameters={"city": "Seattle"},
+)
+```
+
 ## Installation
 
 To add this library as a dependency in your Python project, use `uv add`

{wherobots_python_dbapi-0.25.2 → wherobots_python_dbapi-0.25.4}/README.md

@@ -4,6 +4,44 @@ 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.
 
+## PEP 249 DB-API 2.0 Compliance
+
+This driver implements the [PEP 249](https://peps.python.org/pep-0249/)
+Python Database API Specification v2.0 and exposes the following
+module-level globals:
+
+| Global | Value | Meaning |
+|---|---|---|
+| `apilevel` | `"2.0"` | Supports DB-API 2.0 |
+| `threadsafety` | `1` | Threads may share the module, but not connections |
+| `paramstyle` | `"pyformat"` | Uses `%(name)s` named parameter markers |
+
+### Parameterized queries
+
+Use `%(name)s` markers in your SQL and pass a dictionary of parameter
+values. The driver automatically quotes and escapes values based on
+their Python type (strings are single-quoted, `None` becomes `NULL`,
+booleans become `TRUE`/`FALSE`, and numeric types are passed through
+unquoted):
+
+```python
+curr.execute(
+    "SELECT * FROM places WHERE id = %(id)s AND category = %(cat)s",
+    parameters={"id": 42, "cat": "restaurant"},
+)
+# Produces: ... WHERE id = 42 AND category = 'restaurant'
+```
+
+Literal `%` characters in SQL (e.g. `LIKE` wildcards) do not need
+escaping and work alongside parameters:
+
+```python
+curr.execute(
+    "SELECT * FROM places WHERE name LIKE '%coffee%' AND city = %(city)s",
+    parameters={"city": "Seattle"},
+)
+```
+
 ## Installation
 
 To add this library as a dependency in your Python project, use `uv add`

{wherobots_python_dbapi-0.25.2 → wherobots_python_dbapi-0.25.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wherobots-python-dbapi"
-version = "0.25.2"
+version = "0.25.4"
 description = "Python DB-API driver for Wherobots DB"
 authors = [{ name = "Maxime Petazzoni", email = "max@wherobots.com" }]
 requires-python = ">=3.10, <4"
@@ -8,14 +8,14 @@ readme = "README.md"
 license = "Apache-2.0"
 dependencies = [
     "packaging",
-    "requests>=2.32.3",
+    "requests>=2.31.0",
     "websockets>=13.0",
     "tenacity>=8.2.3",
     "cbor2>=5.6.3",
     "StrEnum>=0.4.15,<0.5",
     "pyarrow>=14.0.2",
     "pandas",
-    "types-requests>=2.32.0.20241016",
+    "types-requests>=2.31.0",
     "pandas-stubs>=2.0.3.230814",
 ]
 

{wherobots_python_dbapi-0.25.2 → wherobots_python_dbapi-0.25.4}/wherobots/db/cursor.py

@@ -1,9 +1,60 @@
+import math
 import queue
+import re
 from typing import Any, List, Tuple, Dict
 
 from .errors import ProgrammingError
 from .models import ExecutionResult, Store, StoreResult
 
+# Matches pyformat parameter markers: %(name)s
+_PYFORMAT_RE = re.compile(r"%\(([^)]+)\)s")
+
+
+def _quote_value(value: Any) -> str:
+    """Convert a Python value to a SQL literal string.
+
+    Handles quoting and escaping so that the interpolated SQL is syntactically
+    correct and safe from trivial injection.
+    """
+    if value is None:
+        return "NULL"
+    # bool must be checked before int because bool is a subclass of int
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    if isinstance(value, (int, float)):
+        if isinstance(value, float) and (math.isnan(value) or math.isinf(value)):
+            raise ProgrammingError(
+                f"Cannot convert float value {value!r} to SQL literal"
+            )
+        return str(value)
+    if isinstance(value, bytes):
+        return "X'" + value.hex() + "'"
+    # Everything else (str, date, datetime, etc.) is treated as a string literal
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+def _substitute_parameters(operation: str, parameters: Dict[str, Any] | None) -> str:
+    """Substitute pyformat parameters into a SQL operation string.
+
+    Uses regex to match only %(name)s tokens, leaving literal percent
+    characters (e.g. SQL LIKE wildcards) untouched.  Values are quoted
+    according to their Python type so the resulting SQL is syntactically
+    correct (see :func:`_quote_value`).
+    """
+    if not parameters:
+        return operation
+
+    def replacer(match: re.Match) -> str:
+        key = match.group(1)
+        if key not in parameters:
+            raise ProgrammingError(
+                f"Parameter '{key}' not found in provided parameters"
+            )
+        return _quote_value(parameters[key])
+
+    return _PYFORMAT_RE.sub(replacer, operation)
+
+
 _TYPE_MAP = {
     "object": "STRING",
     "int64": "NUMBER",
@@ -99,7 +150,9 @@ class Cursor:
         self.__description = None
 
         self.__current_execution_id = self.__exec_fn(
-            operation % (parameters or {}), self.__on_execution_result, store
+            _substitute_parameters(operation, parameters),
+            self.__on_execution_result,
+            store,
         )
 
     def get_store_result(self) -> StoreResult | None: