sqlspec 0.14.1__py3-none-any.whl → 0.16.0__py3-none-any.whl

sqlspec/utils/deprecation.py

@@ -23,12 +23,12 @@ def warn_deprecation(
     info: Optional[str] = None,
     pending: bool = False,
 ) -> None:
-    """Warn about a call to a (soon to be) deprecated function.
+    """Warn about a call to a deprecated function.
 
     Args:
-        version: Advanced Alchemy version where the deprecation will occur
+        version: SQLSpec version where the deprecation will occur
         deprecated_name: Name of the deprecated function
-        removal_in: Advanced Alchemy version where the deprecated function will be removed
+        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`
@@ -72,11 +72,11 @@ def deprecated(
     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 warning call about a (pending) deprecation.
+    """Create a decorator wrapping a function, method or property with a deprecation warning.
 
     Args:
-        version: Litestar version where the deprecation will occur
-        removal_in: Litestar version where the deprecated function will be removed
+        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`

sqlspec/utils/fixtures.py

@@ -8,17 +8,17 @@ __all__ = ("open_fixture", "open_fixture_async")
 
 
 def open_fixture(fixtures_path: Any, fixture_name: str) -> Any:
-    """Loads JSON file with the specified fixture name
+    """Load and parse a JSON fixture file.
 
     Args:
         fixtures_path: The path to look for fixtures (pathlib.Path or anyio.Path)
-        fixture_name (str): The fixture name to load.
+        fixture_name: The fixture name to load.
 
     Raises:
         FileNotFoundError: Fixtures not found.
 
     Returns:
-        Any: The parsed JSON data
+        The parsed JSON data
     """
 
     fixture = Path(fixtures_path / f"{fixture_name}.json")
@@ -31,18 +31,18 @@ def open_fixture(fixtures_path: Any, fixture_name: str) -> Any:
 
 
 async def open_fixture_async(fixtures_path: Any, fixture_name: str) -> Any:
-    """Loads JSON file with the specified fixture name
+    """Load and parse a JSON fixture file asynchronously.
 
     Args:
         fixtures_path: The path to look for fixtures (pathlib.Path or anyio.Path)
-        fixture_name (str): The fixture name to load.
+        fixture_name: The fixture name to load.
 
     Raises:
         FileNotFoundError: Fixtures not found.
         MissingDependencyError: The `anyio` library is required to use this function.
 
     Returns:
-        Any: The parsed JSON data
+        The parsed JSON data
     """
     try:
         from anyio import Path as AsyncPath

sqlspec/utils/logging.py

@@ -18,7 +18,6 @@ if TYPE_CHECKING:
 
 __all__ = ("StructuredFormatter", "correlation_id_var", "get_correlation_id", "get_logger", "set_correlation_id")
 
-# Context variable for correlation ID tracking
 correlation_id_var: ContextVar[str | None] = ContextVar("correlation_id", default=None)
 
 
@@ -52,7 +51,6 @@ class StructuredFormatter(logging.Formatter):
         Returns:
             JSON formatted log entry
         """
-        # Base log entry
         log_entry = {
             "timestamp": self.formatTime(record, self.datefmt),
             "level": record.levelname,

sqlspec/utils/module_loader.py

@@ -9,19 +9,16 @@ __all__ = ("import_string", "module_to_os_path")
 
 
 def module_to_os_path(dotted_path: str = "app") -> "Path":
-    """Find Module to OS Path.
-
-    Return a path to the base directory of the project or the module
-    specified by `dotted_path`.
+    """Convert a module dotted path to filesystem path.
 
     Args:
-        dotted_path: The path to the module. Defaults to "app".
+        dotted_path: The path to the module.
 
     Raises:
         TypeError: The module could not be found.
 
     Returns:
-        Path: The path to the module.
+        The path to the module.
     """
     try:
         if (src := find_spec(dotted_path)) is None:  # pragma: no cover
@@ -36,16 +33,13 @@ def module_to_os_path(dotted_path: str = "app") -> "Path":
 
 
 def import_string(dotted_path: str) -> "Any":
-    """Dotted Path Import.
-
-    Import a dotted module path and return the attribute/class designated by the
-    last name in the path. Raise ImportError if the import failed.
+    """Import a module or attribute from a dotted path string.
 
     Args:
         dotted_path: The path of the module to import.
 
     Returns:
-        object: The imported object.
+        The imported object.
     """
 
     def _raise_import_error(msg: str, exc: "Optional[Exception]" = None) -> None:
@@ -57,7 +51,7 @@ def import_string(dotted_path: str) -> "Any":
     try:
         parts = dotted_path.split(".")
         module = None
-        i = len(parts)  # Initialize to full length
+        i = len(parts)
 
         for i in range(len(parts), 0, -1):
             module_path = ".".join(parts[:i])
@@ -83,6 +77,7 @@ def import_string(dotted_path: str) -> "Any":
                 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(

sqlspec/utils/singleton.py

@@ -10,7 +10,6 @@ _T = TypeVar("_T")
 class SingletonMeta(type):
     """Metaclass for singleton pattern."""
 
-    # We store instances keyed by the class type
     _instances: dict[type, object] = {}
     _lock = threading.Lock()
 

sqlspec/utils/sync_tools.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
 try:
     import uvloop  # pyright: ignore[reportMissingImports]
 except ImportError:
-    uvloop = None
+    uvloop = None  # type: ignore[assignment,unused-ignore]
 
 
 ReturnT = TypeVar("ReturnT")
@@ -61,11 +61,10 @@ def run_(async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -
     """Convert an async function to a blocking function using asyncio.run().
 
     Args:
-        async_function (Callable): The async function to convert.
+        async_function: The async function to convert.
 
     Returns:
-        Callable: A blocking function that runs the async function.
-
+        A blocking function that runs the async function.
     """
 
     @functools.wraps(async_function)
@@ -77,7 +76,6 @@ def run_(async_function: "Callable[ParamSpecT, Coroutine[Any, Any, ReturnT]]") -
             loop = None
 
         if loop is not None:
-            # Running in an existing event loop
             return asyncio.run(partial_f())
         if uvloop and sys.platform != "win32":
             uvloop.install()  # pyright: ignore[reportUnknownMemberType]
@@ -92,12 +90,12 @@ def await_(
     """Convert an async function to a blocking one, running in the main async loop.
 
     Args:
-        async_function (Callable): The async function to convert.
-        raise_sync_error (bool, optional): If False, runs in a new event loop if no loop is present.
-                                         If True (default), raises RuntimeError if no loop is running.
+        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:
-        Callable: A blocking function that runs the async function.
+        A blocking function that runs the async function.
     """
 
     @functools.wraps(async_function)
@@ -111,27 +109,17 @@ def await_(
                 raise RuntimeError(msg) from None
             return asyncio.run(partial_f())
         else:
-            # Running in an existing event loop.
             if loop.is_running():
                 try:
                     current_task = asyncio.current_task(loop=loop)
                 except RuntimeError:
-                    # Not running inside a task managed by this loop
                     current_task = None
 
                 if current_task is not None:
-                    # Called from within the event loop's execution context (a task).
-                    # Blocking here would deadlock the loop.
                     msg = "await_ cannot be called from within an async task running on the same event loop. Use 'await' instead."
                     raise RuntimeError(msg)
-                # Called from a different thread than the loop's thread.
-                # It's safe to block this thread and wait for the loop.
                 future = asyncio.run_coroutine_threadsafe(partial_f(), loop)
-                # This blocks the *calling* thread, not the loop thread.
                 return future.result()
-            # This case should ideally not happen if get_running_loop() succeeded
-            # but the loop isn't running, but handle defensively.
-            # loop is not running
             if raise_sync_error:
                 msg = "Cannot run async function"
                 raise RuntimeError(msg)
@@ -146,12 +134,11 @@ def async_(
     """Convert a blocking function to an async one using asyncio.to_thread().
 
     Args:
-        function (Callable): The blocking function to convert.
-        cancellable (bool, optional): Allow cancellation of the operation.
-        limiter (CapacityLimiter, optional): Limit the total number of threads.
+        function: The blocking function to convert.
+        limiter: Limit the total number of threads.
 
     Returns:
-        Callable: An async function that runs the original function in a thread.
+        An async function that runs the original function in a thread.
     """
 
     @functools.wraps(function)
@@ -170,10 +157,10 @@ def ensure_async_(
     """Convert a function to an async one if it is not already.
 
     Args:
-        function (Callable): The function to convert.
+        function: The function to convert.
 
     Returns:
-        Callable: An async function that runs the original function.
+        An async function that runs the original function.
     """
     if inspect.iscoroutinefunction(function):
         return function
@@ -210,10 +197,10 @@ def with_ensure_async_(
     """Convert a context manager to an async one if it is not already.
 
     Args:
-        obj (AbstractContextManager[T] or AbstractAsyncContextManager[T]): The context manager to convert.
+        obj: The context manager to convert.
 
     Returns:
-        AbstractAsyncContextManager[T]: An async context manager that runs the original context manager.
+        An async context manager that runs the original context manager.
     """
 
     if isinstance(obj, AbstractContextManager):
@@ -222,30 +209,22 @@ def with_ensure_async_(
 
 
 class NoValue:
-    """A fake "Empty class"""
+    """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.
 
-    In Python <3.10, `anext` is not available. This function is a drop-in replacement.
-
-    This function will return the next value form an async iterable. If the
-    iterable is empty the StopAsyncIteration will be propagated. However, if
-    a default value is given as a second argument the exception is silenced and
-    the default value is returned instead.
-
     Args:
         iterable: An async iterable.
         default: An optional default value to return if the iterable is empty.
         *args: The remaining args
-    Return:
+
+    Returns:
         The next value of the iterable.
 
     Raises:
         StopAsyncIteration: The iterable given is not async.
-
-
     """
     has_default = bool(not isinstance(default, NoValue))
     try:

sqlspec/utils/text.py

@@ -5,35 +5,29 @@ import unicodedata
 from functools import lru_cache
 from typing import Optional
 
-# Compiled regex for slugify
 _SLUGIFY_REMOVE_NON_ALPHANUMERIC = re.compile(r"[^\w]+", re.UNICODE)
 _SLUGIFY_HYPHEN_COLLAPSE = re.compile(r"-+")
 
-# Compiled regex for snake_case
-# Insert underscore between lowercase/digit and uppercase letter
 _SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER = re.compile(r"(?<=[a-z0-9])(?=[A-Z])", re.UNICODE)
-# Insert underscore between uppercase letter and uppercase followed by lowercase
 _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)
-# Collapse multiple underscores
+_SNAKE_CASE_REMOVE_NON_WORD = re.compile(r"[^\w]+", re.UNICODE)
 _SNAKE_CASE_MULTIPLE_UNDERSCORES = re.compile(r"__+", re.UNICODE)
 
 __all__ = ("camelize", "check_email", "slugify", "snake_case")
 
 
 def check_email(email: str) -> str:
-    """Validate an email.
-
-    Very simple email validation.
+    """Validate an email address.
 
     Args:
-        email (str): The email to validate.
+        email: The email to validate.
 
     Raises:
         ValueError: If the email is invalid.
 
     Returns:
-        str: The validated email.
+        The validated email.
     """
     if "@" not in email:
         msg = "Invalid email!"
@@ -42,21 +36,15 @@ def check_email(email: str) -> str:
 
 
 def slugify(value: str, allow_unicode: bool = False, separator: Optional[str] = None) -> str:
-    """Slugify.
-
-    Convert to ASCII if ``allow_unicode`` is ``False``. Convert spaces or repeated
-    dashes to single dashes. Remove characters that aren't alphanumerics,
-    underscores, or hyphens. Convert to lowercase. Also strip leading and
-    trailing whitespace, dashes, and underscores.
+    """Convert a string to a URL-friendly slug.
 
     Args:
-        value (str): the string to slugify
-        allow_unicode (bool, optional): allow unicode characters in slug. Defaults to False.
-        separator (str, optional): by default a `-` is used to delimit word boundaries.
-            Set this to configure something different.
+        value: The string to slugify
+        allow_unicode: Allow unicode characters in slug.
+        separator: Separator character for word boundaries. Defaults to "-".
 
     Returns:
-        str: a slugified string of the value parameter
+        A slugified string.
     """
     if allow_unicode:
         value = unicodedata.normalize("NFKC", value)
@@ -67,9 +55,7 @@ def slugify(value: str, allow_unicode: bool = False, separator: Optional[str] =
     if not sep:
         return _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub("", value)
     value = _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub(sep, value)
-    # For dynamic separators, we need to use re.sub with escaped separator
     if sep == "-":
-        # Use pre-compiled regex for common case
         value = value.strip("-")
         return _SLUGIFY_HYPHEN_COLLAPSE.sub("-", value)
     value = re.sub(rf"^{re.escape(sep)}+|{re.escape(sep)}+$", "", value)
@@ -81,10 +67,10 @@ def camelize(string: str) -> str:
     """Convert a string to camel case.
 
     Args:
-        string (str): The string to convert.
+        string: The string to convert.
 
     Returns:
-        str: The converted string.
+        The converted string.
     """
     return "".join(word if index == 0 else word.capitalize() for index, word in enumerate(string.split("_")))
 
@@ -93,11 +79,6 @@ def camelize(string: str) -> str:
 def snake_case(string: str) -> str:
     """Convert a string to snake_case.
 
-    Handles CamelCase, PascalCase, strings with spaces, hyphens, or dots
-    as separators, and ensures single underscores. It also correctly
-    handles acronyms (e.g., "HTTPRequest" becomes "http_request").
-    Handles Unicode letters and numbers.
-
     Args:
         string: The string to convert.
 
@@ -106,30 +87,10 @@ def snake_case(string: str) -> str:
     """
     if not string:
         return ""
-    # 1. Replace hyphens and spaces with underscores
     s = _SNAKE_CASE_HYPHEN_SPACE.sub("_", string)
-
-    # 2. Remove all non-alphanumeric characters except underscores
-    # TODO: move to a compiled regex at the top of the file
-    s = re.sub(r"[^\w]+", "", s, flags=re.UNICODE)
-
-    # 3. Insert an underscore between a lowercase/digit and an uppercase letter.
-    #    e.g., "helloWorld" -> "hello_World"
-    #    e.g., "Python3IsGreat" -> "Python3_IsGreat"
-    #    Uses a positive lookbehind `(?<=[...])` and a positive lookahead `(?=[...])`
+    s = _SNAKE_CASE_REMOVE_NON_WORD.sub("", s)
     s = _SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER.sub("_", s)
-
-    # 4. Insert an underscore between an uppercase letter and another
-    #    uppercase letter followed by a lowercase letter.
-    #    e.g., "HTTPRequest" -> "HTTP_Request"
-    #    This handles acronyms gracefully.
     s = _SNAKE_CASE_UPPER_TO_UPPER_LOWER.sub("_", s)
-
-    # 5. Convert the entire string to lowercase.
     s = s.lower()
-
-    # 6. Remove any leading or trailing underscores that might have been created.
     s = s.strip("_")
-
-    # 7. Collapse multiple consecutive underscores into a single one.
     return _SNAKE_CASE_MULTIPLE_UNDERSCORES.sub("_", s)