sqlspec 0.16.1__cp39-cp39-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/utils/deprecation.py

@@ -0,0 +1,106 @@
+import inspect
+from functools import wraps
+from typing import Callable, Literal, Optional
+from warnings import warn
+
+from typing_extensions import ParamSpec, TypeVar
+
+__all__ = ("deprecated", "warn_deprecation")
+
+
+T = TypeVar("T")
+P = ParamSpec("P")
+DeprecatedKind = Literal["function", "method", "classmethod", "attribute", "property", "class", "parameter", "import"]
+
+
+def warn_deprecation(
+    version: str,
+    deprecated_name: str,
+    kind: DeprecatedKind,
+    *,
+    removal_in: Optional[str] = None,
+    alternative: Optional[str] = None,
+    info: Optional[str] = None,
+    pending: bool = False,
+) -> None:
+    """Warn about a call to a deprecated function.
+
+    Args:
+        version: SQLSpec version where the deprecation will occur
+        deprecated_name: Name of the deprecated function
+        removal_in: SQLSpec version where the deprecated function will be removed
+        alternative: Name of a function that should be used instead
+        info: Additional information
+        pending: Use :class:`warnings.PendingDeprecationWarning` instead of :class:`warnings.DeprecationWarning`
+        kind: Type of the deprecated thing
+    """
+    parts = []
+
+    if kind == "import":
+        access_type = "Import of"
+    elif kind in {"function", "method"}:
+        access_type = "Call to"
+    else:
+        access_type = "Use of"
+
+    if pending:
+        parts.append(f"{access_type} {kind} awaiting deprecation '{deprecated_name}'")  # pyright: ignore[reportUnknownMemberType]
+    else:
+        parts.append(f"{access_type} deprecated {kind} '{deprecated_name}'")  # pyright: ignore[reportUnknownMemberType]
+
+    parts.extend(  # pyright: ignore[reportUnknownMemberType]
+        (f"Deprecated in SQLSpec {version}", f"This {kind} will be removed in {removal_in or 'the next major version'}")
+    )
+    if alternative:
+        parts.append(f"Use {alternative!r} instead")  # pyright: ignore[reportUnknownMemberType]
+
+    if info:
+        parts.append(info)  # pyright: ignore[reportUnknownMemberType]
+
+    text = ". ".join(parts)  # pyright: ignore[reportUnknownArgumentType]
+    warning_class = PendingDeprecationWarning if pending else DeprecationWarning
+
+    warn(text, warning_class, stacklevel=2)
+
+
+def deprecated(
+    version: str,
+    *,
+    removal_in: Optional[str] = None,
+    alternative: Optional[str] = None,
+    info: Optional[str] = None,
+    pending: bool = False,
+    kind: Optional[Literal["function", "method", "classmethod", "property"]] = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Create a decorator wrapping a function, method or property with a deprecation warning.
+
+    Args:
+        version: SQLSpec version where the deprecation will occur
+        removal_in: SQLSpec version where the deprecated function will be removed
+        alternative: Name of a function that should be used instead
+        info: Additional information
+        pending: Use :class:`warnings.PendingDeprecationWarning` instead of :class:`warnings.DeprecationWarning`
+        kind: Type of the deprecated callable. If ``None``, will use ``inspect`` to figure
+            out if it's a function or method
+
+    Returns:
+        A decorator wrapping the function call with a warning
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs) -> T:
+            warn_deprecation(
+                version=version,
+                deprecated_name=func.__name__,
+                info=info,
+                alternative=alternative,
+                pending=pending,
+                removal_in=removal_in,
+                kind=kind or ("method" if inspect.ismethod(func) else "function"),
+            )
+            return func(*args, **kwargs)
+
+        return wrapped
+
+    return decorator

