sqlspec 0.56.1__tar.gz → 0.57.0__tar.gz

{sqlspec-0.56.1 → sqlspec-0.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.56.1
+Version: 0.57.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.56.1 → sqlspec-0.57.0}/pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.56.1"
+version = "0.57.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -308,7 +308,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.56.1"
+current_version = "0.57.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/adbc/core.py

@@ -46,6 +46,7 @@ from sqlspec.utils.module_loader import import_string
 from sqlspec.utils.serializers import to_json
 from sqlspec.utils.type_converters import build_uuid_coercions
 from sqlspec.utils.type_guards import has_rowcount, has_sqlstate
+from sqlspec.utils.uuids import uuid_from_string
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -1068,7 +1069,7 @@ def _convert_uuid_value(value: Any, ordinal: int, row_number: int, element_index
     if not isinstance(value, str):
         raise SQLSpecError(_uuid_binding_error(ordinal, value, row_number, element_index))
     try:
-        return str(UUID(value))
+        return str(uuid_from_string(value))
     except (TypeError, ValueError) as exc:
         raise SQLSpecError(_uuid_binding_error(ordinal, value, row_number, element_index)) from exc
 

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/adbc/driver.py

@@ -40,7 +40,7 @@ from sqlspec.core import (
 )
 from sqlspec.driver import BaseSyncExceptionHandler, SyncDriverAdapterBase, SyncRowStream
 from sqlspec.exceptions import DatabaseConnectionError, SQLSpecError
-from sqlspec.utils.arrow_helpers import arrow_reader_with_deferred_close
+from sqlspec.utils.arrow_helpers import arrow_reader_with_deferred_close, arrow_table_to_pylist
 from sqlspec.utils.logging import get_logger
 from sqlspec.utils.module_loader import ensure_pyarrow
 from sqlspec.utils.serializers import to_json
@@ -129,7 +129,12 @@ class AdbcSelectStreamSource:
                 batch = next(reader)
             except StopIteration:
                 return []
-            rows = cast("list[dict[str, Any]]", batch.to_pylist())
+            rows = arrow_table_to_pylist(
+                batch,
+                decode_arrow_extension_types=bool(
+                    self._driver.driver_features.get("enable_arrow_extension_types", True)
+                ),
+            )
             if rows:
                 return rows
 
@@ -224,7 +229,10 @@ class AdbcDriver(SyncDriverAdapterBase):
 
         if is_select_like:
             arrow_table = cursor.fetch_arrow_table()
-            data = arrow_table.to_pylist()
+            data = arrow_table_to_pylist(
+                arrow_table,
+                decode_arrow_extension_types=bool(self.driver_features.get("enable_arrow_extension_types", True)),
+            )
             column_names = list(arrow_table.column_names)
             return self.create_execution_result(
                 cursor,

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/bigquery/driver.py

@@ -772,14 +772,33 @@ def _bigquery_arrow_reader_from_iterable(batches: "Iterable[ArrowRecordBatch]")
 def _records_to_json_rows(
     records: "Sequence[Mapping[str, Any]] | Sequence[Sequence[Any]]", columns: "list[str] | None"
 ) -> "list[dict[str, Any]]":
-    materialized = list(records)
+    materialized = records if isinstance(records, list) else list(records)
     if not materialized:
         msg = "load_from_records requires at least one record."
         raise ImproperConfigurationError(msg)
 
     first = materialized[0]
     if isinstance(first, Mapping):
-        resolved = columns if columns is not None else list(first.keys())
+        if columns is None:
+            resolved = list(first.keys())
+            expected = set(resolved)
+            can_reuse = True
+            for record in materialized:
+                if not isinstance(record, Mapping):
+                    msg = "load_from_records mapping records must all be mappings."
+                    raise ImproperConfigurationError(msg)
+                record_keys = list(record.keys())
+                if set(record_keys) != expected:
+                    msg = "load_from_records mapping records must all share the same keys."
+                    raise ImproperConfigurationError(msg)
+                if type(record) is not dict or record_keys != resolved:
+                    can_reuse = False
+            validated_records = cast("list[Mapping[str, Any]]", materialized)
+            if can_reuse:
+                return cast("list[dict[str, Any]]", validated_records)
+            return [{column: record[column] for column in resolved} for record in validated_records]
+
+        resolved = columns
         expected = set(resolved)
         rows: list[dict[str, Any]] = []
         for record in materialized:

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/duckdb/core.py

@@ -4,7 +4,6 @@ import contextlib
 from datetime import date, datetime
 from decimal import Decimal
 from typing import TYPE_CHECKING, Any, Final, cast
-from uuid import UUID
 
 from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
 from sqlspec.exceptions import (
@@ -24,6 +23,7 @@ from sqlspec.exceptions import (
 from sqlspec.utils.serializers import to_json
 from sqlspec.utils.type_converters import build_decimal_converter, build_uuid_coercions, time_iso_convert
 from sqlspec.utils.type_guards import has_rowcount
+from sqlspec.utils.uuids import uuid_from_string
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -395,7 +395,7 @@ def _restore_uuid_columns(rows: "list[dict[str, Any]]", description: "list[Any]
         for column in uuid_columns:
             value = row.get(column)
             if isinstance(value, str):
-                row[column] = UUID(value)
+                row[column] = uuid_from_string(value)
 
 
 driver_profile = build_profile()

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/oracledb/_json_handlers.py

@@ -6,8 +6,9 @@ and Oracle's JSON storage types via connection type handlers.
 Routing matrix (input):
 
 * Oracle 21c+ native ``JSON``: bind via ``DB_TYPE_JSON`` (binary OSON).
-* Oracle 12c-20c with ``BLOB CHECK (... IS JSON)``: bind via ``DB_TYPE_BLOB`` with
- textual UTF-8 JSON bytes.
+* Oracle 12c-20c with ``BLOB CHECK (... IS JSON)``: the driver pre-serializes
+  JSON-shaped values and creates a ``DB_TYPE_BLOB`` locator containing UTF-8
+  JSON before input-handler dispatch.
 * Oracle 11g and earlier: bind via ``DB_TYPE_CLOB`` with serialized JSON string.
 * The rung is chosen by ``resolve_oracle_json_storage``, the single JSON-threshold
  source shared with ``OracleVersionInfo`` and the extension stores.
@@ -33,11 +34,12 @@ handler returns ``None`` for values it does not own.
 """
 
 from functools import partial
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 from oracledb import DB_TYPE_CHAR, DB_TYPE_NCHAR, DB_TYPE_NVARCHAR, DB_TYPE_VARCHAR
 
 from sqlspec.adapters.oracledb._typing import DB_TYPE_BLOB, DB_TYPE_CLOB, DB_TYPE_JSON, DB_TYPE_LONG, DB_TYPE_LONG_RAW
+from sqlspec.adapters.oracledb.data_dictionary import resolve_oracle_connection_major
 from sqlspec.data_dictionary.dialects.oracle import (
     ORACLE_JSON_STORAGE_BLOB_JSON,
     ORACLE_JSON_STORAGE_NATIVE,
@@ -51,6 +53,7 @@ if TYPE_CHECKING:
 __all__ = (
     "chain_input_handler",
     "chain_output_handler",
+    "is_json_payload",
     "json_converter_in_blob",
     "json_converter_in_clob",
     "json_converter_out_blob",
@@ -131,7 +134,7 @@ def chain_input_handler(inner: Any, fallback: "Any | None") -> Any:
     instance: python-oracledb selects its calling convention via
     ``inspect.signature(handler)``, which succeeds for a partial of a (compiled)
     function but raises ``ValueError`` for a compiled ``__call__`` object -- the
-    latter forces the legacy 6-argument call and breaks fetches.
+    latter forces the older 6-argument call and breaks fetches.
     """
     return partial(_chained_input_handler, inner, fallback)
 
@@ -144,7 +147,7 @@ def chain_output_handler(inner: Any, fallback: "Any | None") -> Any:
     return partial(_chained_output_handler, inner, fallback)
 
 
-def _is_json_payload(value: Any) -> bool:
+def is_json_payload(value: Any) -> bool:
     """Return True if the value should be claimed by the JSON input handler.
 
     ``dict`` and ``tuple``/``list`` of dicts are claimed. Sequences whose first
@@ -167,10 +170,10 @@ def _is_json_payload(value: Any) -> bool:
 
 def _input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
     """Oracle input type handler for JSON-shaped Python values."""
-    if not _is_json_payload(value):
+    if not is_json_payload(value):
         return None
 
-    server_major = cast("int | None", getattr(cursor.connection, "_sqlspec_oracle_major", None))
+    server_major = resolve_oracle_connection_major(cursor.connection)
 
     if server_major is None:
         return cursor.var(DB_TYPE_JSON, arraysize=arraysize)

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/oracledb/_param_types.py

@@ -8,7 +8,8 @@ Wrap a parameter value to express explicit intent:
 
 * :class:`OracleClob` — bind as ``DB_TYPE_CLOB`` regardless of length.
 * :class:`OracleBlob` — bind as ``DB_TYPE_BLOB`` regardless of length.
-* :class:`OracleJson` — bind as native JSON; defers to the C1 input handler.
+* :class:`OracleJson` — express JSON intent; the input handler selects the
+  storage type supported by the connected Oracle version.
 
 The wrappers themselves perform no validation — type discipline lives at the
 routing site so error messages can include database-context detail.
@@ -38,7 +39,7 @@ class OracleBlob:
 
 
 class OracleJson:
-    """Mark a value to be bound as native ``DB_TYPE_JSON`` regardless of detected version."""
+    """Mark a value for version-aware Oracle JSON binding."""
 
     __slots__ = ("value",)
 

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/oracledb/_uuid_handlers.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any
 from sqlspec.adapters.oracledb._json_handlers import chain_input_handler, chain_output_handler
 from sqlspec.adapters.oracledb._typing import DB_TYPE_RAW
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.uuids import uuid_from_bytes
 
 if TYPE_CHECKING:
     from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
@@ -59,7 +60,7 @@ def uuid_converter_out(value: bytes | None) -> "uuid.UUID | bytes | None":
         return value
 
     try:
-        return uuid.UUID(bytes=value)
+        return uuid_from_bytes(value)
     except (ValueError, TypeError):
         logger.debug("RAW(16) value is not valid UUID format, returning as bytes", extra={"value_length": len(value)})
         return value

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/oracledb/adk/store.py

@@ -296,7 +296,7 @@ class OracleAsyncADKStore(BaseAsyncADKStore["OracleAsyncConfig"]):
         config: OracleAsyncConfig with extension_config["adk"] settings.
 
     Notes:
-        - JSON storage type detected based on Oracle version (21c+, 12c+, legacy)
+        - JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
         - event_data stored as JSON (21c+) or BLOB (older versions)
         - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
         - Named parameters using :param_name
@@ -1265,7 +1265,7 @@ class OracleSyncADKStore(BaseSyncADKStore["OracleSyncConfig"]):
         config: OracleSyncConfig with extension_config["adk"] settings.
 
     Notes:
-        - JSON storage type detected based on Oracle version (21c+, 12c+, legacy)
+        - JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
         - event_data stored as JSON (21c+) or BLOB (older versions)
         - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
         - Named parameters using :param_name

{sqlspec-0.56.1 → sqlspec-0.57.0}/sqlspec/adapters/oracledb/config.py

@@ -23,7 +23,7 @@ from sqlspec.adapters.oracledb._typing import (
 from sqlspec.adapters.oracledb._uuid_handlers import register_uuid_handlers
 from sqlspec.adapters.oracledb._vector_handlers import register_numpy_handlers  # pyright: ignore[reportPrivateUsage]
 from sqlspec.adapters.oracledb.core import apply_driver_features, default_statement_config
-from sqlspec.adapters.oracledb.data_dictionary import OracleVersionCache
+from sqlspec.adapters.oracledb.data_dictionary import OracleVersionCache, resolve_oracle_connection_major
 from sqlspec.adapters.oracledb.driver import (
     OracleAsyncDriver,
     OracleAsyncExceptionHandler,
@@ -32,7 +32,6 @@ from sqlspec.adapters.oracledb.driver import (
 )
 from sqlspec.adapters.oracledb.migrations import OracleAsyncMigrationTracker, OracleSyncMigrationTracker
 from sqlspec.config import AsyncDatabaseConfig, ExtensionConfigs, SyncDatabaseConfig
-from sqlspec.data_dictionary.dialects.oracle import parse_oracle_version_components
 from sqlspec.driver._async import AsyncPoolConnectionContext, AsyncPoolSessionFactory
 from sqlspec.driver._sync import SyncPoolConnectionContext, SyncPoolSessionFactory
 from sqlspec.extensions.events import EventRuntimeHints
@@ -413,9 +412,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
         vector case) internally. UUID registration remains gated for
         backwards compatibility with existing user configurations.
 
-        Caches ``connection._sqlspec_oracle_major`` so the JSON input handler
-        can pick the right binding path (``DB_TYPE_JSON`` on 21c+, OSON-encoded
-        ``DB_TYPE_BLOB`` on 19c-20c, JSON-string ``DB_TYPE_CLOB`` on 12c-18c)
+        Caches ``connection._sqlspec_oracle_major`` so JSON parameter coercion
+        can pick the right binding path (``DB_TYPE_JSON`` on 21c+, a textual
+        ``BLOB IS JSON`` locator on 12c-20c, and ``DB_TYPE_CLOB`` before 12c)
         without re-querying server metadata on every bind. Caches
         ``connection._sqlspec_vector_return_format`` so the vector output
         handler can dispatch to ``numpy`` / ``list`` / ``array`` without
@@ -434,7 +433,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
 
         # Stash detected major version on the connection so the JSON input handler
         # can pick the right binding path without per-bind metadata queries.
-        setattr(connection, "_sqlspec_oracle_major", _resolve_connection_major(self._oracle_version_cache, connection))
+        setattr(
+            connection, "_sqlspec_oracle_major", resolve_oracle_connection_major(connection, self._oracle_version_cache)
+        )
         # Stash the vector-read format so the VECTOR output handler can
         # dispatch without re-reading driver-feature defaults on every fetch.
         setattr(connection, "_sqlspec_vector_return_format", self.driver_features.get("vector_return_format"))
@@ -628,7 +629,9 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
 
         # Stash detected major version on the connection so the JSON input handler
         # can pick the right binding path without per-bind metadata queries.
-        setattr(connection, "_sqlspec_oracle_major", _resolve_connection_major(self._oracle_version_cache, connection))
+        setattr(
+            connection, "_sqlspec_oracle_major", resolve_oracle_connection_major(connection, self._oracle_version_cache)
+        )
         # Stash the vector-read format so the VECTOR output handler can
         # dispatch without re-reading driver-feature defaults on every fetch.
         setattr(connection, "_sqlspec_vector_return_format", self.driver_features.get("vector_return_format"))
@@ -655,24 +658,3 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             await self.connection_instance.close()
             self.connection_instance = None
         self._oracle_version_cache.reset()
-
-
-def _resolve_connection_major(cache: "OracleVersionCache", connection: Any) -> "int | None":
-    """Resolve the Oracle server major for connection-setup type handlers.
-
-    Prefers the pool-scoped version cache once a driver has resolved it through
-    the data-dictionary path. Before that, the major is parsed from
-    ``connection.version`` — a connection attribute populated at connect time, so
-    no query is issued — using the same version parser the data dictionary uses.
-    Returns ``None`` when unavailable; callers treat ``None`` as "assume 21c+".
-    """
-    if cache.resolved and cache.version is not None:
-        return cache.version.major
-    try:
-        version_str = connection.version
-    except AttributeError:
-        return None
-    if not version_str:
-        return None
-    components = parse_oracle_version_components(str(version_str))
-    return components[0] if components is not None else None