feat: handle and compare numpy arrays (#550)

Direct equality comparisons (`!=`) with numpy arrays in repository update methods raised `ValueError: The truth value of an array with more than one element is ambiguous`

Adds a safe comparison utility that handle numpy arrays gracefully

Author: cofin

advanced_alchemy/repository/_async.py

@@ -49,6 +49,7 @@
     FilterableRepositoryProtocol,
     LoadSpec,
     column_has_defaults,
+    compare_values,
     get_abstract_loader_options,
     get_instrumented_attr,
 )
@@ -1293,7 +1294,7 @@ async def get_or_upsert(
             if upsert:
                 for field_name, new_field_value in kwargs.items():
                     field = getattr(existing, field_name, MISSING)
-                    if field is not MISSING and field != new_field_value:
+                    if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                         setattr(existing, field_name, new_field_value)
                 existing = await self._attach_to_session(existing, strategy="merge")
                 await self._flush_or_commit(auto_commit=auto_commit)
@@ -1367,7 +1368,7 @@ async def get_and_update(
             updated = False
             for field_name, new_field_value in kwargs.items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     updated = True
                     setattr(existing, field_name, new_field_value)
             existing = await self._attach_to_session(existing, strategy="merge")
@@ -1502,7 +1503,9 @@ async def update(
                             if new_field_value is None and column_has_defaults(column):
                                 continue
                             existing_field_value = getattr(existing_instance, field_name, MISSING)
-                            if existing_field_value is not MISSING and existing_field_value != new_field_value:
+                            if existing_field_value is not MISSING and not compare_values(
+                                existing_field_value, new_field_value
+                            ):
                                 setattr(existing_instance, field_name, new_field_value)
 
                     # Handle relationships by merging objects into session first
@@ -1940,7 +1943,7 @@ async def upsert(
         ):
             for field_name, new_field_value in data.to_dict(exclude={self.id_attribute}).items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)
             instance = await self._attach_to_session(existing, strategy="merge")
             await self._flush_or_commit(auto_commit=auto_commit)

advanced_alchemy/repository/_sync.py

@@ -50,6 +50,7 @@
     FilterableRepositoryProtocol,
     LoadSpec,
     column_has_defaults,
+    compare_values,
     get_abstract_loader_options,
     get_instrumented_attr,
 )
@@ -1294,7 +1295,7 @@ def get_or_upsert(
             if upsert:
                 for field_name, new_field_value in kwargs.items():
                     field = getattr(existing, field_name, MISSING)
-                    if field is not MISSING and field != new_field_value:
+                    if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                         setattr(existing, field_name, new_field_value)
                 existing = self._attach_to_session(existing, strategy="merge")
                 self._flush_or_commit(auto_commit=auto_commit)
@@ -1368,7 +1369,7 @@ def get_and_update(
             updated = False
             for field_name, new_field_value in kwargs.items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     updated = True
                     setattr(existing, field_name, new_field_value)
             existing = self._attach_to_session(existing, strategy="merge")
@@ -1503,7 +1504,9 @@ def update(
                             if new_field_value is None and column_has_defaults(column):
                                 continue
                             existing_field_value = getattr(existing_instance, field_name, MISSING)
-                            if existing_field_value is not MISSING and existing_field_value != new_field_value:
+                            if existing_field_value is not MISSING and not compare_values(
+                                existing_field_value, new_field_value
+                            ):
                                 setattr(existing_instance, field_name, new_field_value)
 
                     # Handle relationships by merging objects into session first
@@ -1939,7 +1942,7 @@ def upsert(
         ):
             for field_name, new_field_value in data.to_dict(exclude={self.id_attribute}).items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)
             instance = self._attach_to_session(existing, strategy="merge")
             self._flush_or_commit(auto_commit=auto_commit)

advanced_alchemy/repository/_typing.py

@@ -0,0 +1,90 @@
+"""Repository typing utilities for optional dependency support.
+
+Provides stubs and detection functions for numpy arrays to support
+pgvector and other array-based types when numpy is not installed.
+"""
+
+from typing import Any
+
+# Always define stub functions for type checking and fallback behavior
+
+
+def is_numpy_array_stub(value: Any) -> bool:  # pragma: no cover
+    """Check if value has numpy array-like characteristics (fallback implementation).
+
+    When numpy is not installed, this checks for basic array-like attributes
+    that indicate the value might be an array that needs special comparison handling.
+
+    Args:
+        value: Value to check.
+
+    Returns:
+        bool: True if value appears to be array-like.
+    """
+    return hasattr(value, "__array__") and hasattr(value, "dtype")  # pragma: no cover
+
+
+def arrays_equal_stub(a: Any, b: Any) -> bool:
+    """Fallback array equality comparison when numpy is not installed.
+
+    When numpy is not available, we can't properly compare arrays,
+    so we default to considering them different to trigger updates.
+    This ensures safety but may cause unnecessary updates.
+
+    Args:
+        a: First value to compare.
+        b: Second value to compare.
+
+    Returns:
+        bool: Always False when numpy is not available.
+    """
+    _, _ = a, b  # Unused parameters  # pragma: no cover
+    return False  # pragma: no cover
+
+
+# Try to import real numpy implementation at runtime
+try:
+    import numpy as np  # type: ignore[import-not-found,unused-ignore] # pyright: ignore[reportMissingImports]
+
+    def is_numpy_array_real(value: Any) -> bool:
+        """Check if value is a numpy array.
+
+        Args:
+            value: Value to check.
+
+        Returns:
+            bool: True if value is a numpy ndarray.
+        """
+        return isinstance(value, np.ndarray)  # pyright: ignore
+
+    def arrays_equal_real(a: Any, b: Any) -> bool:
+        """Compare numpy arrays for equality.
+
+        Uses numpy.array_equal for proper array comparison.
+
+        Args:
+            a: First array to compare.
+            b: Second array to compare.
+
+        Returns:
+            bool: True if arrays are equal.
+        """
+        return bool(np.array_equal(a, b))  # pyright: ignore
+
+    is_numpy_array = is_numpy_array_real
+    arrays_equal = arrays_equal_real
+    NUMPY_INSTALLED = True  # pyright: ignore[reportConstantRedefinition]
+
+except ImportError:  # pragma: no cover
+    is_numpy_array = is_numpy_array_stub
+    arrays_equal = arrays_equal_stub
+    NUMPY_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+
+__all__ = (
+    "NUMPY_INSTALLED",
+    "arrays_equal",
+    "arrays_equal_stub",
+    "is_numpy_array",
+    "is_numpy_array_stub",
+)

advanced_alchemy/repository/_util.py

@@ -34,6 +34,7 @@
     StatementFilter,
     StatementTypeT,
 )
+from advanced_alchemy.repository._typing import arrays_equal, is_numpy_array
 from advanced_alchemy.repository.typing import ModelT, OrderingPair
 
 WhereClauseT = ColumnExpressionArgument[bool]
@@ -368,3 +369,39 @@ def column_has_defaults(column: Any) -> bool:
         or getattr(column, "onupdate", None) is not None
         or getattr(column, "server_onupdate", None) is not None
     )
+
+
+def compare_values(existing_value: Any, new_value: Any) -> bool:
+    """Safely compare two values, handling numpy arrays and other special types.
+
+    This function handles the comparison of values that may include numpy arrays
+    (such as pgvector's Vector type) which cannot be directly compared using
+    standard equality operators due to their element-wise comparison behavior.
+
+    Args:
+        existing_value: The current value to compare.
+        new_value: The new value to compare against.
+
+    Returns:
+        bool: True if values are equal, False otherwise.
+    """
+    # Handle None comparisons
+    if existing_value is None and new_value is None:
+        return True
+    if existing_value is None or new_value is None:
+        return False
+
+    # Handle numpy arrays or array-like objects
+    if is_numpy_array(existing_value) or is_numpy_array(new_value):
+        # Both values must be arrays for them to be considered equal
+        if not (is_numpy_array(existing_value) and is_numpy_array(new_value)):
+            return False
+        return arrays_equal(existing_value, new_value)
+
+    # Standard equality comparison for all other types
+    try:
+        return bool(existing_value == new_value)
+    except (ValueError, TypeError):
+        # If comparison fails for any reason, consider them different
+        # This is a safe fallback that will trigger updates when unsure
+        return False

advanced_alchemy/repository/memory/_async.py

@@ -35,7 +35,7 @@
     StatementFilter,
 )
 from advanced_alchemy.repository._async import SQLAlchemyAsyncRepositoryProtocol, SQLAlchemyAsyncSlugRepositoryProtocol
-from advanced_alchemy.repository._util import DEFAULT_ERROR_MESSAGE_TEMPLATES, LoadSpec
+from advanced_alchemy.repository._util import DEFAULT_ERROR_MESSAGE_TEMPLATES, LoadSpec, compare_values
 from advanced_alchemy.repository.memory.base import (
     AnyObject,
     InMemoryStore,
@@ -490,7 +490,7 @@ async def get_or_upsert(
         if upsert:
             for field_name, new_field_value in kwargs_.items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)
             existing = await self.update(existing)
         return existing, False
@@ -524,7 +524,7 @@ async def get_and_update(
         updated = False
         for field_name, new_field_value in kwargs_.items():
             field = getattr(existing, field_name, MISSING)
-            if field is not MISSING and field != new_field_value:
+            if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                 updated = True
                 setattr(existing, field_name, new_field_value)
         existing = await self.update(existing)

advanced_alchemy/repository/memory/_sync.py

@@ -36,7 +36,7 @@
     StatementFilter,
 )
 from advanced_alchemy.repository._sync import SQLAlchemySyncRepositoryProtocol, SQLAlchemySyncSlugRepositoryProtocol
-from advanced_alchemy.repository._util import DEFAULT_ERROR_MESSAGE_TEMPLATES, LoadSpec
+from advanced_alchemy.repository._util import DEFAULT_ERROR_MESSAGE_TEMPLATES, LoadSpec, compare_values
 from advanced_alchemy.repository.memory.base import (
     AnyObject,
     InMemoryStore,
@@ -491,7 +491,7 @@ def get_or_upsert(
         if upsert:
             for field_name, new_field_value in kwargs_.items():
                 field = getattr(existing, field_name, MISSING)
-                if field is not MISSING and field != new_field_value:
+                if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)
             existing = self.update(existing)
         return existing, False
@@ -525,7 +525,7 @@ def get_and_update(
         updated = False
         for field_name, new_field_value in kwargs_.items():
             field = getattr(existing, field_name, MISSING)
-            if field is not MISSING and field != new_field_value:
+            if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                 updated = True
                 setattr(existing, field_name, new_field_value)
         existing = self.update(existing)

pyproject.toml

@@ -148,6 +148,8 @@ test = [
   "cattrs",
   "dishka ; python_version >= \"3.10\"",
   "pydantic-extra-types",
+  "numpy",
+  "pgvector",
   "rich-click",
   "coverage>=7.6.1",
   "fsspec[s3]",