Draft: ListMixin.list typing overload

igorp-collabora · igorp-collabora · commit 8cbf8a9673f1 · 2025-02-06T15:28:22.000Z
Overload `ListMixin.list` method typing to return either
`RESTObjectList` or `list` based on the passed options.
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
@@ -3,7 +3,8 @@
 import enum
 from collections.abc import Iterator
 from types import ModuleType
-from typing import Any, Callable, Literal, overload, TYPE_CHECKING
+from typing import Any, Callable, Literal, NoReturn, overload, TYPE_CHECKING
+from warnings import deprecated
 
 import requests
 
@@ -161,6 +162,34 @@ def refresh(self, **kwargs: Any) -> None:
 class ListMixin(HeadMixin[base.TObjCls]):
     _list_filters: tuple[str, ...] = ()
 
+    @overload
+    @deprecated(
+        "Calling a `list()` method without specifying `get_all=True` or "
+        "`iterator=True` will miss certain items because of pagination."
+    )
+    def list(
+        self,
+        get_all: Literal[False] = False,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> list[base.TObjCls]: ...
+
+    @overload
+    def list(
+        self,
+        get_all: Literal[False] = False,
+        iterator: Literal[True] = True,
+        **kwargs: Any,
+    ) -> base.RESTObjectList: ...
+
+    @overload
+    def list(
+        self,
+        get_all: Literal[True] = True,
+        iterator: Literal[False] = False,
+        **kwargs: Any,
+    ) -> list[base.TObjCls]: ...
+
     @exc.on_http_error(exc.GitlabListError)
     def list(self, **kwargs: Any) -> base.RESTObjectList | list[base.TObjCls]:
         """Retrieve a list of objects.
