feat: Add support for UUID6 and UUID7 based on Python version (#714)

Adds support for native UUID6/7 in supported Python installations.

Close #713 

Signed-off-by: lajxw <46254113+lajxw@users.noreply.github.com>
Co-authored-by: Cody Fincher <cody@litestar.dev>

Author: lajxw

README.md

@@ -44,7 +44,7 @@ offering:
     - Unified interface for various storage backends ([`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) and [`obstore`](https://developmentseed.org/obstore/latest/))
     - Optional lifecycle event hooks integrated with SQLAlchemy's event system to automatically save and delete files as records are inserted, updated, or deleted.
 - Optimized JSON types including a custom JSON type for Oracle
-- Integrated support for UUID6 and UUID7 using [`uuid-utils`](https://github.com/aminalaee/uuid-utils) (install with the `uuid` extra)
+- Integrated support for UUID6 and UUID7 ([`uuid-utils`](https://github.com/aminalaee/uuid-utils) when installed, otherwise native in Python 3.14+, with UUID4 fallback on older versions).
 - Integrated support for Nano ID using [`fastnanoid`](https://github.com/oliverlambson/fastnanoid) (install with the `nanoid` extra)
 - Custom encrypted text type with multiple backend support including [`pgcrypto`](https://www.postgresql.org/docs/current/pgcrypto.html) for PostgreSQL and the Fernet implementation from [`cryptography`](https://cryptography.io/en/latest/) for other databases
 - Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation

advanced_alchemy/mixins/uuid.py

@@ -1,18 +1,26 @@
 import logging
-from typing import TYPE_CHECKING, Any
-from uuid import UUID, uuid4
+import sys
+from typing import TYPE_CHECKING, Any, Callable
+from uuid import UUID
 
 from sqlalchemy.orm import Mapped, declarative_mixin, mapped_column
 
 from advanced_alchemy.mixins.sentinel import SentinelMixin
 from advanced_alchemy.types import UUID_UTILS_INSTALLED
 
+_PYTHON_SUPPORTS_UUID6_7 = sys.version_info >= (3, 14)
+
 if UUID_UTILS_INSTALLED and not TYPE_CHECKING:
     from uuid_utils.compat import (  # type: ignore[no-redef,unused-ignore]  # pyright: ignore[reportMissingImports]
         uuid4,
         uuid6,
         uuid7,
     )
+elif _PYTHON_SUPPORTS_UUID6_7:
+    from uuid import uuid4, uuid6, uuid7  # type: ignore[attr-defined]
+
+    uuid6: Callable[[], UUID]  # type: ignore[no-redef]
+    uuid7: Callable[[], UUID]  # type: ignore[no-redef]
 else:
     from uuid import uuid4  # type: ignore[no-redef,unused-ignore]
 
@@ -36,10 +44,14 @@ class UUIDv6PrimaryKey(SentinelMixin):
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
-        if not UUID_UTILS_INSTALLED and not cls.__module__.startswith("advanced_alchemy"):  # pragma: no cover
+        if (
+            not _PYTHON_SUPPORTS_UUID6_7
+            and not UUID_UTILS_INSTALLED
+            and not cls.__module__.startswith("advanced_alchemy")
+        ):  # pragma: no cover
             logger.warning("`uuid-utils` not installed, falling back to `uuid4` for UUID v6 generation.")
 
-    id: Mapped[UUID] = mapped_column(default=uuid6, primary_key=True, sort_order=-100)
+    id: Mapped[UUID] = mapped_column(default=uuid6, primary_key=True, sort_order=-100)  # pyright: ignore[reportUnknownArgumentType]
     """UUID Primary key column."""
 
 
@@ -49,8 +61,12 @@ class UUIDv7PrimaryKey(SentinelMixin):
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
-        if not UUID_UTILS_INSTALLED and not cls.__module__.startswith("advanced_alchemy"):  # pragma: no cover
+        if (
+            not _PYTHON_SUPPORTS_UUID6_7
+            and not UUID_UTILS_INSTALLED
+            and not cls.__module__.startswith("advanced_alchemy")
+        ):  # pragma: no cover
             logger.warning("`uuid-utils` not installed, falling back to `uuid4` for UUID v7 generation.")
 
-    id: Mapped[UUID] = mapped_column(default=uuid7, primary_key=True, sort_order=-100)
+    id: Mapped[UUID] = mapped_column(default=uuid7, primary_key=True, sort_order=-100)  # pyright: ignore[reportUnknownArgumentType]
     """UUID Primary key column."""

tests/unit/test_base.py

@@ -1,16 +1,65 @@
 # pyright: reportUnusedImport=false
 from __future__ import annotations
 
+import importlib
+import sys
+import types
+import uuid as uuid_module
 import warnings
 from typing import cast
 
+import pytest
 from sqlalchemy import Table, create_engine
 from sqlalchemy.dialects import mssql, oracle, postgresql
 from sqlalchemy.orm import declarative_mixin
 from sqlalchemy.schema import CreateTable
 
 from tests.helpers import purge_module
 
+_MISSING = object()
+
+
+def _reload_uuid_mixin(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    uuid_utils_installed: bool,
+    fake_uuid_utils_compat: types.ModuleType | None = None,
+    version_info: tuple[int, int, int, str, int] = (3, 14, 0, "final", 0),
+) -> types.ModuleType:
+    import advanced_alchemy.types as alchemy_types
+
+    module_names = ("advanced_alchemy.mixins.uuid", "uuid_utils.compat", "uuid_utils")
+    previous_modules = {name: sys.modules.get(name, _MISSING) for name in module_names}
+    mixins_package = sys.modules.get("advanced_alchemy.mixins")
+    previous_uuid_attr = getattr(mixins_package, "uuid", _MISSING) if mixins_package is not None else _MISSING
+
+    monkeypatch.setattr(sys, "version_info", version_info)
+    monkeypatch.setattr(alchemy_types, "UUID_UTILS_INSTALLED", object() if uuid_utils_installed else None)
+
+    try:
+        for name in module_names:
+            sys.modules.pop(name, None)
+        if mixins_package is not None and hasattr(mixins_package, "uuid"):
+            delattr(mixins_package, "uuid")
+        if fake_uuid_utils_compat is not None:
+            fake_uuid_utils = types.ModuleType("uuid_utils")
+            fake_uuid_utils.__path__ = []  # type: ignore[attr-defined]
+            sys.modules["uuid_utils"] = fake_uuid_utils
+            sys.modules["uuid_utils.compat"] = fake_uuid_utils_compat
+        return importlib.import_module("advanced_alchemy.mixins.uuid")
+    finally:
+        for name, previous_module in previous_modules.items():
+            if previous_module is _MISSING:
+                sys.modules.pop(name, None)
+            else:
+                sys.modules[name] = cast(types.ModuleType, previous_module)
+        if mixins_package is not None:
+            if previous_uuid_attr is _MISSING:
+                if hasattr(mixins_package, "uuid"):
+                    delattr(mixins_package, "uuid")
+            else:
+                setattr(mixins_package, "uuid", previous_uuid_attr)
+
 
 def test_deprecated_classes_functionality() -> None:
     """Test that mixins classes maintain have base functionality."""
@@ -49,6 +98,80 @@ def test_deprecated_classes_functionality() -> None:
     assert hasattr(audit, "updated_at")
 
 
+def test_uuid_utils_generators_are_preferred_when_installed_on_python_314(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that installing uuid-utils keeps uuid generation on uuid-utils."""
+
+    def native_uuid6() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    def native_uuid7() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    def uuid_utils_uuid4() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    def uuid_utils_uuid6() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    def uuid_utils_uuid7() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    monkeypatch.setattr(uuid_module, "uuid6", native_uuid6, raising=False)
+    monkeypatch.setattr(uuid_module, "uuid7", native_uuid7, raising=False)
+
+    fake_compat = types.ModuleType("uuid_utils.compat")
+    fake_compat.uuid4 = uuid_utils_uuid4  # type: ignore[attr-defined]
+    fake_compat.uuid6 = uuid_utils_uuid6  # type: ignore[attr-defined]
+    fake_compat.uuid7 = uuid_utils_uuid7  # type: ignore[attr-defined]
+
+    uuid_mixin = _reload_uuid_mixin(
+        monkeypatch,
+        uuid_utils_installed=True,
+        fake_uuid_utils_compat=fake_compat,
+    )
+
+    assert uuid_mixin.uuid4 is uuid_utils_uuid4
+    assert uuid_mixin.uuid6 is uuid_utils_uuid6
+    assert uuid_mixin.uuid7 is uuid_utils_uuid7
+
+
+def test_native_uuid_generators_are_used_on_python_314_without_uuid_utils(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that Python 3.14 native UUID generators are used without uuid-utils."""
+
+    def native_uuid6() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    def native_uuid7() -> uuid_module.UUID:
+        return uuid_module.uuid4()
+
+    monkeypatch.setattr(uuid_module, "uuid6", native_uuid6, raising=False)
+    monkeypatch.setattr(uuid_module, "uuid7", native_uuid7, raising=False)
+
+    uuid_mixin = _reload_uuid_mixin(monkeypatch, uuid_utils_installed=False)
+
+    assert uuid_mixin.uuid6 is native_uuid6
+    assert uuid_mixin.uuid7 is native_uuid7
+
+
+def test_uuid_generators_fall_back_to_uuid4_before_python_314_without_uuid_utils(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that UUID6/7 generators fall back to UUID4 before Python 3.14."""
+
+    uuid_mixin = _reload_uuid_mixin(
+        monkeypatch,
+        uuid_utils_installed=False,
+        version_info=(3, 13, 0, "final", 0),
+    )
+
+    assert uuid_mixin.uuid6 is uuid_mixin.uuid4
+    assert uuid_mixin.uuid7 is uuid_mixin.uuid4
+
+
 def test_identity_primary_key_generates_identity_ddl() -> None:
     """Test that IdentityPrimaryKey generates proper IDENTITY DDL for PostgreSQL."""
     from advanced_alchemy.base import BigIntBase