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

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,7 @@ Re-exports common JSON encoding and decoding functions from the core
 serialization module for convenient access.
 """
 
-from typing import Any, Literal, Union, overload
+from typing import Any, Literal, overload
 
 from sqlspec._serialization import decode_json, encode_json
 
@@ -17,7 +17,7 @@ def to_json(data: Any, *, as_bytes: Literal[False] = ...) -> str: ...
 def to_json(data: Any, *, as_bytes: Literal[True]) -> bytes: ...
 
 
-def to_json(data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+def to_json(data: Any, *, as_bytes: bool = False) -> str | bytes:
     """Encode data to JSON string or bytes.
 
     Args:
@@ -40,7 +40,7 @@ def from_json(data: str) -> Any: ...
 def from_json(data: bytes, *, decode_bytes: bool = ...) -> Any: ...
 
 
-def from_json(data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+def from_json(data: str | bytes, *, decode_bytes: bool = True) -> Any:
     """Decode JSON string or bytes to Python object.
 
     Args:

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: