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

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

@@ -2,11 +2,15 @@
 
 Re-exports common JSON encoding and decoding functions from the core
 serialization module for convenient access.
+
+Provides NumPy array serialization hooks for framework integrations
+that support custom type encoders and decoders (e.g., Litestar).
 """
 
-from typing import Any, Literal, Union, overload
+from typing import Any, Literal, overload
 
 from sqlspec._serialization import decode_json, encode_json
+from sqlspec.typing import NUMPY_INSTALLED
 
 
 @overload
@@ -17,7 +21,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 +44,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:
@@ -55,4 +59,109 @@ def from_json(data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
     return decode_json(data)
 
 
-__all__ = ("from_json", "to_json")
+def numpy_array_enc_hook(value: Any) -> Any:
+    """Encode NumPy array to JSON-compatible list.
+
+    Converts NumPy ndarrays to Python lists for JSON serialization.
+    Gracefully handles cases where NumPy is not installed by returning
+    the original value unchanged.
+
+    Args:
+        value: Value to encode (checked for ndarray type).
+
+    Returns:
+        List representation if value is ndarray, original value otherwise.
+
+    Example:
+        >>> import numpy as np
+        >>> arr = np.array([1.0, 2.0, 3.0])
+        >>> numpy_array_enc_hook(arr)
+        [1.0, 2.0, 3.0]
+
+        >>> # Multi-dimensional arrays work automatically
+        >>> arr_2d = np.array([[1, 2], [3, 4]])
+        >>> numpy_array_enc_hook(arr_2d)
+        [[1, 2], [3, 4]]
+    """
+    if not NUMPY_INSTALLED:
+        return value
+
+    import numpy as np
+
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    return value
+
+
+def numpy_array_dec_hook(value: Any) -> "Any":
+    """Decode list to NumPy array.
+
+    Converts Python lists to NumPy arrays when appropriate.
+    Works best with typed schemas (Pydantic, msgspec) that expect ndarray.
+
+    Args:
+        value: List to potentially convert to ndarray.
+
+    Returns:
+        NumPy array if conversion successful, original value otherwise.
+
+    Note:
+        Dtype is inferred by NumPy and may differ from original array.
+        For explicit dtype control, construct arrays manually in application code.
+
+    Example:
+        >>> numpy_array_dec_hook([1.0, 2.0, 3.0])
+        array([1., 2., 3.])
+
+        >>> # Returns original value if NumPy not installed
+        >>> # (when NUMPY_INSTALLED is False)
+        >>> numpy_array_dec_hook([1, 2, 3])
+        [1, 2, 3]
+    """
+    if not NUMPY_INSTALLED:
+        return value
+
+    import numpy as np
+
+    if isinstance(value, list):
+        try:
+            return np.array(value)
+        except Exception:
+            return value
+    return value
+
+
+def numpy_array_predicate(value: Any) -> bool:
+    """Check if value is NumPy array instance.
+
+    Type checker for decoder registration in framework plugins.
+    Returns False when NumPy is not installed.
+
+    Args:
+        value: Value to type-check.
+
+    Returns:
+        True if value is ndarray, False otherwise.
+
+    Example:
+        >>> import numpy as np
+        >>> numpy_array_predicate(np.array([1, 2, 3]))
+        True
+
+        >>> numpy_array_predicate([1, 2, 3])
+        False
+
+        >>> # Returns False when NumPy not installed
+        >>> # (when NUMPY_INSTALLED is False)
+        >>> numpy_array_predicate([1, 2, 3])
+        False
+    """
+    if not NUMPY_INSTALLED:
+        return False
+
+    import numpy as np
+
+    return isinstance(value, np.ndarray)
+
+
+__all__ = ("from_json", "numpy_array_dec_hook", "numpy_array_enc_hook", "numpy_array_predicate", "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]":
@@ -125,14 +132,18 @@ def run_(async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -
 
 
 def await_(
-    async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]", raise_sync_error: bool = True
+    async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]", raise_sync_error: bool = False
 ) -> "Callable[ParamSpecT, ReturnT]":
     """Convert an async function to a blocking one, running in the main async loop.
 
+    When no event loop exists, automatically creates and uses a global portal for
+    async-to-sync bridging via background thread. Set raise_sync_error=True to
+    disable this behavior and raise errors instead.
+
     Args:
         async_function: The async function to convert.
-        raise_sync_error: If False, runs in a new event loop if no loop is present.
-                         If True (default), raises RuntimeError if no loop is running.
+        raise_sync_error: If True, raises RuntimeError when no loop exists.
+                         If False (default), uses portal pattern for automatic bridging.
 
     Returns:
         A blocking function that runs the async function.
@@ -147,7 +158,10 @@ def await_(
             if raise_sync_error:
                 msg = "Cannot run async function"
                 raise RuntimeError(msg) from None
-            return asyncio.run(partial_f())
+            from sqlspec.utils.portal import get_global_portal
+
+            portal = get_global_portal()
+            return portal.call(async_function, *args, **kwargs)
         else:
             if loop.is_running():
                 try:
@@ -163,13 +177,16 @@ def await_(
             if raise_sync_error:
                 msg = "Cannot run async function"
                 raise RuntimeError(msg)
-            return asyncio.run(partial_f())
+            from sqlspec.utils.portal import get_global_portal
+
+            portal = get_global_portal()
+            return portal.call(async_function, *args, **kwargs)
 
     return wrapper
 
 
 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 +209,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 +240,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: