overrides/Gio/ListStore: Add type annotations

Since we are already defining a type variable for the Generic parent class,
we might as well put it to good use and add type annotations to the methods.

These do not really appear to do anything other than serve as a documentation for now.

Had to disable E704 flake8 rule since it misplaces ellipsis.
In fact, this is why it is ignored in the default configuration:
https://github.com/PyCQA/pycodestyle/issues/973

2 files changed, 23 insertions, 9 deletions

diff --git a/gi/overrides/Gio.py b/gi/overrides/Gio.py
index 09c7d441..d34f4513 100644
--- a/gi/overrides/Gio.py
+++ b/gi/overrides/Gio.py
@@ -28,7 +28,7 @@ from gi import PyGIWarning
 from gi.repository import GLib
 from gi.repository import GObject
 
-from typing import Generic, TypeVar
+from typing import Callable, Generator, Generic, List, Sequence, TypeVar, Union, overload
 
 import sys
 
@@ -428,6 +428,11 @@ ObjectItemType = TypeVar('ObjectItemType', bound=GObject.Object)
 
 
 class ListModel(Gio.ListModel, Generic[ObjectItemType]):
+    @overload
+    def __getitem__(self, key: slice) -> List[ObjectItemType]: ...
+
+    @overload
+    def __getitem__(self, key: int) -> ObjectItemType: ...
 
     def __getitem__(self, key):
         if isinstance(key, slice):
@@ -444,7 +449,7 @@ class ListModel(Gio.ListModel, Generic[ObjectItemType]):
         else:
             raise TypeError
 
-    def __contains__(self, item):
+    def __contains__(self, item: ObjectItemType) -> bool:
         pytype = self.get_item_type().pytype
         if not isinstance(item, pytype):
             raise TypeError(
@@ -454,10 +459,10 @@ class ListModel(Gio.ListModel, Generic[ObjectItemType]):
                 return True
         return False
 
-    def __len__(self):
+    def __len__(self) -> int:
         return self.get_n_items()
 
-    def __iter__(self):
+    def __iter__(self) -> Generator[ObjectItemType, None, None]:
         for i in range(len(self)):
             yield self.get_item(i)
 
@@ -480,17 +485,20 @@ else:
 
 
 class ListStore(Gio.ListStore, Generic[ObjectItemType]):
-
-    def sort(self, compare_func, *user_data):
+    # Describing the variadic arguments requires TypeVarTuple and unpacking syntax in type annotation:
+    #   compare_func: Callable[Concatenate[ObjectItemType, ObjectItemType, *TypedVarTuple('Args')], int]
+    #   *user_data: *TypedVarTuple('Args')
+    # Since those are only available on Python ≥ 3.11, let’s keep the arguments untyped for now.
+    def sort(self, compare_func: Callable[..., int], *user_data) -> None:
         compare_func = wrap_list_store_sort_func(compare_func)
         return super(ListStore, self).sort(compare_func, *user_data)
 
-    def insert_sorted(self, item, compare_func, *user_data):
+    def insert_sorted(self, item: ObjectItemType, compare_func: Callable[..., int], *user_data) -> None:
         compare_func = wrap_list_store_sort_func(compare_func)
         return super(ListStore, self).insert_sorted(
             item, compare_func, *user_data)
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: Union[int, slice]) -> None:
         if isinstance(key, slice):
             start, stop, step = key.indices(len(self))
             if step == 1:
@@ -509,6 +517,12 @@ class ListStore(Gio.ListStore, Generic[ObjectItemType]):
         else:
             raise TypeError
 
+    @overload
+    def __setitem__(self, key: slice, value: Sequence[ObjectItemType]) -> None: ...
+
+    @overload
+    def __setitem__(self, key: int, value: ObjectItemType) -> None: ...
+
     def __setitem__(self, key, value):
         if isinstance(key, slice):
             pytype = self.get_item_type().pytype
diff --git a/setup.cfg b/setup.cfg
index c165fa29..091d2392 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,5 +1,5 @@
 [flake8]
-ignore=E501,E123,E124,E402,E731,E722,W504
+ignore=E501,E123,E124,E402,E704,E731,E722,W504
 exclude=subprojects
 
 [coverage:run]