sqlspec/utils/fixtures.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+from typing import Any
+
+from sqlspec._serialization import decode_json
+from sqlspec.exceptions import MissingDependencyError
+
+__all__ = ("open_fixture", "open_fixture_async")
+
+
+def open_fixture(fixtures_path: Any, fixture_name: str) -> Any:
+    """Load and parse a JSON fixture file.
+
+    Args:
+        fixtures_path: The path to look for fixtures (pathlib.Path or anyio.Path)
+        fixture_name: The fixture name to load.
+
+    Raises:
+        FileNotFoundError: Fixtures not found.
+
+    Returns:
+        The parsed JSON data
+    """
+
+    fixture = Path(fixtures_path / f"{fixture_name}.json")
+    if fixture.exists():
+        with fixture.open(mode="r", encoding="utf-8") as f:
+            f_data = f.read()
+        return decode_json(f_data)
+    msg = f"Could not find the {fixture_name} fixture"
+    raise FileNotFoundError(msg)
+
+
+async def open_fixture_async(fixtures_path: Any, fixture_name: str) -> Any:
+    """Load and parse a JSON fixture file asynchronously.
+
+    Args:
+        fixtures_path: The path to look for fixtures (pathlib.Path or anyio.Path)
+        fixture_name: The fixture name to load.
+
+    Raises:
+        FileNotFoundError: Fixtures not found.
+        MissingDependencyError: The `anyio` library is required to use this function.
+
+    Returns:
+        The parsed JSON data
+    """
+    try:
+        from anyio import Path as AsyncPath
+    except ImportError as exc:
+        raise MissingDependencyError(package="anyio") from exc
+
+    fixture = AsyncPath(fixtures_path / f"{fixture_name}.json")
+    if await fixture.exists():
+        async with await fixture.open(mode="r", encoding="utf-8") as f:
+            f_data = await f.read()
+        return decode_json(f_data)
+    msg = f"Could not find the {fixture_name} fixture"
+    raise FileNotFoundError(msg)

sqlspec/utils/logging.py

@@ -0,0 +1,127 @@
+"""Logging utilities for SQLSpec.
+
+This module provides utilities for structured logging with correlation IDs.
+Users should configure their own logging handlers and levels as needed.
+SQLSpec provides StructuredFormatter for JSON-formatted logs if desired.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+from sqlspec._serialization import encode_json
+
+if TYPE_CHECKING:
+    from logging import LogRecord
+
+__all__ = ("StructuredFormatter", "correlation_id_var", "get_correlation_id", "get_logger", "set_correlation_id")
+
+correlation_id_var: ContextVar[str | None] = ContextVar("correlation_id", default=None)
+
+
+def set_correlation_id(correlation_id: str | None) -> None:
+    """Set the correlation ID for the current context.
+
+    Args:
+        correlation_id: The correlation ID to set, or None to clear
+    """
+    correlation_id_var.set(correlation_id)
+
+
+def get_correlation_id() -> str | None:
+    """Get the current correlation ID.
+
+    Returns:
+        The current correlation ID or None if not set
+    """
+    return correlation_id_var.get()
+
+
+class StructuredFormatter(logging.Formatter):
+    """Structured JSON formatter with correlation ID support."""
+
+    def format(self, record: LogRecord) -> str:
+        """Format log record as structured JSON.
+
+        Args:
+            record: The log record to format
+
+        Returns:
+            JSON formatted log entry
+        """
+        log_entry = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        if correlation_id := get_correlation_id():
+            log_entry["correlation_id"] = correlation_id
+
+        if hasattr(record, "extra_fields"):
+            log_entry.update(record.extra_fields)  # pyright: ignore
+
+        if record.exc_info:
+            log_entry["exception"] = self.formatException(record.exc_info)
+
+        return encode_json(log_entry)
+
+
+class CorrelationIDFilter(logging.Filter):
+    """Filter that adds correlation ID to log records."""
+
+    def filter(self, record: LogRecord) -> bool:
+        """Add correlation ID to record if available.
+
+        Args:
+            record: The log record to filter
+
+        Returns:
+            Always True to pass the record through
+        """
+        if correlation_id := get_correlation_id():
+            record.correlation_id = correlation_id
+        return True
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Get a logger instance with standardized configuration.
+
+    Args:
+        name: Logger name. If not provided, returns the root sqlspec logger.
+
+    Returns:
+        Configured logger instance
+    """
+    if name is None:
+        return logging.getLogger("sqlspec")
+
+    if not name.startswith("sqlspec"):
+        name = f"sqlspec.{name}"
+
+    logger = logging.getLogger(name)
+
+    if not any(isinstance(f, CorrelationIDFilter) for f in logger.filters):
+        logger.addFilter(CorrelationIDFilter())
+
+    return logger
+
+
+def log_with_context(logger: logging.Logger, level: int, message: str, **extra_fields: Any) -> None:
+    """Log a message with structured extra fields.
+
+    Args:
+        logger: The logger to use
+        level: Log level
+        message: Log message
+        **extra_fields: Additional fields to include in structured logs
+    """
+    record = logger.makeRecord(logger.name, level, "(unknown file)", 0, message, (), None)
+    record.extra_fields = extra_fields
+    logger.handle(record)

