sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/__init__.py

@@ -0,0 +1,140 @@
+"""SQLSpec: Type-safe SQL query mapper for Python."""
+
+from sqlspec import adapters, base, builder, core, driver, exceptions, extensions, loader, migrations, typing, utils
+from sqlspec.__metadata__ import __version__
+from sqlspec.base import SQLSpec
+from sqlspec.builder import (
+    Column,
+    ColumnExpression,
+    CreateTable,
+    Delete,
+    DropTable,
+    FunctionColumn,
+    Insert,
+    Merge,
+    QueryBuilder,
+    Select,
+    SQLFactory,
+    Update,
+    sql,
+)
+from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
+from sqlspec.core import (
+    SQL,
+    ArrowResult,
+    CacheConfig,
+    CacheStats,
+    ParameterConverter,
+    ParameterProcessor,
+    ParameterStyle,
+    ParameterStyleConfig,
+    ProcessedState,
+    SQLResult,
+    StackOperation,
+    StackResult,
+    Statement,
+    StatementConfig,
+    StatementStack,
+)
+from sqlspec.core import filters as filters
+from sqlspec.driver import AsyncDriverAdapterBase, ExecutionResult, SyncDriverAdapterBase
+from sqlspec.exceptions import StackExecutionError
+from sqlspec.extensions.events import (
+    AsyncEventChannel,
+    AsyncEventListener,
+    EventMessage,
+    SyncEventChannel,
+    SyncEventListener,
+)
+from sqlspec.loader import SQLFile, SQLFileLoader
+from sqlspec.observability import (
+    LoggingConfig,
+    ObservabilityConfig,
+    ObservabilityRuntime,
+    RedactionConfig,
+    StatementEvent,
+    StatementObserver,
+    TelemetryConfig,
+    create_event,
+    create_statement_observer,
+    default_statement_observer,
+    format_statement_event,
+)
+from sqlspec.typing import ConnectionT, PoolT, SchemaT, StatementParameters, SupportedSchemaModel
+from sqlspec.utils.logging import suppress_erroneous_sqlglot_log_messages
+
+suppress_erroneous_sqlglot_log_messages()
+
+__all__ = (
+    "SQL",
+    "ArrowResult",
+    "AsyncDatabaseConfig",
+    "AsyncDriverAdapterBase",
+    "AsyncEventChannel",
+    "AsyncEventListener",
+    "CacheConfig",
+    "CacheStats",
+    "Column",
+    "ColumnExpression",
+    "ConnectionT",
+    "CreateTable",
+    "Delete",
+    "DropTable",
+    "EventMessage",
+    "ExecutionResult",
+    "FunctionColumn",
+    "Insert",
+    "LoggingConfig",
+    "Merge",
+    "ObservabilityConfig",
+    "ObservabilityRuntime",
+    "ParameterConverter",
+    "ParameterProcessor",
+    "ParameterStyle",
+    "ParameterStyleConfig",
+    "PoolT",
+    "ProcessedState",
+    "QueryBuilder",
+    "RedactionConfig",
+    "SQLFactory",
+    "SQLFile",
+    "SQLFileLoader",
+    "SQLResult",
+    "SQLSpec",
+    "SchemaT",
+    "Select",
+    "StackExecutionError",
+    "StackOperation",
+    "StackResult",
+    "Statement",
+    "StatementConfig",
+    "StatementEvent",
+    "StatementObserver",
+    "StatementParameters",
+    "StatementStack",
+    "SupportedSchemaModel",
+    "SyncDatabaseConfig",
+    "SyncDriverAdapterBase",
+    "SyncEventChannel",
+    "SyncEventListener",
+    "TelemetryConfig",
+    "Update",
+    "__version__",
+    "adapters",
+    "base",
+    "builder",
+    "core",
+    "create_event",
+    "create_statement_observer",
+    "default_statement_observer",
+    "driver",
+    "exceptions",
+    "extensions",
+    "filters",
+    "format_statement_event",
+    "loader",
+    "migrations",
+    "sql",
+    "typing",
+    "utils",
+)

