[docker-py] Add some return types to DockerClient method (#15069)

Author: roberfi

stubs/docker/docker/api/daemon.pyi

@@ -1,18 +1,26 @@
-from _typeshed import Incomplete
 from datetime import datetime
-from typing import Any
+from typing import Any, Literal, overload
 
 from docker.types.daemon import CancellableStream
 
 class DaemonApiMixin:
     def df(self) -> dict[str, Any]: ...
+    @overload
     def events(
         self,
         since: datetime | int | None = None,
         until: datetime | int | None = None,
         filters: dict[str, Any] | None = None,
-        decode: bool | None = None,
-    ) -> CancellableStream[Incomplete]: ...
+        decode: Literal[False] | None = None,
+    ) -> CancellableStream[str]: ...
+    @overload
+    def events(
+        self,
+        since: datetime | int | None = None,
+        until: datetime | int | None = None,
+        filters: dict[str, Any] | None = None,
+        decode: Literal[True] = ...,
+    ) -> CancellableStream[dict[str, Any]]: ...
     def info(self) -> dict[str, Any]: ...
     def login(
         self,

stubs/docker/docker/client.pyi

@@ -1,5 +1,5 @@
 from collections.abc import Iterable
-from typing import NoReturn, Protocol, type_check_only
+from typing import Any, Literal, NoReturn, Protocol, overload, type_check_only
 
 from docker import APIClient
 from docker.models.configs import ConfigCollection
@@ -12,6 +12,7 @@ from docker.models.secrets import SecretCollection
 from docker.models.services import ServiceCollection
 from docker.models.swarm import Swarm
 from docker.models.volumes import VolumeCollection
+from docker.types import CancellableStream
 
 @type_check_only
 class _Environ(Protocol):
@@ -51,13 +52,16 @@ class DockerClient:
     def swarm(self) -> Swarm: ...
     @property
     def volumes(self) -> VolumeCollection: ...
-    def events(self, *args, **kwargs): ...
-    def df(self): ...
-    def info(self, *args, **kwargs): ...
-    def login(self, *args, **kwargs): ...
-    def ping(self, *args, **kwargs): ...
-    def version(self, *args, **kwargs): ...
-    def close(self): ...
+    @overload
+    def events(self, *args, decode: Literal[False] | None = None, **kwargs) -> CancellableStream[str]: ...
+    @overload
+    def events(self, *args, decode: Literal[True] = ..., **kwargs) -> CancellableStream[dict[str, Any]]: ...
+    def df(self) -> dict[str, Any]: ...
+    def info(self, *args, **kwargs) -> dict[str, Any]: ...
+    def login(self, *args, **kwargs) -> dict[str, Any]: ...
+    def ping(self, *args, **kwargs) -> bool: ...
+    def version(self, *args, **kwargs) -> dict[str, Any]: ...
+    def close(self) -> None: ...
     def __getattr__(self, name: str) -> NoReturn: ...
 
 from_env = DockerClient.from_env