imprv: generate async overloads for finish-func methods

src/gi-stubs/_gi.pyi

@@ -1,15 +1,20 @@
 from typing import Any
 from typing import ClassVar
 from typing import Final
+from typing import final
+from typing import Generic
 from typing import Protocol
 from typing import type_check_only
 from typing_extensions import Self
+from typing_extensions import TypeVar
 
 from builtins import Warning as _Warning
 from collections.abc import Callable
+from collections.abc import Generator
 from collections.abc import Mapping
 from collections.abc import Sequence
 from contextlib import AbstractContextManager
+from contextvars import Context
 from enum import IntEnum
 from enum import IntFlag
 from inspect import Signature
@@ -18,6 +23,8 @@ from gi.repository import Gio
 from gi.repository import GLib
 from gi.repository import GObject as _GObject
 
+_T_co = TypeVar("_T_co", covariant=True, default=Any)
+
 G_MAXDOUBLE: Final[float]
 G_MAXFLOAT: Final[float]
 G_MAXINT: Final[int]
@@ -60,23 +67,24 @@ class ArrayType(int):
     C: ClassVar[int]
     PTR_ARRAY: ClassVar[int]
 
-class Async:
+@final
+class Async(Generic[_T_co]):
     cancellable: Gio.Cancellable | None
     def __init__(
         self, finish_func: CallableInfo, cancellable: Gio.Cancellable | None = None
     ) -> None: ...
     def add_done_callback(
-        self, callback: Callable[..., Any], *, context: object = None
+        self, callback: Callable[[Self], object], *, context: Context | None = None
     ) -> None: ...
-    def cancel(self) -> None: ...
+    def cancel(self, msg: str | None = None) -> None: ...
     def done(self) -> bool: ...
     def exception(self) -> BaseException | None: ...
-    def remove_done_callback(self, callback: Callable[..., Any], /) -> int: ...
-    def result(self) -> Any: ...
-    def __await__(self) -> Async: ...
+    def remove_done_callback(self, callback: Callable[[Self], object], /) -> int: ...
+    def result(self) -> _T_co: ...
+    def __await__(self) -> Generator[Self, Any, _T_co]: ...
     def __del__(self) -> None: ...
-    def __iter__(self) -> Async: ...
-    def __next__(self) -> Async: ...
+    def __iter__(self) -> Self: ...
+    def __next__(self) -> Self: ...
 
 class BaseInfo:
     def equal(self, object: BaseInfo, /) -> bool: ...
@@ -333,6 +341,7 @@ class ObjectProtocol(GObjectProtocol, Protocol):
 
 class GObject(GObjectProtocol):
     __gtype__: ClassVar[GType]
+    @type_check_only
     class Props: ...
 
     @property

src/gi-stubs/repository/Adw.pyi

@@ -1,6 +1,7 @@
 from typing import Any
 from typing import Final
 from typing import Literal
+from typing import overload
 from typing import Protocol
 from typing import type_check_only
 from typing import TypeAlias
@@ -1031,16 +1032,28 @@ class AlertDialog(Dialog):
         width_request: int = ...,
     ) -> None: ...
     def add_response(self, id: str, label: str) -> None: ...
+    @overload
     def choose(
         self,
         parent: _Gtk4.Widget | None = None,
         cancellable: Gio.Cancellable | None = None,
-        callback: Callable[
-            [GObject.Object | None, Gio.AsyncResult, Unpack[_DataTs]], None
-        ]
-        | None = None,
+    ) -> _gi.Async[str]: ...
+    @overload
+    def choose(
+        self,
+        parent: _Gtk4.Widget | None,
+        cancellable: Gio.Cancellable | None,
+        callback: Gio.AsyncReadyCallback[AlertDialog, Unpack[_DataTs]] | None,
         *user_data: Unpack[_DataTs],
     ) -> None: ...
+    @overload
+    def choose(
+        self,
+        parent: _Gtk4.Widget | None = None,
+        cancellable: Gio.Cancellable | None = None,
+        *,
+        callback: Gio.AsyncReadyCallback[AlertDialog] | None,
+    ) -> None: ...
     def choose_finish(self, result: Gio.AsyncResult) -> str: ...
     def do_response(self, response: str) -> None: ...
     def get_body(self) -> str: ...
@@ -5706,15 +5719,22 @@ class MessageDialog(_Gtk4.Window):
         width_request: int = ...,
     ) -> None: ...
     def add_response(self, id: str, label: str) -> None: ...
+    @overload
+    def choose(self, cancellable: Gio.Cancellable | None = None) -> _gi.Async[str]: ...
+    @overload
     def choose(
         self,
-        cancellable: Gio.Cancellable | None = None,
-        callback: Callable[
-            [GObject.Object | None, Gio.AsyncResult, Unpack[_DataTs]], None
-        ]
-        | None = None,
+        cancellable: Gio.Cancellable | None,
+        callback: Gio.AsyncReadyCallback[MessageDialog, Unpack[_DataTs]] | None,
         *user_data: Unpack[_DataTs],
     ) -> None: ...
+    @overload
+    def choose(
+        self,
+        cancellable: Gio.Cancellable | None = None,
+        *,
+        callback: Gio.AsyncReadyCallback[MessageDialog] | None,
+    ) -> None: ...
     def choose_finish(self, result: Gio.AsyncResult) -> str: ...
     def do_response(self, response: str) -> None: ...
     def get_body(self) -> str: ...

src/gi-stubs/repository/GdkPixbuf.pyi

@@ -1,6 +1,7 @@
 from typing import Any
 from typing import Final
 from typing import Literal
+from typing import overload
 from typing import type_check_only
 from typing import TypeAlias
 from typing_extensions import TypeVarTuple
@@ -181,16 +182,27 @@ class Pixbuf(GObject.Object, Gio.Icon, Gio.LoadableIcon):
     def get_colorspace(self) -> Colorspace: ...
     @staticmethod
     def get_file_info(filename: str) -> tuple[PixbufFormat | None, int, int]: ...
+    @overload
+    @staticmethod
+    def get_file_info_async(
+        filename: str, cancellable: Gio.Cancellable | None = None
+    ) -> _gi.Async[tuple[PixbufFormat | None, int, int]]: ...
+    @overload
     @staticmethod
     def get_file_info_async(
         filename: str,
-        cancellable: Gio.Cancellable | None = None,
-        callback: Callable[
-            [GObject.Object | None, Gio.AsyncResult, Unpack[_DataTs]], None
-        ]
-        | None = None,
+        cancellable: Gio.Cancellable | None,
+        callback: Gio.AsyncReadyCallback[None, Unpack[_DataTs]] | None,
         *user_data: Unpack[_DataTs],
     ) -> None: ...
+    @overload
+    @staticmethod
+    def get_file_info_async(
+        filename: str,
+        cancellable: Gio.Cancellable | None = None,
+        *,
+        callback: Gio.AsyncReadyCallback[None] | None,
+    ) -> None: ...
     @staticmethod
     def get_file_info_finish(
         async_result: Gio.AsyncResult,
@@ -263,16 +275,27 @@ class Pixbuf(GObject.Object, Gio.Icon, Gio.LoadableIcon):
     def new_from_stream(
         cls, stream: Gio.InputStream, cancellable: Gio.Cancellable | None = None
     ) -> Pixbuf | None: ...
+    @overload
+    @staticmethod
+    def new_from_stream_async(
+        stream: Gio.InputStream, cancellable: Gio.Cancellable | None = None
+    ) -> _gi.Async[Pixbuf | None]: ...
+    @overload
     @staticmethod
     def new_from_stream_async(
         stream: Gio.InputStream,
-        cancellable: Gio.Cancellable | None = None,
-        callback: Callable[
-            [GObject.Object | None, Gio.AsyncResult, Unpack[_DataTs]], None
-        ]
-        | None = None,
+        cancellable: Gio.Cancellable | None,
+        callback: Gio.AsyncReadyCallback[None, Unpack[_DataTs]] | None,
         *user_data: Unpack[_DataTs],
     ) -> None: ...
+    @overload
+    @staticmethod
+    def new_from_stream_async(
+        stream: Gio.InputStream,
+        cancellable: Gio.Cancellable | None = None,
+        *,
+        callback: Gio.AsyncReadyCallback[None] | None,
+    ) -> None: ...
     @classmethod
     def new_from_stream_at_scale(
         cls,
@@ -409,16 +432,27 @@ class PixbufAnimation(GObject.Object):
     def new_from_stream(
         cls, stream: Gio.InputStream, cancellable: Gio.Cancellable | None = None
     ) -> PixbufAnimation | None: ...
+    @overload
+    @staticmethod
+    def new_from_stream_async(
+        stream: Gio.InputStream, cancellable: Gio.Cancellable | None = None
+    ) -> _gi.Async[PixbufAnimation | None]: ...
+    @overload
     @staticmethod
     def new_from_stream_async(
         stream: Gio.InputStream,
-        cancellable: Gio.Cancellable | None = None,
-        callback: Callable[
-            [GObject.Object | None, Gio.AsyncResult, Unpack[_DataTs]], None
-        ]
-        | None = None,
+        cancellable: Gio.Cancellable | None,
+        callback: Gio.AsyncReadyCallback[None, Unpack[_DataTs]] | None,
         *user_data: Unpack[_DataTs],
     ) -> None: ...
+    @overload
+    @staticmethod
+    def new_from_stream_async(
+        stream: Gio.InputStream,
+        cancellable: Gio.Cancellable | None = None,
+        *,
+        callback: Gio.AsyncReadyCallback[None] | None,
+    ) -> None: ...
     @classmethod
     def new_from_stream_finish(
         cls, async_result: Gio.AsyncResult