[docker] Fix Container.attach() return type (#15155)

stubs/docker/@tests/test_cases/check_attach.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing_extensions import assert_type
+
+from docker.models.containers import Container
+
+
+def check_attach(c: Container) -> None:
+    assert_type(c.attach(), bytes)
+    assert_type(c.attach(stream=False), bytes)
+    for line in c.attach(stream=True):
+        assert_type(line, bytes)

stubs/docker/docker/api/container.pyi

@@ -24,15 +24,49 @@ class _TopResult(TypedDict):
 _Container: TypeAlias = _HasId | _HasID | str
 
 class ContainerApiMixin:
+    @overload
     def attach(
         self,
         container: _Container,
         stdout: bool = True,
         stderr: bool = True,
-        stream: bool = False,
+        stream: Literal[False] = False,
         logs: bool = False,
-        demux: bool = False,
-    ): ...
+        demux: Literal[False] = False,
+    ) -> bytes: ...
+    @overload
+    def attach(
+        self,
+        container: _Container,
+        stdout: bool = True,
+        stderr: bool = True,
+        stream: Literal[False] = False,
+        logs: bool = False,
+        *,
+        demux: Literal[True],
+    ) -> tuple[bytes | None, bytes | None]: ...
+    @overload
+    def attach(
+        self,
+        container: _Container,
+        stdout: bool = True,
+        stderr: bool = True,
+        *,
+        stream: Literal[True],
+        logs: bool = False,
+        demux: Literal[False] = False,
+    ) -> CancellableStream[bytes]: ...
+    @overload
+    def attach(
+        self,
+        container: _Container,
+        stdout: bool = True,
+        stderr: bool = True,
+        *,
+        stream: Literal[True],
+        logs: bool = False,
+        demux: Literal[True],
+    ) -> CancellableStream[tuple[bytes | None, bytes | None]]: ...
     def attach_socket(self, container: _Container, params=None, ws: bool = False): ...
     def commit(
         self,

stubs/docker/docker/models/containers.pyi

@@ -39,9 +39,40 @@ class Container(Model):
     def health(self) -> str: ...
     @property
     def ports(self) -> dict[Incomplete, Incomplete]: ...
+    @overload
     def attach(
-        self, **kwargs
-    ) -> str | tuple[str | None, str | None] | CancellableStream[str] | CancellableStream[tuple[str | None, str | None]]: ...
+        self,
+        *,
+        stdout: bool = True,
+        stderr: bool = True,
+        stream: Literal[False] = False,
+        logs: bool = False,
+        demux: Literal[False] = False,
+    ) -> bytes: ...
+    @overload
+    def attach(
+        self,
+        *,
+        stdout: bool = True,
+        stderr: bool = True,
+        stream: Literal[False] = False,
+        logs: bool = False,
+        demux: Literal[True],
+    ) -> tuple[bytes | None, bytes | None]: ...
+    @overload
+    def attach(
+        self,
+        *,
+        stdout: bool = True,
+        stderr: bool = True,
+        stream: Literal[True],
+        logs: bool = False,
+        demux: Literal[False] = False,
+    ) -> CancellableStream[bytes]: ...
+    @overload
+    def attach(
+        self, *, stdout: bool = True, stderr: bool = True, stream: Literal[True], logs: bool = False, demux: Literal[True]
+    ) -> CancellableStream[tuple[bytes | None, bytes | None]]: ...
     def attach_socket(self, **kwargs) -> SocketIO | _BufferedReaderStream | SSHSocket: ...
     def commit(self, repository: str | None = None, tag: str | None = None, **kwargs) -> Image: ...
     def diff(self) -> list[dict[str, Incomplete]]: ...