[docker] Fix some incomplete types (#14817)

stubs/docker/METADATA.toml

@@ -1,3 +1,3 @@
 version = "7.1.*"
 upstream_repository = "https://github.com/docker/docker-py"
-requires = ["types-requests", "urllib3>=2"]
+requires = ["types-paramiko", "types-requests", "urllib3>=2"]

stubs/docker/docker/api/image.pyi

@@ -1,7 +1,7 @@
-from _typeshed import Incomplete
+import logging
 from typing import Any
 
-log: Incomplete
+log: logging.Logger
 
 class ImageApiMixin:
     def get_image(self, image: str, chunk_size: int | None = 2097152): ...

stubs/docker/docker/api/swarm.pyi

@@ -1,9 +1,12 @@
-from _typeshed import Incomplete
+import logging
+from typing import Literal
 
-log: Incomplete
+from docker.types.swarm import SwarmSpec
+
+log: logging.Logger
 
 class SwarmApiMixin:
-    def create_swarm_spec(self, *args, **kwargs): ...
+    def create_swarm_spec(self, *args, **kwargs) -> SwarmSpec: ...
     def get_unlock_key(self): ...
     def init_swarm(
         self,
@@ -20,12 +23,12 @@ class SwarmApiMixin:
     def inspect_node(self, node_id): ...
     def join_swarm(
         self, remote_addrs, join_token, listen_addr: str = "0.0.0.0:2377", advertise_addr=None, data_path_addr=None
-    ): ...
-    def leave_swarm(self, force: bool = False): ...
+    ) -> Literal[True]: ...
+    def leave_swarm(self, force: bool = False) -> Literal[True]: ...
     def nodes(self, filters=None): ...
-    def remove_node(self, node_id, force: bool = False): ...
-    def unlock_swarm(self, key): ...
-    def update_node(self, node_id, version, node_spec=None): ...
+    def remove_node(self, node_id, force: bool = False) -> Literal[True]: ...
+    def unlock_swarm(self, key) -> Literal[True]: ...
+    def update_node(self, node_id, version, node_spec=None) -> Literal[True]: ...
     def update_swarm(
         self,
         version,
@@ -33,4 +36,4 @@ class SwarmApiMixin:
         rotate_worker_token: bool = False,
         rotate_manager_token: bool = False,
         rotate_manager_unlock_key: bool = False,
-    ): ...
+    ) -> Literal[True]: ...

stubs/docker/docker/credentials/store.pyi

@@ -1,10 +1,10 @@
 from _typeshed import Incomplete
 
 class Store:
-    program: Incomplete
-    exe: Incomplete
+    program: str
+    exe: str | None
     environment: Incomplete
-    def __init__(self, program, environment=None) -> None: ...
+    def __init__(self, program: str, environment=None) -> None: ...
     def get(self, server): ...
     def store(self, server, username, secret): ...
     def erase(self, server) -> None: ...

stubs/docker/docker/errors.pyi

@@ -1,8 +1,8 @@
-from _typeshed import Incomplete
 from collections.abc import Iterator, Mapping
-from typing import NoReturn
+from typing import Any, NoReturn
 
 from docker.models.containers import Container
+from docker.models.images import Image
 from requests import HTTPError, Response
 
 class DockerException(Exception): ...
@@ -35,11 +35,13 @@ class NullResource(DockerException, ValueError): ...
 
 class ContainerError(DockerException):
     container: Container
-    exit_status: Incomplete
-    command: Incomplete
-    image: Incomplete
+    exit_status: int
+    command: str | list[str] | None
+    image: str | Image
     stderr: str | None
-    def __init__(self, container: Container, exit_status, command, image, stderr: str | None) -> None: ...
+    def __init__(
+        self, container: Container, exit_status: int, command: str | list[str] | None, image: str | Image, stderr: str | None
+    ) -> None: ...
 
 class StreamParseError(RuntimeError):
     msg: str
@@ -52,7 +54,7 @@ class BuildError(DockerException):
 
 class ImageLoadError(DockerException): ...
 
-def create_unexpected_kwargs_error(name, kwargs: Mapping[str, Incomplete]) -> NoReturn: ...
+def create_unexpected_kwargs_error(name, kwargs: Mapping[str, Any]) -> NoReturn: ...
 
 class MissingContextParameter(DockerException):
     param: str

stubs/docker/docker/models/services.pyi

@@ -1,5 +1,3 @@
-from _typeshed import Incomplete
-
 from .resource import Collection, Model
 
 class Service(Model):
@@ -21,7 +19,7 @@ class ServiceCollection(Collection[Service]):
     def get(self, service_id, insert_defaults=None): ...
     def list(self, **kwargs): ...
 
-CONTAINER_SPEC_KWARGS: Incomplete
-TASK_TEMPLATE_KWARGS: Incomplete
-CREATE_SERVICE_KWARGS: Incomplete
-PLACEMENT_KWARGS: Incomplete
+CONTAINER_SPEC_KWARGS: list[str]
+TASK_TEMPLATE_KWARGS: list[str]
+CREATE_SERVICE_KWARGS: list[str]
+PLACEMENT_KWARGS: list[str]

stubs/docker/docker/transport/npipeconn.pyi

@@ -1,29 +1,29 @@
-from _typeshed import Incomplete
-
 import urllib3
 import urllib3.connection
 from docker.transport.basehttpadapter import BaseHTTPAdapter
+from docker.transport.npipesocket import NpipeSocket
+from urllib3._collections import RecentlyUsedContainer as urllib3_RecentlyUsedContainer
 
-RecentlyUsedContainer: Incomplete
+RecentlyUsedContainer = urllib3_RecentlyUsedContainer
 
 class NpipeHTTPConnection(urllib3.connection.HTTPConnection):
-    npipe_path: Incomplete
-    timeout: Incomplete
-    def __init__(self, npipe_path, timeout: int = 60) -> None: ...
-    sock: Incomplete
+    npipe_path: str
+    timeout: int
+    def __init__(self, npipe_path: str, timeout: int = 60) -> None: ...
+    sock: NpipeSocket | None
     def connect(self) -> None: ...
 
 class NpipeHTTPConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
-    npipe_path: Incomplete
-    timeout: Incomplete
-    def __init__(self, npipe_path, timeout: int = 60, maxsize: int = 10) -> None: ...
+    npipe_path: str
+    timeout: urllib3.Timeout
+    def __init__(self, npipe_path: str, timeout: int = 60, maxsize: int = 10) -> None: ...
 
 class NpipeHTTPAdapter(BaseHTTPAdapter):
-    __attrs__: Incomplete
-    npipe_path: Incomplete
-    timeout: Incomplete
-    max_pool_size: Incomplete
-    pools: Incomplete
-    def __init__(self, base_url, timeout: int = 60, pool_connections=..., max_pool_size=...) -> None: ...
+    __attrs__: list[str]
+    npipe_path: str
+    timeout: int
+    max_pool_size: int
+    pools: RecentlyUsedContainer
+    def __init__(self, base_url: str, timeout: int = 60, pool_connections: int = 25, max_pool_size: int = 10) -> None: ...
     def get_connection(self, url, proxies=None): ...
     def request_url(self, request, proxies): ...

stubs/docker/docker/transport/npipesocket.pyi

@@ -1,5 +1,7 @@
 import io
-from _typeshed import Incomplete
+from _typeshed import ReadableBuffer
+from typing import Any, Literal, NoReturn
+from typing_extensions import TypeAlias
 
 cERROR_PIPE_BUSY: int
 cSECURITY_SQOS_PRESENT: int
@@ -8,42 +10,48 @@ MAXIMUM_RETRY_COUNT: int
 
 def check_closed(f): ...
 
+_PyHANDLE: TypeAlias = Any  # pywin32._win32typing.PyHANDLE
+
 class NpipeSocket:
-    def __init__(self, handle=None) -> None: ...
+    def __init__(self, handle: _PyHANDLE | None = None) -> None: ...
     def accept(self) -> None: ...
     def bind(self, address) -> None: ...
     def close(self) -> None: ...
