sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/utils/fixtures.py

@@ -7,7 +7,7 @@ used in testing and development. Supports both sync and async operations.
 import gzip
 import zipfile
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Union
+from typing import TYPE_CHECKING, Any
 
 from sqlspec.storage import storage_registry
 from sqlspec.utils.serializers import from_json as decode_json
@@ -16,7 +16,7 @@ from sqlspec.utils.sync_tools import async_
 from sqlspec.utils.type_guards import schema_dump
 
 if TYPE_CHECKING:
-    from sqlspec.typing import ModelDictList, SupportedSchemaModel
+    from sqlspec.typing import SupportedSchemaModel
 
 __all__ = ("open_fixture", "open_fixture_async", "write_fixture", "write_fixture_async")
 
@@ -171,7 +171,7 @@ def _serialize_data(data: Any) -> str:
 def write_fixture(
     fixtures_path: str,
     table_name: str,
-    data: "Union[ModelDictList, list[dict[str, Any]], SupportedSchemaModel]",
+    data: "list[SupportedSchemaModel] | list[dict[str, Any]] | SupportedSchemaModel",
     storage_backend: str = "local",
     compress: bool = False,
     **storage_kwargs: Any,
@@ -219,7 +219,7 @@ def write_fixture(
 async def write_fixture_async(
     fixtures_path: str,
     table_name: str,
-    data: "Union[ModelDictList, list[dict[str, Any]], SupportedSchemaModel]",
+    data: "list[SupportedSchemaModel] | list[dict[str, Any]] | SupportedSchemaModel",
     storage_backend: str = "local",
     compress: bool = False,
     **storage_kwargs: Any,

sqlspec/utils/logging.py

@@ -8,16 +8,24 @@ SQLSpec provides StructuredFormatter for JSON-formatted logs if desired.
 import logging
 from contextvars import ContextVar
 from logging import LogRecord
-from typing import Any, Optional
+from typing import Any
 
 from sqlspec._serialization import encode_json
 
-__all__ = ("StructuredFormatter", "correlation_id_var", "get_correlation_id", "get_logger", "set_correlation_id")
+__all__ = (
+    "SqlglotCommandFallbackFilter",
+    "StructuredFormatter",
+    "correlation_id_var",
+    "get_correlation_id",
+    "get_logger",
+    "set_correlation_id",
+    "suppress_erroneous_sqlglot_log_messages",
+)
 
-correlation_id_var: "ContextVar[Optional[str]]" = ContextVar("correlation_id", default=None)
+correlation_id_var: "ContextVar[str | None]" = ContextVar("correlation_id", default=None)
 
 
-def set_correlation_id(correlation_id: "Optional[str]") -> None:
+def set_correlation_id(correlation_id: "str | None") -> None:
     """Set the correlation ID for the current context.
 
     Args:
@@ -26,7 +34,7 @@ def set_correlation_id(correlation_id: "Optional[str]") -> None:
     correlation_id_var.set(correlation_id)
 
 
-def get_correlation_id() -> "Optional[str]":
+def get_correlation_id() -> "str | None":
     """Get the current correlation ID.
 
     Returns:
@@ -86,7 +94,27 @@ class CorrelationIDFilter(logging.Filter):
         return True
 
 
-def get_logger(name: "Optional[str]" = None) -> logging.Logger:
+class SqlglotCommandFallbackFilter(logging.Filter):
+    """Filter to suppress sqlglot's confusing 'Falling back to Command' warning.
+
+    This filter suppresses the warning message that sqlglot emits when it
+    encounters unsupported syntax and falls back to parsing as a Command.
+    This is expected behavior in SQLSpec and the warning is confusing to users.
+    """
+
+    def filter(self, record: LogRecord) -> bool:
+        """Suppress the 'Falling back to Command' warning message.
+
+        Args:
+            record: The log record to evaluate
+
+        Returns:
+            False if the record contains the fallback warning, True otherwise
+        """
+        return "Falling back to parsing as a 'Command'" not in record.getMessage()
+
+
+def get_logger(name: "str | None" = None) -> logging.Logger:
     """Get a logger instance with standardized configuration.
 
     Args:
@@ -121,3 +149,15 @@ def log_with_context(logger: logging.Logger, level: int, message: str, **extra_f
     record = logger.makeRecord(logger.name, level, "(unknown file)", 0, message, (), None)
     record.extra_fields = extra_fields
     logger.handle(record)
+
+
+def suppress_erroneous_sqlglot_log_messages() -> None:
+    """Suppress confusing sqlglot warning messages.
+
+    Adds a filter to the sqlglot logger to suppress the warning message
+    about falling back to parsing as a Command. This is expected behavior
+    in SQLSpec and the warning is confusing to users.
+    """
+    sqlglot_logger = logging.getLogger("sqlglot")
+    if not any(isinstance(f, SqlglotCommandFallbackFilter) for f in sqlglot_logger.filters):
+        sqlglot_logger.addFilter(SqlglotCommandFallbackFilter())

sqlspec/utils/module_loader.py

@@ -7,7 +7,7 @@ Used for loading modules from dotted paths and converting module paths to filesy
 import importlib
 from importlib.util import find_spec
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 __all__ = ("import_string", "module_to_os_path")
 
@@ -46,7 +46,7 @@ def import_string(dotted_path: str) -> "Any":
         The imported object.
     """
 
-    def _raise_import_error(msg: str, exc: "Optional[Exception]" = None) -> None:
+    def _raise_import_error(msg: str, exc: "Exception | None" = None) -> None:
         if exc is not None:
             raise ImportError(msg) from exc
         raise ImportError(msg)

sqlspec/utils/schema.py

@@ -0,0 +1,288 @@
+"""Schema transformation utilities for converting data to various schema types."""
+
+import datetime
+import logging
+from collections.abc import Callable, Sequence
+from enum import Enum
+from functools import lru_cache, partial
+from pathlib import Path, PurePath
+from typing import Any, Final, TypeGuard, overload
+from uuid import UUID
+
+from typing_extensions import TypeVar
+
+from sqlspec.exceptions import SQLSpecError
+from sqlspec.typing import (
+    CATTRS_INSTALLED,
+    NUMPY_INSTALLED,
+    SchemaT,
+    attrs_asdict,
+    cattrs_structure,
+    cattrs_unstructure,
+    convert,
+    get_type_adapter,
+)
+from sqlspec.utils.data_transformation import transform_dict_keys
+from sqlspec.utils.text import camelize, kebabize, pascalize
+from sqlspec.utils.type_guards import (
+    get_msgspec_rename_config,
+    is_attrs_schema,
+    is_dataclass,
+    is_dict,
+    is_msgspec_struct,
+    is_pydantic_model,
+    is_typed_dict,
+)
+
+__all__ = (
+    "_DEFAULT_TYPE_DECODERS",
+    "DataT",
+    "_convert_numpy_to_list",
+    "_default_msgspec_deserializer",
+    "_is_list_type_target",
+    "to_schema",
+)
+
+DataT = TypeVar("DataT", default=dict[str, Any])
+
+logger = logging.getLogger(__name__)
+
+_DATETIME_TYPES: Final[set[type]] = {datetime.datetime, datetime.date, datetime.time}
+
+
+def _is_list_type_target(target_type: Any) -> TypeGuard[list[object]]:
+    """Check if target type is a list type (e.g., list[float])."""
+    try:
+        return hasattr(target_type, "__origin__") and target_type.__origin__ is list
+    except (AttributeError, TypeError):
+        return False
+
+
+def _convert_numpy_to_list(target_type: Any, value: Any) -> Any:
+    """Convert numpy array to list if target is a list type."""
+    if not NUMPY_INSTALLED:
+        return value
+
+    import numpy as np
+
+    if isinstance(value, np.ndarray) and _is_list_type_target(target_type):
+        return value.tolist()
+
+    return value
+
+
+@lru_cache(maxsize=128)
+def _detect_schema_type(schema_type: type) -> "str | None":
+    """Detect schema type with LRU caching.
+
+    Args:
+        schema_type: Type to detect
+
+    Returns:
+        Type identifier string or None if unsupported
+    """
+    return (
+        "typed_dict"
+        if is_typed_dict(schema_type)
+        else "dataclass"
+        if is_dataclass(schema_type)
+        else "msgspec"
+        if is_msgspec_struct(schema_type)
+        else "pydantic"
+        if is_pydantic_model(schema_type)
+        else "attrs"
+        if is_attrs_schema(schema_type)
+        else None
+    )
+
+
+def _convert_typed_dict(data: Any, schema_type: Any) -> Any:
+    """Convert data to TypedDict."""
+    return [item for item in data if is_dict(item)] if isinstance(data, list) else data
+
+
+def _convert_dataclass(data: Any, schema_type: Any) -> Any:
+    """Convert data to dataclass."""
+    if isinstance(data, list):
+        return [schema_type(**dict(item)) if is_dict(item) else item for item in data]
+    return schema_type(**dict(data)) if is_dict(data) else (schema_type(**data) if isinstance(data, dict) else data)
+
+
+_DEFAULT_TYPE_DECODERS: Final["list[tuple[Callable[[Any], bool], Callable[[Any, Any], Any]]]"] = [
+    (lambda x: x is UUID, lambda t, v: t(v.hex)),
+    (lambda x: x is datetime.datetime, lambda t, v: t(v.isoformat())),
+    (lambda x: x is datetime.date, lambda t, v: t(v.isoformat())),
+    (lambda x: x is datetime.time, lambda t, v: t(v.isoformat())),
+    (lambda x: x is Enum, lambda t, v: t(v.value)),
+    (_is_list_type_target, _convert_numpy_to_list),
+]
+
+
+def _default_msgspec_deserializer(
+    target_type: Any, value: Any, type_decoders: "Sequence[tuple[Any, Any]] | None" = None
+) -> Any:
+    """Convert msgspec types with type decoder support.
+
+    Args:
+        target_type: Type to convert to
+        value: Value to convert
+        type_decoders: Optional sequence of (predicate, decoder) pairs
+
+    Returns:
+        Converted value or original value if conversion not applicable
+    """
+    if NUMPY_INSTALLED:
+        import numpy as np
+
+        if isinstance(value, np.ndarray) and _is_list_type_target(target_type):
+            return value.tolist()
+
+    if type_decoders:
+        for predicate, decoder in type_decoders:
+            if predicate(target_type):
+                return decoder(target_type, value)
+
+    if target_type is UUID and isinstance(value, UUID):
+        return value.hex
+
+    if target_type in _DATETIME_TYPES and hasattr(value, "isoformat"):
+        return value.isoformat()  # pyright: ignore
+
+    if isinstance(target_type, type) and issubclass(target_type, Enum) and isinstance(value, Enum):
+        return value.value
+
+    try:
+        if isinstance(target_type, type) and isinstance(value, target_type):
+            return value
+    except TypeError:
+        pass
+
+    if isinstance(target_type, type):
+        try:
+            if issubclass(target_type, (Path, PurePath)) or issubclass(target_type, UUID):
+                return target_type(str(value))
+        except (TypeError, ValueError):
+            pass
+
+    return value
+
+
+def _convert_msgspec(data: Any, schema_type: Any) -> Any:
+    """Convert data to msgspec Struct."""
+    rename_config = get_msgspec_rename_config(schema_type)
+    deserializer = partial(_default_msgspec_deserializer, type_decoders=_DEFAULT_TYPE_DECODERS)
+
+    transformed_data = data
+    if (rename_config and is_dict(data)) or (isinstance(data, Sequence) and data and is_dict(data[0])):
+        try:
+            converter_map: dict[str, Callable[[str], str]] = {"camel": camelize, "kebab": kebabize, "pascal": pascalize}
+            converter = converter_map.get(rename_config) if rename_config else None
+            if converter:
+                transformed_data = (
+                    [transform_dict_keys(item, converter) if is_dict(item) else item for item in data]
+                    if isinstance(data, Sequence)
+                    else (transform_dict_keys(data, converter) if is_dict(data) else data)
+                )
+        except Exception as e:
+            logger.debug("Field name transformation failed for msgspec schema: %s", e)
+
+    if NUMPY_INSTALLED:
+        try:
+            import numpy as np
+
+            def _convert_numpy(obj: Any) -> Any:
+                return (
+                    obj.tolist()
+                    if isinstance(obj, np.ndarray)
+                    else {k: _convert_numpy(v) for k, v in obj.items()}
+                    if isinstance(obj, dict)
+                    else type(obj)(_convert_numpy(item) for item in obj)
+                    if isinstance(obj, (list, tuple))
+                    else obj
+                )
+
+            transformed_data = _convert_numpy(transformed_data)
+        except ImportError:
+            pass
+
+    return convert(
+        obj=transformed_data,
+        type=(list[schema_type] if isinstance(transformed_data, Sequence) else schema_type),
+        from_attributes=True,
+        dec_hook=deserializer,
+    )
+
+
+def _convert_pydantic(data: Any, schema_type: Any) -> Any:
+    """Convert data to Pydantic model."""
+    if isinstance(data, Sequence):
+        return get_type_adapter(list[schema_type]).validate_python(data, from_attributes=True)
+    return get_type_adapter(schema_type).validate_python(data, from_attributes=True)
+
+
+def _convert_attrs(data: Any, schema_type: Any) -> Any:
+    """Convert data to attrs class."""
+    if CATTRS_INSTALLED:
+        if isinstance(data, Sequence):
+            return cattrs_structure(data, list[schema_type])
+        return cattrs_structure(cattrs_unstructure(data) if hasattr(data, "__attrs_attrs__") else data, schema_type)
+
+    if isinstance(data, list):
+        return [
+            schema_type(**dict(item)) if hasattr(item, "keys") else schema_type(**attrs_asdict(item)) for item in data
+        ]
+    return (
+        schema_type(**dict(data))
+        if hasattr(data, "keys")
+        else (schema_type(**data) if isinstance(data, dict) else data)
+    )
+
+
+_SCHEMA_CONVERTERS: "dict[str, Callable[[Any, Any], Any]]" = {
+    "typed_dict": _convert_typed_dict,
+    "dataclass": _convert_dataclass,
+    "msgspec": _convert_msgspec,
+    "pydantic": _convert_pydantic,
+    "attrs": _convert_attrs,
+}
+
+
+@overload
+def to_schema(data: "list[DataT]", *, schema_type: "type[SchemaT]") -> "list[SchemaT]": ...
+@overload
+def to_schema(data: "list[DataT]", *, schema_type: None = None) -> "list[DataT]": ...
+@overload
+def to_schema(data: "DataT", *, schema_type: "type[SchemaT]") -> "SchemaT": ...
+@overload
+def to_schema(data: "DataT", *, schema_type: None = None) -> "DataT": ...
+
+
+def to_schema(data: Any, *, schema_type: Any = None) -> Any:
+    """Convert data to a specified schema type.
+
+    Supports transformation to various schema types including:
+    - TypedDict
+    - dataclasses
+    - msgspec Structs
+    - Pydantic models
+    - attrs classes
+
+    Args:
+        data: Input data to convert (dict, list of dicts, or other)
+        schema_type: Target schema type for conversion. If None, returns data unchanged.
+
+    Returns:
+        Converted data in the specified schema type, or original data if schema_type is None
+
+    Raises:
+        SQLSpecError: If schema_type is not a supported type
+    """
+    if schema_type is None:
+        return data
+
+    schema_type_key = _detect_schema_type(schema_type)
+    if schema_type_key is None:
+        msg = "`schema_type` should be a valid Dataclass, Pydantic model, Msgspec struct, Attrs class, or TypedDict"
+        raise SQLSpecError(msg)
+
+    return _SCHEMA_CONVERTERS[schema_type_key](data, schema_type)

sqlspec/utils/serializers.py

@@ -4,7 +4,55 @@ Re-exports common JSON encoding and decoding functions from the core
 serialization module for convenient access.
 """
 
-from sqlspec._serialization import decode_json as from_json
-from sqlspec._serialization import encode_json as to_json
+from typing import Any, Literal, overload
+
+from sqlspec._serialization import decode_json, encode_json
+
+
+@overload
+def to_json(data: Any, *, as_bytes: Literal[False] = ...) -> str: ...
+
+
+@overload
+def to_json(data: Any, *, as_bytes: Literal[True]) -> bytes: ...
+
+
+def to_json(data: Any, *, as_bytes: bool = False) -> str | bytes:
+    """Encode data to JSON string or bytes.
+
+    Args:
+        data: Data to encode.
+        as_bytes: Whether to return bytes instead of string for optimal performance.
+
+    Returns:
+        JSON string or bytes representation based on as_bytes parameter.
+    """
+    if as_bytes:
+        return encode_json(data, as_bytes=True)
+    return encode_json(data, as_bytes=False)
+
+
+@overload
+def from_json(data: str) -> Any: ...
+
+
+@overload
+def from_json(data: bytes, *, decode_bytes: bool = ...) -> Any: ...
+
+
+def from_json(data: str | bytes, *, decode_bytes: bool = True) -> Any:
+    """Decode JSON string or bytes to Python object.
+
+    Args:
+        data: JSON string or bytes to decode.
+        decode_bytes: Whether to decode bytes input (vs passing through).
+
+    Returns:
+        Decoded Python object.
+    """
+    if isinstance(data, bytes):
+        return decode_json(data, decode_bytes=decode_bytes)
+    return decode_json(data)
+
 
 __all__ = ("from_json", "to_json")

sqlspec/utils/sync_tools.py

@@ -8,9 +8,10 @@ for adapter implementations that need to support both sync and async patterns.
 import asyncio
 import functools
 import inspect
+import os
 import sys
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
-from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar, Union, cast
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
 from typing_extensions import ParamSpec
 
@@ -46,13 +47,21 @@ class CapacityLimiter:
             total_tokens: Maximum number of concurrent operations allowed
         """
         self._total_tokens = total_tokens
-        self._semaphore_instance: Optional[asyncio.Semaphore] = None
+        self._semaphore_instance: asyncio.Semaphore | None = None
+        self._pid: int | None = None
 
     @property
     def _semaphore(self) -> asyncio.Semaphore:
-        """Lazy initialization of asyncio.Semaphore for Python 3.9 compatibility."""
-        if self._semaphore_instance is None:
+        """Lazy initialization of asyncio.Semaphore with per-process tracking.
+
+        Reinitializes the semaphore if running in a new process (detected via PID).
+        This ensures pytest-xdist workers each get their own semaphore bound to
+        their event loop, preventing cross-process deadlocks.
+        """
+        current_pid = os.getpid()
+        if self._semaphore_instance is None or self._pid != current_pid:
             self._semaphore_instance = asyncio.Semaphore(self._total_tokens)
+            self._pid = current_pid
         return self._semaphore_instance
 
     async def acquire(self) -> None:
@@ -72,22 +81,20 @@ class CapacityLimiter:
     def total_tokens(self, value: int) -> None:
         self._total_tokens = value
         self._semaphore_instance = None
+        self._pid = None
 
     async def __aenter__(self) -> None:
         """Async context manager entry."""
         await self.acquire()
 
     async def __aexit__(
-        self,
-        exc_type: "Optional[type[BaseException]]",
-        exc_val: "Optional[BaseException]",
-        exc_tb: "Optional[TracebackType]",
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
     ) -> None:
         """Async context manager exit."""
         self.release()
 
 
-_default_limiter = CapacityLimiter(15)
+_default_limiter = CapacityLimiter(1000)
 
 
 def run_(async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -> "Callable[ParamSpecT, ReturnT]":
@@ -169,7 +176,7 @@ def await_(
 
 
 def async_(
-    function: "Callable[ParamSpecT, ReturnT]", *, limiter: "Optional[CapacityLimiter]" = None
+    function: "Callable[ParamSpecT, ReturnT]", *, limiter: "CapacityLimiter | None" = None
 ) -> "Callable[ParamSpecT, Awaitable[ReturnT]]":
     """Convert a blocking function to an async one using asyncio.to_thread().
 
@@ -192,7 +199,7 @@ def async_(
 
 
 def ensure_async_(
-    function: "Callable[ParamSpecT, Union[Awaitable[ReturnT], ReturnT]]",
+    function: "Callable[ParamSpecT, Awaitable[ReturnT] | ReturnT]",
 ) -> "Callable[ParamSpecT, Awaitable[ReturnT]]":
     """Convert a function to an async one if it is not already.
 
@@ -223,16 +230,13 @@ class _ContextManagerWrapper(Generic[T]):
         return self._cm.__enter__()
 
     async def __aexit__(
-        self,
-        exc_type: "Optional[type[BaseException]]",
-        exc_val: "Optional[BaseException]",
-        exc_tb: "Optional[TracebackType]",
-    ) -> "Optional[bool]":
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> "bool | None":
         return self._cm.__exit__(exc_type, exc_val, exc_tb)
 
 
 def with_ensure_async_(
-    obj: "Union[AbstractContextManager[T], AbstractAsyncContextManager[T]]",
+    obj: "AbstractContextManager[T] | AbstractAsyncContextManager[T]",
 ) -> "AbstractAsyncContextManager[T]":
     """Convert a context manager to an async one if it is not already.
 

sqlspec/utils/text.py

@@ -8,7 +8,6 @@ generation and data validation.
 import re
 import unicodedata
 from functools import lru_cache
-from typing import Optional
 
 _SLUGIFY_REMOVE_NON_ALPHANUMERIC = re.compile(r"[^\w]+", re.UNICODE)
 _SLUGIFY_HYPHEN_COLLAPSE = re.compile(r"-+")
@@ -22,7 +21,7 @@ _SNAKE_CASE_MULTIPLE_UNDERSCORES = re.compile(r"__+", re.UNICODE)
 __all__ = ("camelize", "kebabize", "pascalize", "slugify", "snake_case")
 
 
-def slugify(value: str, allow_unicode: bool = False, separator: Optional[str] = None) -> str:
+def slugify(value: str, allow_unicode: bool = False, separator: str | None = None) -> str:
     """Convert a string to a URL-friendly slug.
 
     Args: