sqlspec 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

sqlspec/typing.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
+from __future__ import annotations  # noqa: A005
 
 from collections.abc import Sequence
 from dataclasses import Field, fields
@@ -48,11 +48,21 @@ FilterTypeT = TypeVar("FilterTypeT", bound="StatementFilter")
 
 :class:`~advanced_alchemy.filters.StatementFilter`
 """
+ModelDTOT = TypeVar("ModelDTOT", bound="Struct | BaseModel")
+"""Type variable for model DTOs.
+
+:class:`msgspec.Struct`|:class:`pydantic.BaseModel`
+"""
+PydanticOrMsgspecT: TypeAlias = Union[Struct, BaseModel]
+"""Type alias for pydantic or msgspec models.
+
+:class:`msgspec.Struct` or :class:`pydantic.BaseModel`
+"""
 ModelDictT: TypeAlias = Union[dict[str, Any], ModelT, DataclassProtocol, Struct, BaseModel]
 """Type alias for model dictionaries.
 
 Represents:
-- :type:`dict[str, Any]` | :class:`~advanced_alchemy.base.ModelProtocol` | :class:`msgspec.Struct` |  :class:`pydantic.BaseModel` | :class:`litestar.dto.data_structures.DTOData` | :class:`~advanced_alchemy.base.ModelProtocol`
+- :type:`dict[str, Any]` |  :class:`msgspec.Struct` |  :class:`pydantic.BaseModel`
 """
 ModelDictListT: TypeAlias = Sequence[Union[dict[str, Any], ModelT, DataclassProtocol, Struct, BaseModel]]
 """Type alias for model dictionary lists.
@@ -72,7 +82,7 @@ def is_dataclass_instance(obj: Any) -> TypeGuard[DataclassProtocol]:
     Returns:
         True if the object is a dataclass instance.
     """
-    return hasattr(type(obj), "__dataclass_fields__")
+    return hasattr(type(obj), "__dataclass_fields__")  # pyright: ignore[reportUnknownArgumentType]
 
 
 @lru_cache(typed=True)
@@ -104,7 +114,33 @@ def is_pydantic_model(v: Any) -> TypeGuard[BaseModel]:
     return PYDANTIC_INSTALLED and isinstance(v, BaseModel)
 
 
-def is_msgspec_model(v: Any) -> TypeGuard[Struct]:
+def is_pydantic_model_with_field(v: Any, field_name: str) -> TypeGuard[BaseModel]:
+    """Check if a pydantic model has a specific field.
+
+    Args:
+        v: Value to check.
+        field_name: Field name to check for.
+
+    Returns:
+        bool
+    """
+    return is_pydantic_model(v) and field_name in v.model_fields
+
+
+def is_pydantic_model_without_field(v: Any, field_name: str) -> TypeGuard[BaseModel]:
+    """Check if a pydantic model does not have a specific field.
+
+    Args:
+        v: Value to check.
+        field_name: Field name to check for.
+
+    Returns:
+        bool
+    """
+    return not is_pydantic_model_with_field(v, field_name)
+
+
+def is_msgspec_struct(v: Any) -> TypeGuard[Struct]:
     """Check if a value is a msgspec model.
 
     Args:
@@ -116,6 +152,32 @@ def is_msgspec_model(v: Any) -> TypeGuard[Struct]:
     return MSGSPEC_INSTALLED and isinstance(v, Struct)
 
 
+def is_msgspec_struct_with_field(v: Any, field_name: str) -> TypeGuard[Struct]:
+    """Check if a msgspec model has a specific field.
+
+    Args:
+        v: Value to check.
+        field_name: Field name to check for.
+
+    Returns:
+        bool
+    """
+    return is_msgspec_struct(v) and field_name in v.__struct_fields__
+
+
+def is_msgspec_struct_without_field(v: Any, field_name: str) -> TypeGuard[Struct]:
+    """Check if a msgspec model does not have a specific field.
+
+    Args:
+        v: Value to check.
+        field_name: Field name to check for.
+
+    Returns:
+        bool
+    """
+    return not is_msgspec_struct_with_field(v, field_name)
+
+
 def is_dict(v: Any) -> TypeGuard[dict[str, Any]]:
     """Check if a value is a dictionary.
 
@@ -154,8 +216,8 @@ def is_dict_without_field(v: Any, field_name: str) -> TypeGuard[dict[str, Any]]:
     return is_dict(v) and field_name not in v
 
 
-def is_dataclass(v: Any) -> TypeGuard[DataclassProtocol]:
-    """Check if a value is a dataclass.
+def is_schema(v: Any) -> TypeGuard[Struct | BaseModel]:
+    """Check if a value is a msgspec Struct or Pydantic model.
 
     Args:
         v: Value to check.
@@ -163,11 +225,23 @@ def is_dataclass(v: Any) -> TypeGuard[DataclassProtocol]:
     Returns:
         bool
     """
-    return is_dataclass_instance(v)
+    return is_msgspec_struct(v) or is_pydantic_model(v)
 
 
-def is_dataclass_with_field(v: Any, field_name: str) -> TypeGuard[DataclassProtocol]:
-    """Check if a dataclass has a specific field.
+def is_schema_or_dict(v: Any) -> TypeGuard[Struct | BaseModel | dict[str, Any]]:
+    """Check if a value is a msgspec Struct, Pydantic model, or dict.
+
+    Args:
+        v: Value to check.
+
+    Returns:
+        bool
+    """
+    return is_schema(v) or is_dict(v)
+
+
+def is_schema_with_field(v: Any, field_name: str) -> TypeGuard[Struct | BaseModel]:
+    """Check if a value is a msgspec Struct or Pydantic model with a specific field.
 
     Args:
         v: Value to check.
@@ -176,11 +250,11 @@ def is_dataclass_with_field(v: Any, field_name: str) -> TypeGuard[DataclassProto
     Returns:
         bool
     """
-    return is_dataclass(v) and field_name in v.__dataclass_fields__
+    return is_msgspec_struct_with_field(v, field_name) or is_pydantic_model_with_field(v, field_name)
 
 
-def is_dataclass_without_field(v: Any, field_name: str) -> TypeGuard[DataclassProtocol]:
-    """Check if a dataclass does not have a specific field.
+def is_schema_without_field(v: Any, field_name: str) -> TypeGuard[Struct | BaseModel]:
+    """Check if a value is a msgspec Struct or Pydantic model without a specific field.
 
     Args:
         v: Value to check.
@@ -189,11 +263,11 @@ def is_dataclass_without_field(v: Any, field_name: str) -> TypeGuard[DataclassPr
     Returns:
         bool
     """
-    return is_dataclass(v) and field_name not in v.__dataclass_fields__
+    return not is_schema_with_field(v, field_name)
 
 
-def is_pydantic_model_with_field(v: Any, field_name: str) -> TypeGuard[BaseModel]:
-    """Check if a pydantic model has a specific field.
+def is_schema_or_dict_with_field(v: Any, field_name: str) -> TypeGuard[Struct | BaseModel | dict[str, Any]]:
+    """Check if a value is a msgspec Struct, Pydantic model, or dict with a specific field.
 
     Args:
         v: Value to check.
@@ -202,11 +276,11 @@ def is_pydantic_model_with_field(v: Any, field_name: str) -> TypeGuard[BaseModel
     Returns:
         bool
     """
-    return is_pydantic_model(v) and field_name in v.model_fields
+    return is_schema_with_field(v, field_name) or is_dict_with_field(v, field_name)
 
 
-def is_pydantic_model_without_field(v: Any, field_name: str) -> TypeGuard[BaseModel]:
-    """Check if a pydantic model does not have a specific field.
+def is_schema_or_dict_without_field(v: Any, field_name: str) -> TypeGuard[Struct | BaseModel | dict[str, Any]]:
+    """Check if a value is a msgspec Struct, Pydantic model, or dict without a specific field.
 
     Args:
         v: Value to check.
@@ -215,11 +289,23 @@ def is_pydantic_model_without_field(v: Any, field_name: str) -> TypeGuard[BaseMo
     Returns:
         bool
     """
-    return not is_pydantic_model_with_field(v, field_name)
+    return not is_schema_or_dict_with_field(v, field_name)
 
 
-def is_msgspec_model_with_field(v: Any, field_name: str) -> TypeGuard[Struct]:
-    """Check if a msgspec model has a specific field.
+def is_dataclass(v: Any) -> TypeGuard[DataclassProtocol]:
+    """Check if a value is a dataclass.
+
+    Args:
+        v: Value to check.
+
+    Returns:
+        bool
+    """
+    return is_dataclass_instance(v)
+
+
+def is_dataclass_with_field(v: Any, field_name: str) -> TypeGuard[DataclassProtocol]:
+    """Check if a dataclass has a specific field.
 
     Args:
         v: Value to check.
@@ -228,11 +314,11 @@ def is_msgspec_model_with_field(v: Any, field_name: str) -> TypeGuard[Struct]:
     Returns:
         bool
     """
-    return is_msgspec_model(v) and field_name in v.__struct_fields__
+    return is_dataclass(v) and field_name in v.__dataclass_fields__
 
 
-def is_msgspec_model_without_field(v: Any, field_name: str) -> TypeGuard[Struct]:
-    """Check if a msgspec model does not have a specific field.
+def is_dataclass_without_field(v: Any, field_name: str) -> TypeGuard[DataclassProtocol]:
+    """Check if a dataclass does not have a specific field.
 
     Args:
         v: Value to check.
@@ -241,7 +327,7 @@ def is_msgspec_model_without_field(v: Any, field_name: str) -> TypeGuard[Struct]
     Returns:
         bool
     """
-    return not is_msgspec_model_with_field(v, field_name)
+    return is_dataclass(v) and field_name not in v.__dataclass_fields__
 
 
 def extract_dataclass_fields(
@@ -339,7 +425,7 @@ def dataclass_to_dict(
             ret[field.name] = dataclass_to_dict(value, exclude_none, exclude_empty)
         else:
             ret[field.name] = getattr(obj, field.name)
-    return ret
+    return cast("dict[str, Any]", ret)
 
 
 def schema_dump(
@@ -355,13 +441,15 @@ def schema_dump(
     Returns:
         :type: dict[str, Any]
     """
+    if is_dict(data):
+        return data
     if is_dataclass(data):
         return dataclass_to_dict(data, exclude_empty=exclude_unset)
     if is_pydantic_model(data):
         return data.model_dump(exclude_unset=exclude_unset)
-    if is_msgspec_model(data) and exclude_unset:
+    if is_msgspec_struct(data) and exclude_unset:
         return {f: val for f in data.__struct_fields__ if (val := getattr(data, f, None)) != UNSET}
-    if is_msgspec_model(data) and not exclude_unset:
+    if is_msgspec_struct(data) and not exclude_unset:
         return {f: getattr(data, f, None) for f in data.__struct_fields__}
     return cast("dict[str,Any]", data)
 
@@ -394,9 +482,9 @@ __all__ = (
     "is_dict",
     "is_dict_with_field",
     "is_dict_without_field",
-    "is_msgspec_model",
-    "is_msgspec_model_with_field",
-    "is_msgspec_model_without_field",
+    "is_msgspec_struct",
+    "is_msgspec_struct_with_field",
+    "is_msgspec_struct_without_field",
     "is_pydantic_model",
     "is_pydantic_model_with_field",
     "is_pydantic_model_without_field",

sqlspec/utils/deprecation.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import inspect
+from functools import wraps
+from typing import Callable, Literal
+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: str | None = None,
+    alternative: str | None = None,
+    info: str | None = None,
+    pending: bool = False,
+) -> None:
+    """Warn about a call to a (soon to be) deprecated function.
+
+    Args:
+        version: Advanced Alchemy 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
+        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!r}")  # pyright: ignore[reportUnknownMemberType]
+    else:
+        parts.append(f"{access_type} deprecated {kind} {deprecated_name!r}")  # pyright: ignore[reportUnknownMemberType]
+
+    parts.extend(  # pyright: ignore[reportUnknownMemberType]
+        (
+            f"Deprecated in advanced-alchemy {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: str | None = None,
+    alternative: str | None = None,
+    info: str | None = None,
+    pending: bool = False,
+    kind: Literal["function", "method", "classmethod", "property"] | None = 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.
+
+    Args:
+        version: Litestar version where the deprecation will occur
+        removal_in: Litestar 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,66 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlspec._serialization import decode_json
+from sqlspec.exceptions import MissingDependencyError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from anyio import Path as AsyncPath
+
+__all__ = ("open_fixture", "open_fixture_async")
+
+
+def open_fixture(fixtures_path: Path | AsyncPath, fixture_name: str) -> Any:
+    """Loads JSON file with the specified fixture name
+
+    Args:
+        fixtures_path: :class:`pathlib.Path` | :class:`anyio.Path` The path to look for fixtures
+        fixture_name (str): The fixture name to load.
+
+    Raises:
+        :class:`FileNotFoundError`: Fixtures not found.
+
+    Returns:
+        Any: The parsed JSON data
+    """
+    from pathlib import Path
+
+    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: Path | AsyncPath, fixture_name: str) -> Any:
+    """Loads JSON file with the specified fixture name
+
+    Args:
+        fixtures_path: :class:`pathlib.Path` | :class:`anyio.Path` The path to look for fixtures
+        fixture_name (str): The fixture name to load.
+
+    Raises:
+        :class:`~advanced_alchemy.exceptions.MissingDependencyError`: The `anyio` library is required to use this function.
+        :class:`FileNotFoundError`: Fixtures not found.
+
+    Returns:
+        Any: The parsed JSON data
+    """
+    try:
+        from anyio import Path as AsyncPath
+    except ImportError as exc:
+        msg = "The `anyio` library is required to use this function. Please install it with `pip install anyio`."
+        raise MissingDependencyError(msg) 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/module_loader.py

@@ -0,0 +1,94 @@
+"""General utility functions."""
+
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+__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`.
+
+    Args:
+        dotted_path: The path to the module. Defaults to "app".
+
+    Raises:
+        TypeError: The module could not be found.
+
+    Returns:
+        Path: 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:
+    """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.
+
+    Args:
+        dotted_path: The path of the module to import.
+
+    Raises:
+        ImportError: Could not import the module.
+
+    Returns:
+        object: The imported object.
+    """
+
+    def _is_loaded(module: ModuleType | None) -> bool:
+        spec = getattr(module, "__spec__", None)
+        initializing = getattr(spec, "_initializing", False)
+        return bool(module and spec and not initializing)
+
+    def _cached_import(module_path: str, class_name: str) -> Any:
+        """Import and cache a class from a module.
+
+        Args:
+            module_path: dotted path to module.
+            class_name: Class or function name.
+
+        Returns:
+            object: The imported class or function
+        """
+        # Check whether module is loaded and fully initialized.
+        module = sys.modules.get(module_path)
+        if not _is_loaded(module):
+            module = import_module(module_path)
+        return getattr(module, class_name)
+
+    try:
+        module_path, class_name = dotted_path.rsplit(".", 1)
+    except ValueError as e:
+        msg = "%s doesn't look like a module path"
+        raise ImportError(msg, dotted_path) from e
+
+    try:
+        return _cached_import(module_path, class_name)
+    except AttributeError as e:
+        msg = "Module '%s' does not define a '%s' attribute/class"
+        raise ImportError(msg, module_path, class_name) from e

sqlspec/utils/text.py

@@ -0,0 +1,46 @@
+"""General utility functions."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+__all__ = (
+    "check_email",
+    "slugify",
+)
+
+
+def check_email(email: str) -> str:
+    """Validate an email."""
+    if "@" not in email:
+        msg = "Invalid email!"
+        raise ValueError(msg)
+    return email.lower()
+
+
+def slugify(value: str, allow_unicode: bool = False, separator: str | None = 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.
+
+    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.
+
+    Returns:
+        str: a slugified string of the value parameter
+    """
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode("ascii")
+    value = re.sub(r"[^\w\s-]", "", value.lower())
+    if separator is not None:
+        return re.sub(r"[-\s]+", "-", value).strip("-_").replace("-", separator)
+    return re.sub(r"[-\s]+", "-", value).strip("-_")