sqlspec/utils/module_loader.py

@@ -0,0 +1,89 @@
+"""General utility functions."""
+
+import importlib
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Any, Optional
+
+__all__ = ("import_string", "module_to_os_path")
+
+
+def module_to_os_path(dotted_path: str = "app") -> "Path":
+    """Convert a module dotted path to filesystem path.
+
+    Args:
+        dotted_path: The path to the module.
+
+    Raises:
+        TypeError: The module could not be found.
+
+    Returns:
+        The path to the module.
+    """
+    try:
+        if (src := find_spec(dotted_path)) is None:  # pragma: no cover
+            msg = f"Couldn't find the path for {dotted_path}"
+            raise TypeError(msg)
+    except ModuleNotFoundError as e:
+        msg = f"Couldn't find the path for {dotted_path}"
+        raise TypeError(msg) from e
+
+    path = Path(str(src.origin))
+    return path.parent if path.is_file() else path
+
+
+def import_string(dotted_path: str) -> "Any":
+    """Import a module or attribute from a dotted path string.
+
+    Args:
+        dotted_path: The path of the module to import.
+
+    Returns:
+        The imported object.
+    """
+
+    def _raise_import_error(msg: str, exc: "Optional[Exception]" = None) -> None:
+        if exc is not None:
+            raise ImportError(msg) from exc
+        raise ImportError(msg)
+
+    obj: Any = None
+    try:
+        parts = dotted_path.split(".")
+        module = None
+        i = len(parts)
+
+        for i in range(len(parts), 0, -1):
+            module_path = ".".join(parts[:i])
+            try:
+                module = importlib.import_module(module_path)
+                break
+            except ModuleNotFoundError:
+                continue
+        else:
+            _raise_import_error(f"{dotted_path} doesn't look like a module path")
+
+        if module is None:
+            _raise_import_error(f"Failed to import any module from {dotted_path}")
+
+        obj = module
+        attrs = parts[i:]
+        if not attrs and i == len(parts) and len(parts) > 1:
+            parent_module_path = ".".join(parts[:-1])
+            attr = parts[-1]
+            try:
+                parent_module = importlib.import_module(parent_module_path)
+            except Exception:
+                return obj
+            if not hasattr(parent_module, attr):
+                _raise_import_error(f"Module '{parent_module_path}' has no attribute '{attr}' in '{dotted_path}'")
+
+        for attr in attrs:
+            if not hasattr(obj, attr):
+                _raise_import_error(
+                    f"Module '{module.__name__ if module is not None else 'unknown'}' has no attribute '{attr}' in '{dotted_path}'"
+                )
+            obj = getattr(obj, attr)
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        _raise_import_error(f"Could not import '{dotted_path}': {e}", e)
+    return obj

sqlspec/utils/serializers.py

@@ -0,0 +1,4 @@
+from sqlspec._serialization import decode_json as from_json
+from sqlspec._serialization import encode_json as to_json
+
+__all__ = ("from_json", "to_json")

sqlspec/utils/singleton.py

@@ -0,0 +1,32 @@
+import threading
+from typing import Any, TypeVar
+
+__all__ = ("SingletonMeta",)
+
+
+_T = TypeVar("_T")
+
+
+class SingletonMeta(type):
+    """Metaclass for singleton pattern."""
+
+    _instances: dict[type, object] = {}
+    _lock = threading.Lock()
+
+    def __call__(cls: type[_T], *args: Any, **kwargs: Any) -> _T:
+        """Call method for the singleton metaclass.
+
+        Args:
+            cls: The class being instantiated.
+            *args: Positional arguments for the class constructor.
+            **kwargs: Keyword arguments for the class constructor.
+
+        Returns:
+            The singleton instance of the class.
+        """
+        if cls not in SingletonMeta._instances:  # pyright: ignore[reportUnnecessaryContains]
+            with SingletonMeta._lock:
+                if cls not in SingletonMeta._instances:
+                    instance = super().__call__(*args, **kwargs)  # type: ignore[misc]
+                    SingletonMeta._instances[cls] = instance
+        return SingletonMeta._instances[cls]  # type: ignore[return-value]