-    flags: Incomplete
-    def connect(self, address, retry_count: int = 0): ...
-    def connect_ex(self, address): ...
-    def detach(self): ...
-    def dup(self): ...
-    def getpeername(self): ...
-    def getsockname(self): ...
-    def getsockopt(self, level, optname, buflen=None) -> None: ...
-    def ioctl(self, control, option) -> None: ...
-    def listen(self, backlog) -> None: ...
-    def makefile(self, mode=None, bufsize=None): ...
-    def recv(self, bufsize, flags: int = 0): ...
-    def recvfrom(self, bufsize, flags: int = 0): ...
-    def recvfrom_into(self, buf, nbytes: int = 0, flags: int = 0): ...
-    def recv_into(self, buf, nbytes: int = 0): ...
-    def send(self, string, flags: int = 0): ...
-    def sendall(self, string, flags: int = 0): ...
-    def sendto(self, string, address): ...
-    def setblocking(self, flag): ...
-    def settimeout(self, value) -> None: ...
-    def gettimeout(self): ...
-    def setsockopt(self, level, optname, value) -> None: ...
-    def shutdown(self, how): ...
+    flags: int
+    def connect(self, address: str, retry_count: int = 0) -> None: ...
+    def connect_ex(self, address: str) -> None: ...
+    def detach(self) -> _PyHANDLE | None: ...
+    def dup(self) -> NpipeSocket: ...
+    def getpeername(self) -> str: ...
+    def getsockname(self) -> str: ...
+    # NotImplementedError
+    def getsockopt(self, level, optname, buflen=None) -> NoReturn: ...
+    # NotImplementedError
+    def ioctl(self, control, option) -> NoReturn: ...
+    # NotImplementedError
+    def listen(self, backlog) -> NoReturn: ...
+    def makefile(self, mode: str | None = None, bufsize: int | None = None) -> io.BufferedReader: ...
+    def recv(self, bufsize: int, flags: int = 0) -> str: ...
+    def recvfrom(self, bufsize: int, flags: int = 0) -> tuple[str, str]: ...
+    def recvfrom_into(self, buf: memoryview | ReadableBuffer, nbytes: int = 0, flags: int = 0) -> tuple[int, str]: ...
+    def recv_into(self, buf: memoryview | ReadableBuffer, nbytes: int = 0) -> int: ...
+    def send(self, string: str, flags: int = 0) -> int: ...
+    def sendall(self, string: str, flags: int = 0) -> int: ...
+    def sendto(self, string: str, address: str) -> int: ...
+    def setblocking(self, flag: bool) -> None: ...
+    def settimeout(self, value: float | None) -> None: ...
+    def gettimeout(self) -> int | None: ...
+    # NotImplementedError
+    def setsockopt(self, level, optname, value) -> NoReturn: ...
+    def shutdown(self, how) -> None: ...
 
 class NpipeFileIOBase(io.RawIOBase):
-    sock: Incomplete
-    def __init__(self, npipe_socket) -> None: ...
+    sock: NpipeSocket
+    def __init__(self, npipe_socket: NpipeSocket) -> None: ...
     def close(self) -> None: ...
     def fileno(self): ...
-    def isatty(self): ...
-    def readable(self): ...
-    def readinto(self, buf): ...
-    def seekable(self): ...
-    def writable(self): ...
+    def isatty(self) -> Literal[False]: ...
+    def readable(self) -> Literal[True]: ...
+    def readinto(self, buf: memoryview | ReadableBuffer) -> int: ...
+    def seekable(self) -> Literal[False]: ...
+    def writable(self) -> Literal[False]: ...

stubs/docker/docker/transport/sshconn.pyi

@@ -1,18 +1,20 @@
 import socket
-from _typeshed import Incomplete
+import subprocess
 
 import urllib3
 import urllib3.connection
 from docker.transport.basehttpadapter import BaseHTTPAdapter
+from paramiko import SSHClient, Transport
+from urllib3._collections import RecentlyUsedContainer as urllib3_RecentlyUsedContainer
 
-RecentlyUsedContainer: Incomplete
+RecentlyUsedContainer = urllib3_RecentlyUsedContainer
 
 class SSHSocket(socket.socket):
-    host: Incomplete
-    port: Incomplete
-    user: Incomplete
-    proc: Incomplete
-    def __init__(self, host) -> None: ...
+    host: str
+    port: str | None
+    user: str | None
+    proc: subprocess.Popen[bytes] | None
+    def __init__(self, host: str) -> None: ...
     def connect(self, **kwargs) -> None: ...  # type:ignore[override]
     def sendall(self, data) -> None: ...  # type:ignore[override]
     def send(self, data): ...  # type:ignore[override]
@@ -21,27 +23,31 @@ class SSHSocket(socket.socket):
     def close(self) -> None: ...
 
 class SSHConnection(urllib3.connection.HTTPConnection):
-    ssh_transport: Incomplete
-    timeout: Incomplete
-    ssh_host: Incomplete
-    def __init__(self, ssh_transport=None, timeout: int = 60, host=None) -> None: ...
-    sock: Incomplete
+    ssh_transport: Transport | None
+    timeout: int
+    ssh_host: str | None
+    def __init__(self, ssh_transport: Transport | None = None, timeout: int = 60, host: str | None = None) -> None: ...
+    sock: SSHSocket | None
     def connect(self) -> None: ...
 
 class SSHConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
     scheme: str
-    ssh_transport: Incomplete
-    timeout: Incomplete
-    ssh_host: Incomplete
-    def __init__(self, ssh_client=None, timeout: int = 60, maxsize: int = 10, host=None) -> None: ...
+    ssh_transport: Transport | None
+    timeout: urllib3.Timeout
+    ssh_host: str | None
+    def __init__(
+        self, ssh_client: SSHClient | None = None, timeout: int = 60, maxsize: int = 10, host: str | None = None
+    ) -> None: ...
 
 class SSHHTTPAdapter(BaseHTTPAdapter):
-    __attrs__: Incomplete
-    ssh_client: Incomplete
-    ssh_host: Incomplete
-    timeout: Incomplete
-    max_pool_size: Incomplete
-    pools: Incomplete
-    def __init__(self, base_url, timeout: int = 60, pool_connections=25, max_pool_size=10, shell_out: bool = False) -> None: ...
-    def get_connection(self, url, proxies=None): ...
+    __attrs__: list[str]
+    ssh_client: SSHClient | None
+    ssh_host: str
+    timeout: int
+    max_pool_size: int
+    pools: int
+    def __init__(
+        self, base_url: str, timeout: int = 60, pool_connections: int = 25, max_pool_size: int = 10, shell_out: bool = False
+    ) -> None: ...
+    def get_connection(self, url: str | bytes, proxies=None) -> SSHConnectionPool: ...
     def close(self) -> None: ...

stubs/docker/docker/transport/unixconn.pyi

@@ -1,31 +1,34 @@
-from _typeshed import Incomplete
+import socket
 
 import urllib3
 import urllib3.connection
 from docker.transport.basehttpadapter import BaseHTTPAdapter
+from requests import PreparedRequest
+from urllib3._collections import RecentlyUsedContainer as urllib3_RecentlyUsedContainer
 
-RecentlyUsedContainer: Incomplete
+RecentlyUsedContainer = urllib3_RecentlyUsedContainer
 
 class UnixHTTPConnection(urllib3.connection.HTTPConnection):
-    base_url: Incomplete
-    unix_socket: Incomplete
-    timeout: Incomplete
-    def __init__(self, base_url, unix_socket, timeout: int = 60) -> None: ...
-    sock: Incomplete
+    base_url: str
+    unix_socket: str
+    timeout: int
+    def __init__(self, base_url: str, unix_socket: str, timeout: int = 60) -> None: ...
+    sock: socket.socket | None
     def connect(self) -> None: ...
 
 class UnixHTTPConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
-    base_url: Incomplete
-    socket_path: Incomplete
-    timeout: Incomplete
-    def __init__(self, base_url, socket_path, timeout: int = 60, maxsize: int = 10) -> None: ...
+    base_url: str
+    socket_path: str
+    timeout: urllib3.Timeout
+    def __init__(self, base_url: str, socket_path: str, timeout: int = 60, maxsize: int = 10) -> None: ...
 
 class UnixHTTPAdapter(BaseHTTPAdapter):
-    __attrs__: Incomplete
-    socket_path: Incomplete
-    timeout: Incomplete
-    max_pool_size: Incomplete
-    pools: Incomplete
-    def __init__(self, socket_url, timeout: int = 60, pool_connections=25, max_pool_size=10) -> None: ...
-    def get_connection(self, url, proxies=None): ...
-    def request_url(self, request, proxies): ...
+    __attrs__: list[str]
+    socket_path: str
+    timeout: int
+    max_pool_size: int
+    pools: RecentlyUsedContainer
+    def __init__(self, socket_url: str, timeout: int = 60, pool_connections: int = 25, max_pool_size: int = 10) -> None: ...
+    def get_connection(self, url: bytes | str, proxies=None) -> UnixHTTPConnectionPool: ...
+    # proxies is unused
+    def request_url(self, request: PreparedRequest, proxies) -> str: ...

stubs/docker/docker/types/networks.pyi

@@ -5,7 +5,7 @@ class EndpointConfig(dict[str, Incomplete]):
     def __init__(
         self,
         version: str,
-        aliases: list[Incomplete] | None = None,
+        aliases: list[str] | None = None,
         links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
         ipv4_address: str | None = None,
         ipv6_address: str | None = None,

stubs/docker/docker/types/services.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Incomplete
 from collections.abc import Iterable, Mapping
-from typing import Final, Literal, TypeVar, overload
+from typing import Final, Literal, TypedDict, TypeVar, overload
 
 from .healthcheck import Healthcheck
 
@@ -36,12 +36,12 @@ class ContainerSpec(dict[str, Incomplete]):
         env: dict[str, Incomplete] | list[str] | None = None,
         workdir: str | None = None,
         user: str | None = None,
-        labels: dict[Incomplete, Incomplete] | None = None,
+        labels: dict[str, str] | None = None,
         mounts: Iterable[str | Mount] | None = None,
         stop_grace_period: int | None = None,
         secrets: list[SecretReference] | None = None,
         tty: bool | None = None,
-        groups: list[Incomplete] | None = None,
+        groups: list[str] | None = None,
         open_stdin: bool | None = None,
         read_only: bool | None = None,
         stop_signal: str | None = None,
@@ -52,9 +52,9 @@ class ContainerSpec(dict[str, Incomplete]):
         privileges: Privileges | None = None,
         isolation: str | None = None,
         init: bool | None = None,
-        cap_add: list[Incomplete] | None = None,
-        cap_drop: list[Incomplete] | None = None,
-        sysctls: dict[str, Incomplete] | None = None,
+        cap_add: list[str] | None = None,
+        cap_drop: list[str] | None = None,
+        sysctls: dict[str, str] | None = None,
     ) -> None: ...
 
 class Mount(dict[str, Incomplete]):
@@ -67,7 +67,7 @@ class Mount(dict[str, Incomplete]):
         consistency: Literal["default", "consistent", "cached", "delegated"] | None = None,
         propagation: str | None = None,
         no_copy: bool = False,
-        labels: dict[Incomplete, Incomplete] | None = None,
+        labels: dict[str, str] | None = None,
         driver_config: DriverConfig | None = None,
         tmpfs_size: int | str | None = None,
         tmpfs_mode: int | None = None,
@@ -75,6 +75,10 @@ class Mount(dict[str, Incomplete]):
     @classmethod
     def parse_mount_string(cls, string: str) -> Mount: ...
 
+class _ResourceDict(TypedDict):
+    Kind: str
+    Value: int
+
 class Resources(dict[str, Incomplete]):
     def __init__(
         self,
@@ -82,7 +86,9 @@ class Resources(dict[str, Incomplete]):
         mem_limit: int | None = None,
         cpu_reservation: int | None = None,
         mem_reservation: int | None = None,
-        generic_resources: dict[str, Incomplete] | list[str] | None = None,
+        generic_resources: (
+            dict[str, int | str] | list[dict[Literal["DiscreteResourceSpec", "NamedResourceSpec"], _ResourceDict]] | None
+        ) = None,
     ) -> None: ...
 
 class UpdateConfig(dict[str, Incomplete]):
@@ -110,7 +116,7 @@ class RestartPolicy(dict[str, Incomplete]):
     ) -> None: ...
 
 class DriverConfig(dict[str, Incomplete]):
-    def __init__(self, name: str, options: dict[Incomplete, Incomplete] | None = None) -> None: ...
+    def __init__(self, name: str, options: dict[str, str] | None = None) -> None: ...
 
 class EndpointSpec(dict[str, Incomplete]):
     def __init__(
@@ -185,4 +191,4 @@ class Privileges(dict[str, Incomplete]):
     ) -> None: ...
 
 class NetworkAttachmentConfig(dict[str, Incomplete]):
-    def __init__(self, target: str, aliases: list[str] | None = None, options: dict[str, Incomplete] | None = None) -> None: ...
+    def __init__(self, target: str, aliases: list[str] | None = None, options: dict[str, str] | None = None) -> None: ...

stubs/docker/docker/types/swarm.pyi

@@ -1,4 +1,3 @@
-from _typeshed import Incomplete
 from typing import Any
 
 from .services import DriverConfig
@@ -17,7 +16,7 @@ class SwarmSpec(dict[str, Any]):
         node_cert_expiry: int | None = None,
         external_cas: list[SwarmExternalCA] | None = None,
         name: str | None = None,
-        labels: dict[str, Incomplete] | None = None,
+        labels: dict[str, str] | None = None,
         signing_ca_cert: str | None = None,
         signing_ca_key: str | None = None,
         ca_force_rotate: int | None = None,
@@ -27,9 +26,5 @@ class SwarmSpec(dict[str, Any]):
 
 class SwarmExternalCA(dict[str, Any]):
     def __init__(
-        self,
-        url: str,
-        protocol: str | None = None,
-        options: dict[Incomplete, Incomplete] | None = None,
-        ca_cert: str | None = None,
+        self, url: str, protocol: str | None = None, options: dict[str, str] | None = None, ca_cert: str | None = None
     ) -> None: ...

stubs/docker/docker/utils/decorators.pyi

@@ -1,6 +1,10 @@
-from _typeshed import Incomplete
 from collections.abc import Callable
+from typing import TypeVar
+from typing_extensions import ParamSpec
 
-def check_resource(resource_name: str): ...
-def minimum_version(version: str): ...
-def update_headers(f: Callable[..., Incomplete]): ...
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+def check_resource(resource_name: str) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]: ...
+def minimum_version(version: str) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]: ...
+def update_headers(f: Callable[_P, _R]) -> Callable[_P, _R]: ...

stubs/docker/docker/utils/utils.pyi

@@ -1,5 +1,5 @@
 import datetime
-from _typeshed import FileDescriptorOrPath, Incomplete, ReadableBuffer
+from _typeshed import FileDescriptorOrPath, ReadableBuffer
 from collections.abc import Iterable, Mapping
 from shlex import _ShlexInstream
 from typing import Literal, NamedTuple, NoReturn, TypedDict, TypeVar, overload, type_check_only
@@ -38,7 +38,7 @@ def convert_port_bindings(
 @overload
 def convert_volume_binds(binds: list[_T]) -> list[_T]: ...
 @overload
-def convert_volume_binds(binds: Mapping[str | bytes, Incomplete]) -> list[str]: ...
+def convert_volume_binds(binds: Mapping[str | bytes, bytes | str | dict[str, bytes | str]]) -> list[str]: ...
 @overload
 def convert_tmpfs_mounts(tmpfs: dict[_K, _V]) -> dict[_K, _V]: ...
 @overload
@@ -56,8 +56,8 @@ def parse_host(
 ) -> Literal["http+unix:///var/run/docker.sock"]: ...
 @overload
 def parse_host(addr: str | None, is_win32: bool = False, tls: bool = False) -> str | bytes: ...
-def parse_devices(devices: Iterable[str | dict[str, Incomplete]]) -> list[dict[str, Incomplete]]: ...
-def kwargs_from_env(environment: Mapping[str, Incomplete] | None = None) -> _EnvKWArgs: ...
+def parse_devices(devices: Iterable[str | dict[str, str]]) -> list[dict[str, str]]: ...
+def kwargs_from_env(environment: Mapping[str, str] | None = None) -> _EnvKWArgs: ...
 def convert_filters(filters) -> str: ...
 def datetime_to_timestamp(dt: datetime.datetime) -> int: ...
 def parse_bytes(s: float | str) -> float: ...