From ef9f9628c0ec85a5107de51568e57cbd459cce17 Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Fri, 10 May 2024 09:15:17 +0100 Subject: [PATCH 1/4] Add return type to Docker Container.logs The documentation at https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.logs says "generator or str", but https://github.com/docker/docker-py/pull/2240 will change this to say "generator of bytes or bytes". --- stubs/docker/docker/api/container.pyi | 3 ++- stubs/docker/docker/models/containers.pyi | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/stubs/docker/docker/api/container.pyi b/stubs/docker/docker/api/container.pyi index 267e763bfd20..9db37a114616 100644 --- a/stubs/docker/docker/api/container.pyi +++ b/stubs/docker/docker/api/container.pyi @@ -1,4 +1,5 @@ from _typeshed import Incomplete +from collections.abc import Generator class ContainerApiMixin: def attach( @@ -77,7 +78,7 @@ class ContainerApiMixin: since: Incomplete | None = None, follow: Incomplete | None = None, until: Incomplete | None = None, - ): ... + ) -> Generator[bytes, None, None] | bytes: ... def pause(self, container) -> None: ... def port(self, container, private_port): ... def put_archive(self, container, path, data): ... diff --git a/stubs/docker/docker/models/containers.pyi b/stubs/docker/docker/models/containers.pyi index 524920e9493e..298b2a4997bf 100644 --- a/stubs/docker/docker/models/containers.pyi +++ b/stubs/docker/docker/models/containers.pyi @@ -1,4 +1,5 @@ from _typeshed import Incomplete +from collections.abc import Generator from typing import NamedTuple from .resource import Collection, Model @@ -39,7 +40,7 @@ class Container(Model): def export(self, chunk_size=2097152): ... def get_archive(self, path, chunk_size=2097152, encode_stream: bool = False): ... def kill(self, signal: Incomplete | None = None): ... - def logs(self, **kwargs): ... + def logs(self, **kwargs) -> Generator[bytes, None, None] | bytes: ... def pause(self): ... def put_archive(self, path, data): ... def remove(self, **kwargs) -> None: ... From 96dbb34fceac76170ecbc5bd30584b3012ffcda1 Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Sat, 11 May 2024 11:20:05 +0100 Subject: [PATCH 2/4] Use 'CancellableStream' as a return type for docker logs call --- stubs/docker/docker/api/container.pyi | 5 +++-- stubs/docker/docker/models/containers.pyi | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/stubs/docker/docker/api/container.pyi b/stubs/docker/docker/api/container.pyi index 9db37a114616..eff437d0e045 100644 --- a/stubs/docker/docker/api/container.pyi +++ b/stubs/docker/docker/api/container.pyi @@ -1,5 +1,6 @@ from _typeshed import Incomplete -from collections.abc import Generator + +from docker.types.daemon import CancellableStream class ContainerApiMixin: def attach( @@ -78,7 +79,7 @@ class ContainerApiMixin: since: Incomplete | None = None, follow: Incomplete | None = None, until: Incomplete | None = None, - ) -> Generator[bytes, None, None] | bytes: ... + ) -> CancellableStream | bytes: ... def pause(self, container) -> None: ... def port(self, container, private_port): ... def put_archive(self, container, path, data): ... diff --git a/stubs/docker/docker/models/containers.pyi b/stubs/docker/docker/models/containers.pyi index 298b2a4997bf..300fddb292c4 100644 --- a/stubs/docker/docker/models/containers.pyi +++ b/stubs/docker/docker/models/containers.pyi @@ -1,7 +1,8 @@ from _typeshed import Incomplete -from collections.abc import Generator from typing import NamedTuple +from docker.types.daemon import CancellableStream + from .resource import Collection, Model class Container(Model): @@ -40,7 +41,7 @@ class Container(Model): def export(self, chunk_size=2097152): ... def get_archive(self, path, chunk_size=2097152, encode_stream: bool = False): ... def kill(self, signal: Incomplete | None = None): ... - def logs(self, **kwargs) -> Generator[bytes, None, None] | bytes: ... + def logs(self, **kwargs) -> CancellableStream | bytes: ... def pause(self): ... def put_archive(self, path, data): ... def remove(self, **kwargs) -> None: ... From f4a54f6c378cc26e45de90a7121e54990353ab1f Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Sat, 11 May 2024 11:48:34 +0100 Subject: [PATCH 3/4] Use @overload on Docker logs method to show different return types --- stubs/docker/docker/api/container.pyi | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/stubs/docker/docker/api/container.pyi b/stubs/docker/docker/api/container.pyi index eff437d0e045..c0dd2a3542a8 100644 --- a/stubs/docker/docker/api/container.pyi +++ b/stubs/docker/docker/api/container.pyi @@ -1,4 +1,5 @@ from _typeshed import Incomplete +from typing import Literal, overload from docker.types.daemon import CancellableStream @@ -68,18 +69,33 @@ class ContainerApiMixin: def get_archive(self, container, path, chunk_size=2097152, encode_stream: bool = False): ... def inspect_container(self, container): ... def kill(self, container, signal: Incomplete | None = None) -> None: ... + @overload def logs( self, container, stdout: bool = True, stderr: bool = True, - stream: bool = False, + stream: Literal[False] = False, timestamps: bool = False, tail: str = "all", since: Incomplete | None = None, follow: Incomplete | None = None, until: Incomplete | None = None, - ) -> CancellableStream | bytes: ... + ) -> bytes: ... + @overload + def logs( + self, + container, + stdout: bool = True, + stderr: bool = True, + *, + stream: Literal[True], + timestamps: bool = False, + tail: str = "all", + since: Incomplete | None = None, + follow: Incomplete | None = None, + until: Incomplete | None = None, + ) -> CancellableStream: ... def pause(self, container) -> None: ... def port(self, container, private_port): ... def put_archive(self, container, path, data): ... From 8ccc147ef20701df47fd593894e869628f97c393 Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Sun, 12 May 2024 12:20:48 +0100 Subject: [PATCH 4/4] Address review comments to handle overload correctly --- stubs/docker/docker/api/container.pyi | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/stubs/docker/docker/api/container.pyi b/stubs/docker/docker/api/container.pyi index c270afd21712..9deb1d16d76b 100644 --- a/stubs/docker/docker/api/container.pyi +++ b/stubs/docker/docker/api/container.pyi @@ -75,27 +75,40 @@ class ContainerApiMixin: container, stdout: bool = True, stderr: bool = True, - stream: Literal[False] = False, + *, + stream: Literal[True], timestamps: bool = False, tail: Literal["all"] | int = "all", since: Incomplete | None = None, follow: Incomplete | None = None, until: Incomplete | None = None, - ) -> bytes: ... + ) -> CancellableStream: ... @overload def logs( self, container, - stdout: bool = True, - stderr: bool = True, - *, + stdout: bool, + stderr: bool, stream: Literal[True], timestamps: bool = False, - tail: str = "all", + tail: Literal["all"] | int = "all", since: Incomplete | None = None, follow: Incomplete | None = None, until: Incomplete | None = None, ) -> CancellableStream: ... + @overload + def logs( + self, + container, + stdout: bool = True, + stderr: bool = True, + stream: Literal[False] = False, + timestamps: bool = False, + tail: Literal["all"] | int = "all", + since: Incomplete | None = None, + follow: Incomplete | None = None, + until: Incomplete | None = None, + ) -> bytes: ... def pause(self, container) -> None: ... def port(self, container, private_port): ... def put_archive(self, container, path, data): ...