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

sqlspec/utils/sync_tools.py

@@ -0,0 +1,311 @@
+"""Utilities for async/sync interoperability in SQLSpec.
+
+This module provides utilities for converting between async and sync functions,
+managing concurrency limits, and handling context managers. Used primarily
+for adapter implementations that need to support both sync and async patterns.
+"""
+
+import asyncio
+import concurrent.futures
+import functools
+import inspect
+import os
+import sys
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
+
+from typing_extensions import ParamSpec
+
+from sqlspec.utils.module_loader import module_available
+from sqlspec.utils.portal import get_global_portal
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine
+    from types import TracebackType
+
+if module_available("uvloop"):
+    import uvloop  # pyright: ignore[reportMissingImports]
+else:
+    uvloop = None  # type: ignore[assignment,unused-ignore]
+
+
+ReturnT = TypeVar("ReturnT")
+ParamSpecT = ParamSpec("ParamSpecT")
+T = TypeVar("T")
+
+
+class NoValue:
+    """Sentinel class for missing values."""
+
+
+NO_VALUE = NoValue()
+
+
+class CapacityLimiter:
+    """Limits the number of concurrent operations using a semaphore."""
+
+    def __init__(self, total_tokens: int) -> None:
+        """Initialize the capacity limiter.
+
+        Args:
+            total_tokens: Maximum number of concurrent operations allowed
+        """
+        self._total_tokens = total_tokens
+        self._semaphore_instance: asyncio.Semaphore | None = None
+        self._pid: int | None = None
+
+    @property
+    def _semaphore(self) -> asyncio.Semaphore:
+        """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:
+        """Acquire a token from the semaphore."""
+        await self._semaphore.acquire()
+
+    def release(self) -> None:
+        """Release a token back to the semaphore."""
+        self._semaphore.release()
+
+    @property
+    def total_tokens(self) -> int:
+        """Get the total number of tokens available."""
+        return self._total_tokens
+
+    @total_tokens.setter
+    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: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> None:
+        """Async context manager exit."""
+        self.release()
+
+
+_default_limiter = CapacityLimiter(1000)
+
+
+def _return_value(value: Any) -> Any:
+    return value
+
+
+class _RunWrapper(Generic[ParamSpecT, ReturnT]):
+    __slots__ = ("__dict__", "_function")
+
+    def __init__(self, async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -> None:
+        self._function = async_function
+        functools.update_wrapper(self, async_function)
+
+    def __call__(self, *args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(self._function, *args, **kwargs)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None:
+            if loop.is_running():
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(asyncio.run, partial_f())
+                    return future.result()
+            return asyncio.run(partial_f())
+        if uvloop and sys.platform != "win32":
+            uvloop.install()  # pyright: ignore[reportUnknownMemberType]
+        return asyncio.run(partial_f())
+
+
+def run_(async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -> "Callable[ParamSpecT, ReturnT]":
+    """Convert an async function to a blocking function using asyncio.run().
+
+    Args:
+        async_function: The async function to convert.
+
+    Returns:
+        A blocking function that runs the async function.
+    """
+
+    return _RunWrapper(async_function)
+
+
+def await_(
+    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 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.
+    """
+
+    return _AwaitWrapper(async_function, raise_sync_error)
+
+
+def async_(
+    function: "Callable[ParamSpecT, ReturnT]", *, limiter: "CapacityLimiter | None" = None
+) -> "Callable[ParamSpecT, Awaitable[ReturnT]]":
+    """Convert a blocking function to an async one using asyncio.to_thread().
+
+    Args:
+        function: The blocking function to convert.
+        limiter: Limit the total number of threads.
+
+    Returns:
+        An async function that runs the original function in a thread.
+    """
+
+    return _AsyncWrapper(function, limiter)
+
+
+def ensure_async_(
+    function: "Callable[ParamSpecT, Awaitable[ReturnT] | ReturnT]",
+) -> "Callable[ParamSpecT, Awaitable[ReturnT]]":
+    """Convert a function to an async one if it is not already.
+
+    Args:
+        function: The function to convert.
+
+    Returns:
+        An async function that runs the original function.
+    """
+    if inspect.iscoroutinefunction(function):
+        return function
+
+    return _EnsureAsyncWrapper(function)
+
+
+class _AwaitWrapper(Generic[ParamSpecT, ReturnT]):
+    __slots__ = ("__dict__", "_function", "_raise_sync_error")
+
+    def __init__(
+        self, async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]", raise_sync_error: bool
+    ) -> None:
+        self._function = async_function
+        self._raise_sync_error = raise_sync_error
+        functools.update_wrapper(self, async_function)
+
+    def __call__(self, *args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(self._function, *args, **kwargs)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            if self._raise_sync_error:
+                msg = "Cannot run async function"
+                raise RuntimeError(msg) from None
+            portal = get_global_portal()
+            typed_partial = cast("Callable[[], Coroutine[Any, Any, ReturnT]]", partial_f)
+            return portal.call(typed_partial)
+        if loop.is_running():
+            try:
+                current_task = asyncio.current_task(loop=loop)
+            except RuntimeError:
+                current_task = None
+
+            if current_task is not None:
+                msg = "await_ cannot be called from within an async task running on the same event loop. Use 'await' instead."
+                raise RuntimeError(msg)
+            future = asyncio.run_coroutine_threadsafe(partial_f(), loop)
+            return future.result()
+        if self._raise_sync_error:
+            msg = "Cannot run async function"
+            raise RuntimeError(msg)
+        portal = get_global_portal()
+        typed_partial = cast("Callable[[], Coroutine[Any, Any, ReturnT]]", partial_f)
+        return portal.call(typed_partial)
+
+
+class _AsyncWrapper(Generic[ParamSpecT, ReturnT]):
+    __slots__ = ("__dict__", "_function", "_limiter")
+
+    def __init__(self, function: "Callable[ParamSpecT, ReturnT]", limiter: "CapacityLimiter | None") -> None:
+        self._function = function
+        self._limiter = limiter
+        functools.update_wrapper(self, function)
+
+    async def __call__(self, *args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(self._function, *args, **kwargs)
+        used_limiter = self._limiter or _default_limiter
+        async with used_limiter:
+            return await asyncio.to_thread(partial_f)
+
+
+class _EnsureAsyncWrapper(Generic[ParamSpecT, ReturnT]):
+    __slots__ = ("__dict__", "_function")
+
+    def __init__(self, function: "Callable[ParamSpecT, Awaitable[ReturnT] | ReturnT]") -> None:
+        self._function = function
+        functools.update_wrapper(self, function)
+
+    async def __call__(self, *args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        result = self._function(*args, **kwargs)
+        if inspect.isawaitable(result):
+            return await cast("Awaitable[ReturnT]", result)
+        return result
+
+
+class _ContextManagerWrapper(Generic[T]):
+    def __init__(self, cm: AbstractContextManager[T]) -> None:
+        self._cm = cm
+
+    async def __aenter__(self) -> T:
+        return self._cm.__enter__()
+
+    async def __aexit__(
+        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: "AbstractContextManager[T] | AbstractAsyncContextManager[T]",
+) -> "AbstractAsyncContextManager[T]":
+    """Convert a context manager to an async one if it is not already.
+
+    Args:
+        obj: The context manager to convert.
+
+    Returns:
+        An async context manager that runs the original context manager.
+    """
+    if isinstance(obj, AbstractContextManager):
+        return cast("AbstractAsyncContextManager[T]", _ContextManagerWrapper(obj))
+    return obj
+
+
+async def get_next(iterable: Any, default: Any = NO_VALUE, *args: Any) -> Any:  # pragma: no cover
+    """Return the next item from an async iterator.
+
+    Args:
+        iterable: An async iterable.
+        default: An optional default value to return if the iterable is empty.
+        *args: The remaining args
+
+    Returns:
+        The next value of the iterable.
+    """
+    if isinstance(default, NoValue):
+        return await anext(iterable)
+    return await anext(iterable, default)

sqlspec/utils/text.py

@@ -0,0 +1,108 @@
+"""Text processing utilities for SQLSpec.
+
+Provides functions for string manipulation including case conversion,
+slugification, and email validation. Used primarily for identifier
+generation and data validation.
+"""
+
+import re
+import unicodedata
+from functools import lru_cache
+
+_SLUGIFY_REMOVE_NON_ALPHANUMERIC = re.compile(r"[^\w]+", re.UNICODE)
+_SLUGIFY_HYPHEN_COLLAPSE = re.compile(r"-+")
+
+_SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER = re.compile(r"(?<=[a-z0-9])(?=[A-Z])", re.UNICODE)
+_SNAKE_CASE_UPPER_TO_UPPER_LOWER = re.compile(r"(?<=[A-Z])(?=[A-Z][a-z])", re.UNICODE)
+_SNAKE_CASE_HYPHEN_SPACE = re.compile(r"[.\s@-]+", re.UNICODE)
+_SNAKE_CASE_REMOVE_NON_WORD = re.compile(r"[^\w]+", re.UNICODE)
+_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: str | None = None) -> str:
+    """Convert a string to a URL-friendly slug.
+
+    Args:
+        value: The string to slugify
+        allow_unicode: Allow unicode characters in slug.
+        separator: Separator character for word boundaries. Defaults to "-".
+
+    Returns:
+        A slugified string.
+    """
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode("ascii")
+    value = value.lower().strip()
+    sep = separator if separator is not None else "-"
+    if not sep:
+        return _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub("", value)
+    value = _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub(sep, value)
+    if sep == "-":
+        value = value.strip("-")
+        return _SLUGIFY_HYPHEN_COLLAPSE.sub("-", value)
+    value = re.sub(rf"^{re.escape(sep)}+|{re.escape(sep)}+$", "", value)
+    return re.sub(rf"{re.escape(sep)}+", sep, value)
+
+
+@lru_cache(maxsize=100)
+def camelize(string: str) -> str:
+    """Convert a string to camel case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The converted string.
+    """
+    return "".join(word if index == 0 else word.capitalize() for index, word in enumerate(string.split("_")))
+
+
+@lru_cache(maxsize=100)
+def kebabize(string: str) -> str:
+    """Convert a string to kebab-case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The kebab-case version of the string.
+    """
+    return "-".join(word.lower() for word in string.split("_") if word)
+
+
+@lru_cache(maxsize=100)
+def pascalize(string: str) -> str:
+    """Convert a string to PascalCase.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The PascalCase version of the string.
+    """
+    return "".join(word.capitalize() for word in string.split("_") if word)
+
+
+@lru_cache(maxsize=100)
+def snake_case(string: str) -> str:
+    """Convert a string to snake_case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The snake_case version of the string.
+    """
+    if not string:
+        return ""
+    s = _SNAKE_CASE_HYPHEN_SPACE.sub("_", string)
+    s = _SNAKE_CASE_REMOVE_NON_WORD.sub("", s)
+    s = _SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER.sub("_", s)
+    s = _SNAKE_CASE_UPPER_TO_UPPER_LOWER.sub("_", s)
+    s = s.lower()
+    s = s.strip("_")
+    return _SNAKE_CASE_MULTIPLE_UNDERSCORES.sub("_", s)

sqlspec/utils/type_converters.py

@@ -0,0 +1,128 @@
+"""Reusable converter builders for parameter configuration."""
+
+import decimal
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import datetime
+    from collections.abc import Callable, Sequence
+
+__all__ = (
+    "DEFAULT_DECIMAL_MODE",
+    "build_decimal_converter",
+    "build_json_list_converter",
+    "build_json_tuple_converter",
+    "build_nested_decimal_normalizer",
+    "build_time_iso_converter",
+    "should_json_encode_sequence",
+)
+
+JSON_NESTED_TYPES: "tuple[type[Any], ...]" = (dict, list, tuple)
+DEFAULT_DECIMAL_MODE: str = "preserve"
+
+
+def _decimal_identity(value: "decimal.Decimal") -> "decimal.Decimal":
+    return value
+
+
+def _decimal_to_string(value: "decimal.Decimal") -> str:
+    return str(value)
+
+
+def _decimal_to_float(value: "decimal.Decimal") -> float:
+    return float(value)
+
+
+class _JsonListConverter:
+    __slots__ = ("_preserve_arrays", "_serializer")
+
+    def __init__(self, serializer: "Callable[[Any], str]", preserve_arrays: bool) -> None:
+        self._serializer = serializer
+        self._preserve_arrays = preserve_arrays
+
+    def __call__(self, value: "list[Any]") -> Any:
+        if not value:
+            return value
+        if self._preserve_arrays and not should_json_encode_sequence(value):
+            return value
+        return self._serializer(value)
+
+
+class _JsonTupleConverter:
+    __slots__ = ("_list_converter",)
+
+    def __init__(self, list_converter: _JsonListConverter) -> None:
+        self._list_converter = list_converter
+
+    def __call__(self, value: "tuple[Any, ...]") -> Any:
+        if not value:
+            return value
+        return self._list_converter(list(value))
+
+
+class _DecimalNormalizer:
+    __slots__ = ("_decimal_converter",)
+
+    def __init__(self, decimal_converter: "Callable[[decimal.Decimal], Any]") -> None:
+        self._decimal_converter = decimal_converter
+
+    def __call__(self, value: Any) -> Any:
+        if isinstance(value, decimal.Decimal):
+            return self._decimal_converter(value)
+        if isinstance(value, list):
+            return [self(item) for item in value]
+        if isinstance(value, tuple):
+            return tuple(self(item) for item in value)
+        if isinstance(value, dict):
+            return {key: self(item) for key, item in value.items()}
+        return value
+
+
+def _time_iso_convert(value: "datetime.date | datetime.datetime | datetime.time") -> str:
+    return value.isoformat()
+
+
+def should_json_encode_sequence(sequence: "Sequence[Any]") -> bool:
+    """Return ``True`` when a sequence should be JSON serialized."""
+
+    return any(isinstance(item, JSON_NESTED_TYPES) for item in sequence if item is not None)
+
+
+def build_json_list_converter(
+    serializer: "Callable[[Any], str]", *, preserve_arrays: bool = True
+) -> "Callable[[list[Any]], Any]":
+    """Create a converter that serializes lists containing nested structures."""
+    return _JsonListConverter(serializer, preserve_arrays)
+
+
+def build_json_tuple_converter(
+    serializer: "Callable[[Any], str]", *, preserve_arrays: bool = True
+) -> "Callable[[tuple[Any, ...]], Any]":
+    """Create a converter that mirrors list handling for tuples."""
+    list_converter = _JsonListConverter(serializer, preserve_arrays)
+    return _JsonTupleConverter(list_converter)
+
+
+def build_decimal_converter(*, mode: str = DEFAULT_DECIMAL_MODE) -> "Callable[[decimal.Decimal], Any]":
+    """Create a Decimal converter according to the desired mode."""
+
+    if mode == "preserve":
+        return _decimal_identity
+    if mode == "string":
+        return _decimal_to_string
+    if mode == "float":
+        return _decimal_to_float
+
+    msg = f"Unsupported decimal converter mode: {mode}"
+    raise ValueError(msg)
+
+
+def build_nested_decimal_normalizer(*, mode: str = DEFAULT_DECIMAL_MODE) -> "Callable[[Any], Any]":
+    """Return a callable that coerces ``Decimal`` values within nested structures."""
+    decimal_converter = build_decimal_converter(mode=mode)
+    return _DecimalNormalizer(decimal_converter)
+
+
+def build_time_iso_converter() -> "Callable[[datetime.date | datetime.datetime | datetime.time], str]":
+    """Return a converter that formats temporal values using ISO 8601."""
+    return _time_iso_convert