sqlspec/utils/sync_tools.py

@@ -0,0 +1,237 @@
+import asyncio
+import functools
+import inspect
+import sys
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar, Union, cast
+
+from typing_extensions import ParamSpec
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine
+    from types import TracebackType
+
+try:
+    import uvloop  # pyright: ignore[reportMissingImports]
+except ImportError:
+    uvloop = None  # type: ignore[assignment,unused-ignore]
+
+
+ReturnT = TypeVar("ReturnT")
+ParamSpecT = ParamSpec("ParamSpecT")
+T = TypeVar("T")
+
+
+class CapacityLimiter:
+    """Limits the number of concurrent operations using a semaphore."""
+
+    def __init__(self, total_tokens: int) -> None:
+        self._semaphore = asyncio.Semaphore(total_tokens)
+
+    async def acquire(self) -> None:
+        await self._semaphore.acquire()
+
+    def release(self) -> None:
+        self._semaphore.release()
+
+    @property
+    def total_tokens(self) -> int:
+        return self._semaphore._value
+
+    @total_tokens.setter
+    def total_tokens(self, value: int) -> None:
+        self._semaphore = asyncio.Semaphore(value)
+
+    async def __aenter__(self) -> None:
+        await self.acquire()
+
+    async def __aexit__(
+        self,
+        exc_type: "Optional[type[BaseException]]",
+        exc_val: "Optional[BaseException]",
+        exc_tb: "Optional[TracebackType]",
+    ) -> None:
+        self.release()
+
+
+_default_limiter = CapacityLimiter(15)
+
+
+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.
+    """
+
+    @functools.wraps(async_function)
+    def wrapper(*args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(async_function, *args, **kwargs)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None:
+            return asyncio.run(partial_f())
+        if uvloop and sys.platform != "win32":
+            uvloop.install()  # pyright: ignore[reportUnknownMemberType]
+        return asyncio.run(partial_f())
+
+    return wrapper
+
+
+def await_(
+    async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]", raise_sync_error: bool = True
+) -> "Callable[ParamSpecT, ReturnT]":
+    """Convert an async function to a blocking one, running in the main async loop.
+
+    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.
+
+    Returns:
+        A blocking function that runs the async function.
+    """
+
+    @functools.wraps(async_function)
+    def wrapper(*args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(async_function, *args, **kwargs)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            if raise_sync_error:
+                msg = "Cannot run async function"
+                raise RuntimeError(msg) from None
+            return asyncio.run(partial_f())
+        else:
+            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 raise_sync_error:
+                msg = "Cannot run async function"
+                raise RuntimeError(msg)
+            return asyncio.run(partial_f())
+
+    return wrapper
+
+
+def async_(
+    function: "Callable[ParamSpecT, ReturnT]", *, limiter: "Optional[CapacityLimiter]" = 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.
+    """
+
+    @functools.wraps(function)
+    async def wrapper(*args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        partial_f = functools.partial(function, *args, **kwargs)
+        used_limiter = limiter or _default_limiter
+        async with used_limiter:
+            return await asyncio.to_thread(partial_f)
+
+    return wrapper
+
+
+def ensure_async_(
+    function: "Callable[ParamSpecT, Union[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
+
+    @functools.wraps(function)
+    async def wrapper(*args: "ParamSpecT.args", **kwargs: "ParamSpecT.kwargs") -> "ReturnT":
+        result = function(*args, **kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return await async_(lambda: result)()
+
+    return wrapper
+
+
+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: "Optional[type[BaseException]]",
+        exc_val: "Optional[BaseException]",
+        exc_tb: "Optional[TracebackType]",
+    ) -> "Optional[bool]":
+        return self._cm.__exit__(exc_type, exc_val, exc_tb)
+
+
+def with_ensure_async_(
+    obj: "Union[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
+
+
+class NoValue:
+    """Sentinel class for missing values."""
+
+
+async def get_next(iterable: Any, default: Any = NoValue, *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.
+
+    Raises:
+        StopAsyncIteration: The iterable given is not async.
+    """
+    has_default = bool(not isinstance(default, NoValue))
+    try:
+        return await iterable.__anext__()
+
+    except StopAsyncIteration as exc:
+        if has_default:
+            return default
+
+        raise StopAsyncIteration from exc