fix: use typing.List to avoid list() method shadowing on Python 3.14 (#674)

On Python 3.14 (PEP 649), lazy annotation evaluation resolves bare
`list[...]` inside classes with a `list()` method to the method instead
of the builtin type. Replace with `typing.List` in all affected class
annotations.

Closes #659

Author: cofin

.github/workflows/ci.yml

@@ -169,7 +169,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install Microsoft ODBC
-        run: sudo ACCEPT_EULA=Y apt-get install msodbcsql18 -y
+        run: sudo apt-get update && sudo ACCEPT_EULA=Y apt-get install msodbcsql18 -y
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

.github/workflows/test.yml

@@ -31,7 +31,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install Microsoft ODBC Drivers
-        run: sudo ACCEPT_EULA=Y apt-get install msodbcsql18 -y
+        run: sudo apt-get update && sudo ACCEPT_EULA=Y apt-get install msodbcsql18 -y
 
       - name: Free additional space
         run: |

advanced_alchemy/repository/_async.py

@@ -4,7 +4,7 @@
 import string
 from collections import abc
 from collections.abc import Iterable
-from typing import Any, Optional, Union, cast, overload
+from typing import Any, List, Optional, Union, cast, overload
 from unittest.mock import create_autospec
 
 from sqlalchemy import (
@@ -58,7 +58,7 @@ class SQLAlchemyAsyncMockRepository(SQLAlchemyAsyncRepositoryProtocol[ModelT]):
     """Default execution options for the repository."""
     model_type: type[ModelT]
     id_attribute: Any = "id"
-    match_fields: Optional[Union[list[str], str]] = None
+    match_fields: Optional[Union[List[str], str]] = None
     uniquify: bool = False
     _exclude_kwargs: set[str] = {
         "statement",
@@ -87,7 +87,7 @@ def __init__(
         auto_expunge: bool = False,
         auto_refresh: bool = True,
         auto_commit: bool = False,
-        order_by: Optional[Union[list[OrderingPair], OrderingPair]] = None,
+        order_by: Optional[Union[List[OrderingPair], OrderingPair]] = None,
         error_messages: Optional[Union[ErrorMessages, EmptyType]] = Empty,
         wrap_exceptions: bool = True,
         load: Optional[LoadSpec] = None,
@@ -210,7 +210,7 @@ def _exclude_unused_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
         return {key: value for key, value in kwargs.items() if key not in self._exclude_kwargs}
 
     @staticmethod
-    def _apply_limit_offset_pagination(result: list[ModelT], limit: int, offset: int) -> list[ModelT]:
+    def _apply_limit_offset_pagination(result: List[ModelT], limit: int, offset: int) -> List[ModelT]:
         return result[offset:limit]
 
     def _extract_field_name(self, field: "Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]") -> str:
@@ -234,35 +234,35 @@ def _extract_field_name(self, field: "Union[str, ColumnElement[Any], Instrumente
 
     def _filter_in_collection(
         self,
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: "Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]",
         values: abc.Collection[Any],
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         field_str = self._extract_field_name(field_name)
         return [item for item in result if getattr(item, field_str) in values]
 
     def _filter_not_in_collection(
         self,
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: "Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]",
         values: abc.Collection[Any],
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         if not values:
             return result
         field_str = self._extract_field_name(field_name)
         return [item for item in result if getattr(item, field_str) not in values]
 
     def _filter_on_datetime_field(
         self,
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: "Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]",
         before: Optional[datetime.datetime] = None,
         after: Optional[datetime.datetime] = None,
         on_or_before: Optional[datetime.datetime] = None,
         on_or_after: Optional[datetime.datetime] = None,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         field_str = self._extract_field_name(field_name)
-        result_: list[ModelT] = []
+        result_: List[ModelT] = []
         for item in result:
             attr: datetime.datetime = getattr(item, field_str)
             if before is not None and attr < before:
@@ -277,14 +277,14 @@ def _filter_on_datetime_field(
 
     @staticmethod
     def _filter_by_like(
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: Union[str, set[str]],
         value: str,
         ignore_case: bool,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         pattern = re.compile(rf".*{value}.*", re.IGNORECASE) if ignore_case else re.compile(rf".*{value}.*")
         fields = {field_name} if isinstance(field_name, str) else field_name
-        items: list[ModelT] = []
+        items: List[ModelT] = []
         for field in fields:
             items.extend(
                 [
@@ -297,14 +297,14 @@ def _filter_by_like(
 
     @staticmethod
     def _filter_by_not_like(
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: Union[str, set[str]],
         value: str,
         ignore_case: bool,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         pattern = re.compile(rf".*{value}.*", re.IGNORECASE) if ignore_case else re.compile(rf".*{value}.*")
         fields = {field_name} if isinstance(field_name, str) else field_name
-        items: list[ModelT] = []
+        items: List[ModelT] = []
         for field in fields:
             items.extend(
                 [
@@ -320,7 +320,7 @@ def _filter_result_by_kwargs(
         result: Iterable[ModelT],
         /,
         kwargs: Union[dict[Any, Any], Iterable[tuple[Any, Any]]],
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         kwargs_: dict[Any, Any] = kwargs if isinstance(kwargs, dict) else dict(*kwargs)  # pyright: ignore
         kwargs_ = self._exclude_unused_kwargs(kwargs_)  # pyright: ignore
         try:
@@ -330,18 +330,18 @@ def _filter_result_by_kwargs(
 
     def _order_by(
         self,
-        result: list[ModelT],
+        result: List[ModelT],
         field_name: "Union[str, ColumnElement[Any], InstrumentedAttribute[Any]]",
         sort_desc: bool = False,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         return sorted(result, key=lambda item: getattr(item, self._extract_field_name(field_name)), reverse=sort_desc)
 
     def _apply_filters(
         self,
-        result: list[ModelT],
+        result: List[ModelT],
         *filters: Union[StatementFilter, ColumnElement[bool]],
         apply_pagination: bool = True,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         for filter_ in filters:
             if isinstance(filter_, LimitOffset):
                 if apply_pagination:
@@ -394,9 +394,9 @@ def _apply_filters(
 
     def _get_match_fields(
         self,
-        match_fields: Union[list[str], str, None],
+        match_fields: Union[List[str], str, None],
         id_attribute: Optional[str] = None,
-    ) -> Optional[list[str]]:
+    ) -> Optional[List[str]]:
         id_attribute = id_attribute or self.id_attribute
         match_fields = match_fields or self.match_fields
         if isinstance(match_fields, str):
@@ -407,22 +407,22 @@ async def _list_and_count_basic(
         self,
         *filters: Union[StatementFilter, ColumnElement[bool]],
         **kwargs: Any,
-    ) -> tuple[list[ModelT], int]:
+    ) -> tuple[List[ModelT], int]:
         result = await self.list(*filters, **kwargs)
         return result, len(result)
 
     async def _list_and_count_window(
         self,
         *filters: Union[StatementFilter, ColumnElement[bool]],
         **kwargs: Any,
-    ) -> tuple[list[ModelT], int]:
+    ) -> tuple[List[ModelT], int]:
         return await self._list_and_count_basic(*filters, **kwargs)
 
     def _find_or_raise_not_found(self, id_: Any) -> ModelT:
         return self.check_not_found(self.__collection__().get_or_none(id_))
 
     @staticmethod
-    def _find_one_or_raise_error(result: list[ModelT]) -> ModelT:
+    def _find_one_or_raise_error(result: List[ModelT]) -> ModelT:
         if not result:
             msg = "No item found when one was expected"
             raise IntegrityError(msg)
@@ -435,7 +435,7 @@ def _get_update_many_statement(
         self,
         model_type: type[ModelT],
         supports_returning: bool,
-        loader_options: Optional[list[_AbstractLoad]],
+        loader_options: Optional[List[_AbstractLoad]],
         execution_options: Optional[dict[str, Any]],
     ) -> Union[Update, ReturningUpdate[tuple[ModelT]]]:
         return self.statement  # type: ignore[no-any-return] # pyright: ignore[reportReturnType]
@@ -496,7 +496,7 @@ async def get_one_or_none(
     async def get_or_upsert(
         self,
         *filters: Union[StatementFilter, ColumnElement[bool]],
-        match_fields: Union[list[str], str, None] = None,
+        match_fields: Union[List[str], str, None] = None,
         upsert: bool = True,
         attribute_names: Optional[Iterable[str]] = None,
         with_for_update: ForUpdateParameter = None,
@@ -534,7 +534,7 @@ async def get_or_upsert(
     async def get_and_update(
         self,
         *filters: Union[StatementFilter, ColumnElement[bool]],
-        match_fields: Union[list[str], str, None] = None,
+        match_fields: Union[List[str], str, None] = None,
         attribute_names: Optional[Iterable[str]] = None,
         with_for_update: ForUpdateParameter = None,
         auto_commit: Optional[bool] = None,
@@ -606,13 +606,13 @@ async def add(
 
     async def add_many(
         self,
-        data: list[ModelT],
+        data: List[ModelT],
         *,
         auto_commit: Optional[bool] = None,
         auto_expunge: Optional[bool] = None,
         error_messages: Optional[Union[ErrorMessages, EmptyType]] = Empty,
         bind_group: Optional[str] = None,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         for obj in data:
             await self.add(obj)  # pyright: ignore[reportCallIssue]
         return data
@@ -638,7 +638,7 @@ async def update(
 
     async def update_many(
         self,
-        data: list[ModelT],
+        data: List[ModelT],
         *,
         auto_commit: Optional[bool] = None,
         auto_expunge: Optional[bool] = None,
@@ -647,7 +647,7 @@ async def update_many(
         execution_options: Optional[dict[str, Any]] = None,
         uniquify: Optional[bool] = None,
         bind_group: Optional[str] = None,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         return [self.__collection__().update(obj) for obj in data if obj in self.__collection__()]
 
     async def delete(
@@ -670,7 +670,7 @@ async def delete(
 
     async def delete_many(
         self,
-        item_ids: list[Any],
+        item_ids: List[Any],
         *,
         auto_commit: Optional[bool] = None,
         auto_expunge: Optional[bool] = None,
@@ -681,8 +681,8 @@ async def delete_many(
         execution_options: Optional[dict[str, Any]] = None,
         uniquify: Optional[bool] = None,
         bind_group: Optional[str] = None,
-    ) -> list[ModelT]:
-        deleted: list[ModelT] = []
+    ) -> List[ModelT]:
+        deleted: List[ModelT] = []
         for id_ in item_ids:
             if obj := self.__collection__().get_or_none(id_):
                 deleted.append(obj)
@@ -701,7 +701,7 @@ async def delete_where(
         uniquify: Optional[bool] = None,
         bind_group: Optional[str] = None,
         **kwargs: Any,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         result = self.__collection__().list()
         result = self._apply_filters(result, *filters)
         models = self._filter_result_by_kwargs(result, kwargs)
@@ -717,7 +717,7 @@ async def upsert(
         auto_expunge: Optional[bool] = None,
         auto_commit: Optional[bool] = None,
         auto_refresh: Optional[bool] = None,
-        match_fields: Optional[Union[list[str], str]] = None,
+        match_fields: Optional[Union[List[str], str]] = None,
         error_messages: Optional[Union[ErrorMessages, EmptyType]] = Empty,
         load: Optional[LoadSpec] = None,
         execution_options: Optional[dict[str, Any]] = None,
@@ -731,18 +731,18 @@ async def upsert(
 
     async def upsert_many(
         self,
-        data: list[ModelT],
+        data: List[ModelT],
         *,
         auto_expunge: Optional[bool] = None,
         auto_commit: Optional[bool] = None,
         no_merge: bool = False,
-        match_fields: Optional[Union[list[str], str]] = None,
+        match_fields: Optional[Union[List[str], str]] = None,
         error_messages: Optional[Union[ErrorMessages, EmptyType]] = Empty,
         load: Optional[LoadSpec] = None,
         execution_options: Optional[dict[str, Any]] = None,
         uniquify: Optional[bool] = None,
         bind_group: Optional[str] = None,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         return [await self.upsert(item) for item in data]
 
     async def list_and_count(
@@ -751,15 +751,15 @@ async def list_and_count(
         statement: Union[Select[tuple[ModelT]], StatementLambdaElement, None] = None,
         auto_expunge: Optional[bool] = None,
         count_with_window_function: Optional[bool] = None,
-        order_by: Optional[Union[list[OrderingPair], OrderingPair]] = None,
+        order_by: Optional[Union[List[OrderingPair], OrderingPair]] = None,
         error_messages: Optional[Union[ErrorMessages, EmptyType]] = Empty,
         load: Optional[LoadSpec] = None,
         execution_options: Optional[dict[str, Any]] = None,
         uniquify: Optional[bool] = None,
         use_cache: bool = True,
         bind_group: Optional[str] = None,
         **kwargs: Any,
-    ) -> tuple[list[ModelT], int]:
+    ) -> tuple[List[ModelT], int]:
         return await self._list_and_count_basic(*filters, **kwargs)
 
     async def list(
@@ -769,7 +769,7 @@ async def list(
         use_cache: bool = True,
         bind_group: Optional[str] = None,
         **kwargs: Any,
-    ) -> list[ModelT]:
+    ) -> List[ModelT]:
         result = self.__collection__().list()
         result = self._apply_filters(result, *filters)
         return self._filter_result_by_kwargs(result, kwargs)