sqlspec 0.25.0__tar.gz → 0.26.0__tar.gz

{sqlspec-0.25.0 → sqlspec-0.26.0}/.gitignore

@@ -61,3 +61,6 @@ benchmarks/
 *.duckdb
 .crush
 CRUSH.md
+*.md
+!README.md
+!CONTRIBUTING.md

{sqlspec-0.25.0 → sqlspec-0.26.0}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.13.0"
+    rev: "v0.13.2"
     hooks:
       - id: ruff
         args: ["--fix"]

{sqlspec-0.25.0 → sqlspec-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.25.0
+Version: 0.26.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.25.0 → sqlspec-0.26.0}/pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.9, <4.0"
-version = "0.25.0"
+version = "0.26.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -91,6 +91,7 @@ extras = [
   "adbc_driver_postgresql",
   "adbc_driver_flightsql",
   "adbc_driver_bigquery",
+  "dishka ; python_version >= \"3.10\"",
 ]
 lint = [
   "mypy>=1.13.0",
@@ -161,6 +162,13 @@ include = [
   "sqlspec/core/**/*.py", # Core module
   "sqlspec/loader.py",    # Loader module
 
+  # === ADAPTER TYPE CONVERTERS ===
+  "sqlspec/adapters/adbc/type_converter.py",     # ADBC type converter
+  "sqlspec/adapters/bigquery/type_converter.py", # BigQuery type converter
+  "sqlspec/adapters/duckdb/type_converter.py",   # DuckDB type converter
+  "sqlspec/adapters/oracledb/type_converter.py", # Oracle type converter
+  "sqlspec/adapters/psqlpy/type_converter.py",   # Psqlpy type converter
+
   # === UTILITY MODULES ===
   "sqlspec/utils/text.py",                # Text utilities
   "sqlspec/utils/sync_tools.py",          # Synchronous utility functions

sqlspec-0.26.0/sqlspec/_serialization.py

@@ -0,0 +1,279 @@
+"""Enhanced serialization module with byte-aware encoding and class-based architecture.
+
+Provides a Protocol-based serialization system that users can extend.
+Supports msgspec, orjson, and standard library JSON with automatic fallback.
+"""
+
+import contextlib
+import datetime
+import enum
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Final, Literal, Optional, Protocol, Union, overload
+
+from sqlspec.typing import MSGSPEC_INSTALLED, ORJSON_INSTALLED, PYDANTIC_INSTALLED, BaseModel
+
+
+def _type_to_string(value: Any) -> str:  # pragma: no cover
+    """Convert special types to strings for JSON serialization.
+
+    Args:
+        value: Value to convert.
+
+    Returns:
+        String representation of the value.
+    """
+    if isinstance(value, datetime.datetime):
+        return convert_datetime_to_gmt_iso(value)
+    if isinstance(value, datetime.date):
+        return convert_date_to_iso(value)
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    if PYDANTIC_INSTALLED and isinstance(value, BaseModel):
+        return value.model_dump_json()
+    try:
+        return str(value)
+    except Exception as exc:
+        raise TypeError from exc
+
+
+class JSONSerializer(Protocol):
+    """Protocol for JSON serialization implementations.
+
+    Users can implement this protocol to create custom serializers.
+    """
+
+    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+        """Encode data to JSON.
+
+        Args:
+            data: Data to encode.
+            as_bytes: Whether to return bytes instead of string.
+
+        Returns:
+            JSON string or bytes depending on as_bytes parameter.
+        """
+        ...
+
+    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+        """Decode from JSON.
+
+        Args:
+            data: JSON string or bytes to decode.
+            decode_bytes: Whether to decode bytes input.
+
+        Returns:
+            Decoded Python object.
+        """
+        ...
+
+
+class BaseJSONSerializer(ABC):
+    """Base class for JSON serializers with common functionality."""
+
+    __slots__ = ()
+
+    @abstractmethod
+    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+        """Encode data to JSON."""
+        ...
+
+    @abstractmethod
+    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+        """Decode from JSON."""
+        ...
+
+
+class MsgspecSerializer(BaseJSONSerializer):
+    """Msgspec-based JSON serializer for optimal performance."""
+
+    __slots__ = ("_decoder", "_encoder")
+
+    def __init__(self) -> None:
+        """Initialize msgspec encoder and decoder."""
+        from msgspec.json import Decoder, Encoder
+
+        self._encoder: Final[Encoder] = Encoder(enc_hook=_type_to_string)
+        self._decoder: Final[Decoder] = Decoder()
+
+    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+        """Encode data using msgspec."""
+        try:
+            if as_bytes:
+                return self._encoder.encode(data)
+            return self._encoder.encode(data).decode("utf-8")
+        except (TypeError, ValueError):
+            if ORJSON_INSTALLED:
+                return OrjsonSerializer().encode(data, as_bytes=as_bytes)
+            return StandardLibSerializer().encode(data, as_bytes=as_bytes)
+
+    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+        """Decode data using msgspec."""
+        if isinstance(data, bytes):
+            if decode_bytes:
+                try:
+                    return self._decoder.decode(data)
+                except (TypeError, ValueError):
+                    if ORJSON_INSTALLED:
+                        return OrjsonSerializer().decode(data, decode_bytes=decode_bytes)
+                    return StandardLibSerializer().decode(data, decode_bytes=decode_bytes)
+            return data
+
+        try:
+            return self._decoder.decode(data.encode("utf-8"))
+        except (TypeError, ValueError):
+            if ORJSON_INSTALLED:
+                return OrjsonSerializer().decode(data, decode_bytes=decode_bytes)
+            return StandardLibSerializer().decode(data, decode_bytes=decode_bytes)
+
+
+class OrjsonSerializer(BaseJSONSerializer):
+    """Orjson-based JSON serializer with native datetime/UUID support."""
+
+    __slots__ = ()
+
+    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+        """Encode data using orjson."""
+        from orjson import (
+            OPT_NAIVE_UTC,  # pyright: ignore[reportUnknownVariableType]
+            OPT_SERIALIZE_NUMPY,  # pyright: ignore[reportUnknownVariableType]
+            OPT_SERIALIZE_UUID,  # pyright: ignore[reportUnknownVariableType]
+        )
+        from orjson import dumps as _orjson_dumps  # pyright: ignore[reportMissingImports]
+
+        result = _orjson_dumps(
+            data, default=_type_to_string, option=OPT_SERIALIZE_NUMPY | OPT_NAIVE_UTC | OPT_SERIALIZE_UUID
+        )
+        return result if as_bytes else result.decode("utf-8")
+
+    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+        """Decode data using orjson."""
+        from orjson import loads as _orjson_loads  # pyright: ignore[reportMissingImports]
+
+        if isinstance(data, bytes):
+            if decode_bytes:
+                return _orjson_loads(data)
+            return data
+        return _orjson_loads(data)
+
+
+class StandardLibSerializer(BaseJSONSerializer):
+    """Standard library JSON serializer as fallback."""
+
+    __slots__ = ()
+
+    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+        """Encode data using standard library json."""
+        json_str = json.dumps(data, default=_type_to_string)
+        return json_str.encode("utf-8") if as_bytes else json_str
+
+    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+        """Decode data using standard library json."""
+        if isinstance(data, bytes):
+            if decode_bytes:
+                return json.loads(data.decode("utf-8"))
+            return data
+        return json.loads(data)
+
+
+_default_serializer: Optional[JSONSerializer] = None
+
+
+def get_default_serializer() -> JSONSerializer:
+    """Get the default serializer based on available libraries.
+
+    Priority: msgspec > orjson > stdlib
+
+    Returns:
+        The best available JSON serializer.
+    """
+    global _default_serializer
+
+    if _default_serializer is None:
+        if MSGSPEC_INSTALLED:
+            with contextlib.suppress(ImportError):
+                _default_serializer = MsgspecSerializer()
+
+        if _default_serializer is None and ORJSON_INSTALLED:
+            with contextlib.suppress(ImportError):
+                _default_serializer = OrjsonSerializer()
+
+        if _default_serializer is None:
+            _default_serializer = StandardLibSerializer()
+
+    assert _default_serializer is not None
+    return _default_serializer
+
+
+@overload
+def encode_json(data: Any, *, as_bytes: Literal[False] = ...) -> str: ...  # pragma: no cover
+
+
+@overload
+def encode_json(data: Any, *, as_bytes: Literal[True]) -> bytes: ...  # pragma: no cover
+
+
+def encode_json(data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+    """Encode to JSON, optionally returning bytes for optimal performance.
+
+    Args:
+        data: The data to encode.
+        as_bytes: Whether to return bytes instead of string.
+
+    Returns:
+        JSON string or bytes depending on as_bytes parameter.
+    """
+    return get_default_serializer().encode(data, as_bytes=as_bytes)
+
+
+def decode_json(data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    """Decode from JSON string or bytes efficiently.
+
+    Args:
+        data: JSON string or bytes to decode.
+        decode_bytes: Whether to decode bytes input.
+
+    Returns:
+        Decoded Python object.
+    """
+    return get_default_serializer().decode(data, decode_bytes=decode_bytes)
+
+
+def convert_datetime_to_gmt_iso(dt: datetime.datetime) -> str:  # pragma: no cover
+    """Handle datetime serialization for nested timestamps.
+
+    Args:
+        dt: The datetime to convert.
+
+    Returns:
+        The ISO formatted datetime string.
+    """
+    if not dt.tzinfo:
+        dt = dt.replace(tzinfo=datetime.timezone.utc)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def convert_date_to_iso(dt: datetime.date) -> str:  # pragma: no cover
+    """Handle datetime serialization for nested timestamps.
+
+    Args:
+        dt: The date to convert.
+
+    Returns:
+        The ISO formatted date string.
+    """
+    return dt.isoformat()
+
+
+__all__ = (
+    "BaseJSONSerializer",
+    "JSONSerializer",
+    "MsgspecSerializer",
+    "OrjsonSerializer",
+    "StandardLibSerializer",
+    "convert_date_to_iso",
+    "convert_datetime_to_gmt_iso",
+    "decode_json",
+    "encode_json",
+    "get_default_serializer",
+)

{sqlspec-0.25.0 → sqlspec-0.26.0}/sqlspec/_sql.py

@@ -40,6 +40,7 @@ from sqlspec.builder._expression_wrappers import (
     MathExpression,
     StringExpression,
 )
+from sqlspec.builder._parsing_utils import extract_expression, to_expression
 from sqlspec.builder.mixins._join_operations import JoinBuilder
 from sqlspec.builder.mixins._select_operations import Case, SubqueryBuilder, WindowFunctionBuilder
 from sqlspec.core.statement import SQL
@@ -746,7 +747,7 @@ class SQLFactory:
         if isinstance(column, str) and column == "*":
             expr = exp.Count(this=exp.Star(), distinct=distinct)
         else:
-            col_expr = self._extract_expression(column)
+            col_expr = extract_expression(column)
             expr = exp.Count(this=col_expr, distinct=distinct)
         return AggregateExpression(expr)
 
@@ -774,7 +775,7 @@ class SQLFactory:
         Returns:
             SUM expression.
         """
-        col_expr = SQLFactory._extract_expression(column)
+        col_expr = extract_expression(column)
         return AggregateExpression(exp.Sum(this=col_expr, distinct=distinct))
 
     @staticmethod
@@ -787,7 +788,7 @@ class SQLFactory:
         Returns:
             AVG expression.
         """
-        col_expr = SQLFactory._extract_expression(column)
+        col_expr = extract_expression(column)
         return AggregateExpression(exp.Avg(this=col_expr))
 
     @staticmethod
@@ -800,7 +801,7 @@ class SQLFactory:
         Returns:
             MAX expression.
         """
-        col_expr = SQLFactory._extract_expression(column)
+        col_expr = extract_expression(column)
         return AggregateExpression(exp.Max(this=col_expr))
 
     @staticmethod
@@ -813,7 +814,7 @@ class SQLFactory:
         Returns:
             MIN expression.
         """
-        col_expr = SQLFactory._extract_expression(column)
+        col_expr = extract_expression(column)
         return AggregateExpression(exp.Min(this=col_expr))
 
     @staticmethod
@@ -1034,45 +1035,6 @@ class SQLFactory:
             return FunctionExpression(value)
         return FunctionExpression(exp.convert(value))
 
-    @staticmethod
-    def _to_expression(value: Any) -> exp.Expression:
-        """Convert a Python value to a raw SQLGlot expression.
-
-        Args:
-            value: Python value or SQLGlot expression to convert.
-
-        Returns:
-            Raw SQLGlot expression.
-        """
-        if isinstance(value, exp.Expression):
-            return value
-        return exp.convert(value)
-
-    @staticmethod
-    def _extract_expression(value: Any) -> exp.Expression:
-        """Extract SQLGlot expression from value, handling our wrapper types.
-
-        Args:
-            value: String, SQLGlot expression, or our wrapper type.
-
-        Returns:
-            Raw SQLGlot expression.
-        """
-        from sqlspec.builder._expression_wrappers import ExpressionWrapper
-        from sqlspec.builder.mixins._select_operations import Case
-
-        if isinstance(value, str):
-            return exp.column(value)
-        if isinstance(value, Column):
-            return value.sqlglot_expression
-        if isinstance(value, ExpressionWrapper):
-            return value.expression
-        if isinstance(value, Case):
-            return exp.Case(ifs=value.conditions, default=value.default)
-        if isinstance(value, exp.Expression):
-            return value
-        return exp.convert(value)
-
     @staticmethod
     def decode(column: Union[str, exp.Expression], *args: Union[str, exp.Expression, Any]) -> FunctionExpression:
         """Create a DECODE expression (Oracle-style conditional logic).
@@ -1109,14 +1071,14 @@ class SQLFactory:
 
         for i in range(0, len(args) - 1, 2):
             if i + 1 >= len(args):
-                default = SQLFactory._to_expression(args[i])
+                default = to_expression(args[i])
                 break
 
             search_val = args[i]
             result_val = args[i + 1]
 
-            search_expr = SQLFactory._to_expression(search_val)
-            result_expr = SQLFactory._to_expression(result_val)
+            search_expr = to_expression(search_val)
+            result_expr = to_expression(result_val)
 
             condition = exp.EQ(this=col_expr, expression=search_expr)
             conditions.append(exp.If(this=condition, true=result_expr))
@@ -1164,7 +1126,7 @@ class SQLFactory:
             COALESCE expression equivalent to NVL.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        sub_expr = SQLFactory._to_expression(substitute_value)
+        sub_expr = to_expression(substitute_value)
         return ConversionExpression(exp.Coalesce(expressions=[col_expr, sub_expr]))
 
     @staticmethod
@@ -1192,8 +1154,8 @@ class SQLFactory:
             ```
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        not_null_expr = SQLFactory._to_expression(value_if_not_null)
-        null_expr = SQLFactory._to_expression(value_if_null)
+        not_null_expr = to_expression(value_if_not_null)
+        null_expr = to_expression(value_if_null)
 
         is_null = exp.Is(this=col_expr, expression=exp.Null())
         condition = exp.Not(this=is_null)

{sqlspec-0.25.0 → sqlspec-0.26.0}/sqlspec/_typing.py

@@ -177,6 +177,14 @@ except ImportError:
     MSGSPEC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
 
 
+try:
+    import orjson  # noqa: F401
+
+    ORJSON_INSTALLED = True  # pyright: ignore[reportConstantRedefinition]
+except ImportError:
+    ORJSON_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+
 # Always define stub type for DTOData
 @runtime_checkable
 class DTODataStub(Protocol[T]):
@@ -621,6 +629,7 @@ __all__ = (
     "NUMPY_INSTALLED",
     "OBSTORE_INSTALLED",
     "OPENTELEMETRY_INSTALLED",
+    "ORJSON_INSTALLED",
     "PGVECTOR_INSTALLED",
     "PROMETHEUS_INSTALLED",
     "PYARROW_INSTALLED",

{sqlspec-0.25.0 → sqlspec-0.26.0}/sqlspec/adapters/adbc/config.py

@@ -77,6 +77,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         migration_config: Optional[dict[str, Any]] = None,
         statement_config: Optional[StatementConfig] = None,
         driver_features: Optional[dict[str, Any]] = None,
+        bind_key: Optional[str] = None,
     ) -> None:
         """Initialize configuration.
 
@@ -85,6 +86,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
             migration_config: Migration configuration
             statement_config: Default SQL statement configuration
             driver_features: Driver feature configuration
+            bind_key: Optional unique identifier for this configuration
         """
         if connection_config is None:
             connection_config = {}
@@ -104,6 +106,7 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
             migration_config=migration_config,
             statement_config=statement_config,
             driver_features=driver_features or {},
+            bind_key=bind_key,
         )
 
     def _resolve_driver_name(self) -> str:
@@ -174,7 +177,11 @@ class AdbcConfig(NoPoolSyncConfig[AdbcConnection, AdbcDriver]):
         try:
             connect_func = import_string(driver_path)
         except ImportError as e:
-            driver_path_with_suffix = f"{driver_path}.dbapi.connect"
+            # Only add .dbapi.connect if it's not already there
+            if not driver_path.endswith(".dbapi.connect"):
+                driver_path_with_suffix = f"{driver_path}.dbapi.connect"
+            else:
+                driver_path_with_suffix = driver_path
             try:
                 connect_func = import_string(driver_path_with_suffix)
             except ImportError as e2: