Add Container wait return type at Docker model layer (#12217)

Also, improve type for the API layer. Previously, the type accounted for a 404 response. However, in the 404 case, a `docker.errors.NotFound` exception is raised.

stubs/docker/docker/_types.pyi

@@ -1,8 +1,19 @@
 # Internal-use module for types shared by multiple modules.
 # This does not match a module in docker-py.
 
-from typing_extensions import TypeAlias
+from typing import TypedDict, type_check_only
+from typing_extensions import NotRequired, TypeAlias
 
 # Type alias for JSON, explained at:
 # https://github.com/python/typing/issues/182#issuecomment-1320974824.
 JSON: TypeAlias = dict[str, JSON] | list[JSON] | str | int | float | bool | None
+
+# See https://docs.docker.com/engine/api/v1.42/#tag/Container/operation/ContainerWait
+@type_check_only
+class _WaitErrorDetails(TypedDict):
+    Message: str
+
+@type_check_only
+class WaitContainerResponse(TypedDict):
+    StatusCode: int
+    Error: NotRequired[_WaitErrorDetails]

stubs/docker/docker/api/container.pyi

@@ -1,8 +1,9 @@
 import datetime
 from _typeshed import Incomplete
 from typing import Literal, TypedDict, overload, type_check_only
-from typing_extensions import NotRequired, TypeAlias
+from typing_extensions import TypeAlias
 
+from docker._types import WaitContainerResponse
 from docker.types.daemon import CancellableStream
 
 from ..types import ContainerConfig, EndpointConfig, HostConfig, NetworkingConfig
@@ -15,21 +16,6 @@ class _HasId(TypedDict):
 class _HasID(TypedDict):
     ID: str
 
-@type_check_only
-class _WaitErrorDetails(TypedDict):
-    Message: str
-
-@type_check_only
-class _WaitContainerExistsResponse(TypedDict):
-    StatusCode: int
-    Error: NotRequired[_WaitErrorDetails]
-
-@type_check_only
-class _WaitNoSuchContainerErrorResponse(TypedDict):
-    message: str
-
-_WaitContainerResponseType: TypeAlias = _WaitContainerExistsResponse | _WaitNoSuchContainerErrorResponse
-
 _Container: TypeAlias = _HasId | _HasID | str
 
 class ContainerApiMixin:
@@ -179,4 +165,4 @@ class ContainerApiMixin:
         container: _Container,
         timeout: int | None = None,
         condition: Literal["not-running", "next-exit", "removed"] | None = None,
-    ) -> _WaitContainerResponseType: ...
+    ) -> WaitContainerResponse: ...

stubs/docker/docker/models/containers.pyi

@@ -2,6 +2,7 @@ import datetime
 from _typeshed import Incomplete
 from typing import Literal, NamedTuple, overload
 
+from docker._types import WaitContainerResponse
 from docker.types.daemon import CancellableStream
 
 from .images import Image
@@ -97,7 +98,9 @@ class Container(Model):
         kernel_memory: int | str | None = None,
         restart_policy: Incomplete | None = None,
     ): ...
-    def wait(self, *, timeout: float | None = None, condition: Literal["not-running", "next-exit", "removed"] | None = None): ...
+    def wait(
+        self, *, timeout: float | None = None, condition: Literal["not-running", "next-exit", "removed"] | None = None
+    ) -> WaitContainerResponse: ...
 
 class ContainerCollection(Collection[Container]):
     model: type[Container]