sqlspec/__main__.py

@@ -0,0 +1,12 @@
+from sqlspec.cli import add_migration_commands as build_cli_interface
+
+__all__ = ("run_cli",)
+
+
+def run_cli() -> None:  # pragma: no cover
+    """SQLSpec CLI."""
+    build_cli_interface()()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

sqlspec/__metadata__.py

@@ -0,0 +1,14 @@
+"""Metadata for the project."""
+
+from importlib.metadata import PackageNotFoundError, metadata, version
+
+__all__ = ("__project__", "__version__")
+
+try:
+    __version__ = version("sqlspec")
+    __project__ = metadata("sqlspec")["Name"]
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.1"
+    __project__ = "SQLSpec"
+finally:
+    del version, PackageNotFoundError, metadata

sqlspec/_serialization.py

@@ -0,0 +1,315 @@
+"""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.
+
+Features optional numpy array serialization when numpy is installed.
+Arrays are automatically converted to lists during JSON encoding.
+"""
+
+import contextlib
+import datetime
+import enum
+import json
+from abc import ABC, abstractmethod
+from decimal import Decimal
+from typing import Any, Final, Literal, Protocol, overload
+
+from sqlspec._typing import NUMPY_INSTALLED
+from sqlspec.core.filters import OffsetPagination
+from sqlspec.typing import MSGSPEC_INSTALLED, ORJSON_INSTALLED, PYDANTIC_INSTALLED, BaseModel
+
+
+def _type_to_string(value: Any) -> Any:  # pragma: no cover
+    """Convert special types to strings for JSON serialization.
+
+    Handles datetime, date, enums, Decimal, Pydantic models, and numpy arrays.
+
+    Args:
+        value: Value to convert.
+
+    Returns:
+        Serializable representation of the value (string, list, dict, etc.).
+
+    Raises:
+        TypeError: If value cannot be serialized.
+    """
+    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, Decimal):
+        return float(value)
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    if PYDANTIC_INSTALLED and isinstance(value, BaseModel):
+        return value.model_dump_json()
+    if isinstance(value, OffsetPagination):
+        return {"items": value.items, "limit": value.limit, "offset": value.offset, "total": value.total}
+    if NUMPY_INSTALLED:
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            return value.tolist()
+    try:
+        return str(value)
+    except Exception as exc:
+        msg = f"Cannot serialize {type(value).__name__}"
+        raise TypeError(msg) 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) -> 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: 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) -> str | bytes:
+        """Encode data to JSON."""
+        ...
+
+    @abstractmethod
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
+        """Decode from JSON."""
+        ...
+
+
+class MsgspecSerializer(BaseJSONSerializer):
+    """Msgspec-based JSON serializer."""
+
+    __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) -> 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: 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.
+
+    Automatically enables numpy serialization if numpy is installed.
+    """
+
+    __slots__ = ()
+
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
+        """Encode data using orjson.
+
+        Args:
+            data: Data to encode.
+            as_bytes: Whether to return bytes instead of string.
+
+        Returns:
+            JSON string or bytes depending on as_bytes parameter.
+        """
+        from orjson import (
+            OPT_NAIVE_UTC,  # pyright: ignore[reportUnknownVariableType]
+            OPT_SERIALIZE_UUID,  # pyright: ignore[reportUnknownVariableType]
+        )
+        from orjson import dumps as _orjson_dumps  # pyright: ignore[reportMissingImports]
+
+        options = OPT_NAIVE_UTC | OPT_SERIALIZE_UUID
+
+        if NUMPY_INSTALLED:
+            from orjson import OPT_SERIALIZE_NUMPY  # pyright: ignore[reportUnknownVariableType]
+
+            options |= OPT_SERIALIZE_NUMPY
+
+        result = _orjson_dumps(data, default=_type_to_string, option=options)
+        return result if as_bytes else result.decode("utf-8")
+
+    def decode(self, data: 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) -> 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: 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: JSONSerializer | None = 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) -> str | bytes:
+    """Encode to JSON, optionally returning bytes.
+
+    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: 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",
+)