[docker] Replace *args and **kwargs with explicit parameters

stubs/docker/@tests/stubtest_allowlist.txt

@@ -6,10 +6,8 @@ docker.transport.sshconn
 # model is always set by child classes
 docker.models.resource.Collection.model
 
-# keyword arguments are now unsupported
-docker.api.container.ContainerApiMixin.start
-
 # implementation has *args and **kwargs params that can't be used
+docker.api.container.ContainerApiMixin.start
 docker.client.DockerClient.info
 docker.client.DockerClient.ping
 

stubs/docker/docker/api/config.pyi

@@ -1,5 +1,13 @@
+from _typeshed import Incomplete
+
 class ConfigApiMixin:
-    def create_config(self, name, data, labels=None, templating=None): ...
+    def create_config(
+        self,
+        name: str,
+        data: bytes,
+        labels: dict[Incomplete, Incomplete] | None = None,
+        templating: dict[Incomplete, Incomplete] | None = None,
+    ): ...
     def inspect_config(self, id): ...
     def remove_config(self, id): ...
     def configs(self, filters=None): ...

stubs/docker/docker/api/container.pyi

@@ -1,12 +1,22 @@
 import datetime
 from _typeshed import Incomplete
+from collections.abc import Iterable, Mapping
 from typing import Any, Literal, TypeAlias, TypedDict, overload, type_check_only
+from typing_extensions import NotRequired
 
-from docker._types import WaitContainerResponse
+from docker._types import ContainerWeightDevice, WaitContainerResponse
+from docker.types.containers import DeviceRequest, LogConfig, Ulimit
 from docker.types.daemon import CancellableStream
+from docker.types.healthcheck import Healthcheck
+from docker.types.services import Mount
 
 from ..types import ContainerConfig, EndpointConfig, HostConfig, NetworkingConfig
 
+@type_check_only
+class _RestartPolicy(TypedDict):
+    MaximumRetryCount: NotRequired[int]
+    Name: NotRequired[Literal["always", "on-failure"]]
+
 @type_check_only
 class _HasId(TypedDict):
     Id: str
@@ -121,11 +131,116 @@ class ContainerApiMixin:
         use_config_proxy: bool = True,
         platform: str | None = None,
     ): ...
-    def create_container_config(self, *args, **kwargs) -> ContainerConfig: ...
+    # Please keep in sync with docker.types.ContainerConfig
+    def create_container_config(
+        self,
+        image: str,
+        command: str | list[str],
+        hostname: str | None = None,
+        user: str | int | None = None,
+        detach: bool = False,
+        stdin_open: bool = False,
+        tty: bool = False,
+        # list is invariant, enumerating all possible union combination would be too complex for:
+        # list[str | int | tuple[int | str, str] | tuple[int | str, ...]]
+        ports: dict[str, dict[str, str]] | list[Any] | None = None,
+        environment: dict[str, str] | list[str] | None = None,
+        volumes: str | list[str] | None = None,
+        network_disabled: bool = False,
+        entrypoint: str | list[str] | None = None,
+        working_dir: str | None = None,
+        domainname: str | None = None,
+        host_config: HostConfig | None = None,
+        mac_address: str | None = None,
+        labels: dict[str, str] | list[str] | None = None,
+        stop_signal: str | None = None,
+        networking_config: NetworkingConfig | None = None,
+        healthcheck: Healthcheck | None = None,
+        stop_timeout: int | None = None,
+        runtime: str | None = None,
+    ) -> ContainerConfig: ...
     def create_container_from_config(self, config, name=None, platform=None): ...
-    def create_host_config(self, *args, **kwargs) -> HostConfig: ...
-    def create_networking_config(self, *args, **kwargs) -> NetworkingConfig: ...
-    def create_endpoint_config(self, *args, **kwargs) -> EndpointConfig: ...
+    # Please keep in sync with docker.types.HostConfig
+    def create_host_config(
+        self,
+        binds: dict[str, Mapping[str, str]] | list[str] | None = None,
+        port_bindings: Mapping[int | str, Any] | None = None,  # Any: int, str, tuple, dict, or list
+        lxc_conf: dict[str, str] | list[dict[str, str]] | None = None,
+        publish_all_ports: bool = False,
+        links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
+        privileged: bool = False,
+        dns: list[str] | None = None,
+        dns_search: list[str] | None = None,
+        volumes_from: list[str] | None = None,
+        network_mode: str | None = None,
+        restart_policy: Mapping[str, str | int] | None = None,
+        cap_add: list[str] | None = None,
+        cap_drop: list[str] | None = None,
+        devices: list[str] | None = None,
+        extra_hosts: dict[str, str] | list[str] | None = None,
+        read_only: bool | None = None,
+        pid_mode: str | None = None,
+        ipc_mode: str | None = None,
+        security_opt: list[str] | None = None,
+        ulimits: list[Ulimit] | None = None,
+        log_config: LogConfig | None = None,
+        mem_limit: str | int | None = None,
+        memswap_limit: str | int | None = None,
+        mem_reservation: str | int | None = None,
+        kernel_memory: str | int | None = None,
+        mem_swappiness: int | None = None,
+        cgroup_parent: str | None = None,
+        group_add: Iterable[str | int] | None = None,
+        cpu_quota: int | None = None,
+        cpu_period: int | None = None,
+        blkio_weight: int | None = None,
+        blkio_weight_device: list[ContainerWeightDevice] | None = None,
+        device_read_bps: list[Mapping[str, str | int]] | None = None,
+        device_write_bps: list[Mapping[str, str | int]] | None = None,
+        device_read_iops: list[Mapping[str, str | int]] | None = None,
+        device_write_iops: list[Mapping[str, str | int]] | None = None,
+        oom_kill_disable: bool = False,
+        shm_size: str | int | None = None,
+        sysctls: dict[str, str] | None = None,
+        tmpfs: dict[str, str] | None = None,
+        oom_score_adj: int | None = None,
+        dns_opt: list[str] | None = None,
+        cpu_shares: int | None = None,
+        cpuset_cpus: str | None = None,
+        userns_mode: str | None = None,
+        uts_mode: str | None = None,
+        pids_limit: int | None = None,
+        isolation: str | None = None,
+        auto_remove: bool = False,
+        storage_opt: dict[str, str] | None = None,
+        init: bool | None = None,
+        init_path: str | None = None,
+        volume_driver: str | None = None,
+        cpu_count: int | None = None,
+        cpu_percent: int | None = None,
+        nano_cpus: int | None = None,
+        cpuset_mems: str | None = None,
+        runtime: str | None = None,
+        mounts: list[Mount] | None = None,
+        cpu_rt_period: int | None = None,
+        cpu_rt_runtime: int | None = None,
+        device_cgroup_rules: list[str] | None = None,
+        device_requests: list[DeviceRequest] | None = None,
+        cgroupns: Literal["private", "host"] | None = None,
+    ) -> HostConfig: ...
+    # Please keep in sync with docker.types.NetworkingConfig
+    def create_networking_config(self, endpoints_config: EndpointConfig | None = None) -> NetworkingConfig: ...
+    # Please keep in sync with docker.types.EndpointConfig
+    def create_endpoint_config(
+        self,
+        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,
+        link_local_ips: list[str] | None = None,
+        driver_opt: dict[str, str] | None = None,
+        mac_address: str | None = None,
+    ) -> EndpointConfig: ...
     def diff(self, container: _Container) -> list[dict[Incomplete, Incomplete]]: ...
     def export(self, container: _Container, chunk_size: int | None = 2097152): ...
     def get_archive(
@@ -201,7 +316,7 @@ class ContainerApiMixin:
         mem_reservation: float | str | None = None,
         memswap_limit: int | str | None = None,
         kernel_memory: int | str | None = None,
-        restart_policy=None,
+        restart_policy: _RestartPolicy | None = None,
     ): ...
     def wait(
         self,

stubs/docker/docker/api/image.pyi

@@ -38,6 +38,6 @@ class ImageApiMixin:
     def push(self, repository: str, tag: str | None = None, stream: bool = False, auth_config=None, decode: bool = False): ...
     def remove_image(self, image: str, force: bool = False, noprune: bool = False): ...
     def search(self, term: str, limit: int | None = None): ...
-    def tag(self, image, repository, tag: str | None = None, force: bool = False): ...
+    def tag(self, image, repository, tag: str | None = None, force: bool = False) -> bool: ...
 
 def is_file(src: str) -> bool: ...

stubs/docker/docker/api/network.pyi

@@ -1,3 +1,4 @@
+from _typeshed import Incomplete
 from collections.abc import Iterable
 from typing import Any, Literal, TypeAlias, TypedDict, type_check_only
 
@@ -15,7 +16,7 @@ _Network: TypeAlias = _HasId | _HasID | str
 _Container: TypeAlias = _HasId | _HasID | str
 
 class NetworkApiMixin:
-    def networks(self, names=None, ids=None, filters=None): ...
+    def networks(self, names: list[Incomplete] | None = None, ids: list[Incomplete] | None = None, filters=None): ...
     def create_network(
         self,
         name: str,

stubs/docker/docker/client.pyi

@@ -1,5 +1,6 @@
 from _typeshed import Incomplete
 from collections.abc import Iterable, Mapping
+from datetime import datetime
 from typing import Any, Literal, NoReturn, Protocol, overload, type_check_only
 
 from docker import APIClient
@@ -83,13 +84,28 @@ class DockerClient:
     @property
     def volumes(self) -> VolumeCollection: ...
 
+    # Please keep in sync with docker.api.daemon.DaemonApiMixin.events
     @overload
-    def events(self, *args, decode: Literal[False] | None = None, **kwargs) -> CancellableStream[str]: ...
+    def events(
+        self,
+        since: datetime | int | None = None,
+        until: datetime | int | None = None,
+        filters: dict[str, Any] | None = None,
+        decode: Literal[False] | None = None,
+    ) -> CancellableStream[str]: ...
     @overload
-    def events(self, *args, decode: Literal[True] = ..., **kwargs) -> CancellableStream[dict[str, Any]]: ...
+    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 df(self) -> dict[str, Any]: ...
+    # Please keep in sync with docker.api.daemon.DaemonApiMixin.info
     def info(self) -> dict[str, Any]: ...
+    # Please keep in sync with docker.api.daemon.DaemonApiMixin.login
     def login(
         self,
         username: str,
@@ -99,7 +115,9 @@ class DockerClient:
         reauth: bool = False,
         dockercfg_path: str | None = None,
     ) -> dict[str, Any]: ...
+    # Please keep in sync with docker.api.daemon.DaemonApiMixin.ping
     def ping(self) -> bool: ...
+    # Please keep in sync with docker.api.daemon.DaemonApiMixin.version
     def version(self, api_version: bool = True) -> dict[str, Any]: ...
     def close(self) -> None: ...
     def __getattr__(self, name: str) -> NoReturn: ...

stubs/docker/docker/models/configs.pyi

@@ -1,4 +1,5 @@
-import builtins
+from _typeshed import Incomplete
+from builtins import list as _list
 
 from .resource import Collection, Model
 
@@ -10,6 +11,15 @@ class Config(Model):
 
 class ConfigCollection(Collection[Config]):
     model: type[Config]
-    def create(self, **kwargs) -> Config: ...  # type: ignore[override]
+    # Please keep in sync with docker.api.config.ConfigApiMixin.create_config
+    def create(  # type: ignore[override]
+        self,
+        *,
+        name: str,
+        data: bytes,
+        labels: dict[Incomplete, Incomplete] | None = None,
+        templating: dict[Incomplete, Incomplete] | None = None,
+    ) -> Config: ...
     def get(self, config_id: str) -> Config: ...
-    def list(self, **kwargs) -> builtins.list[Config]: ...
+    # Please keep in sync with docker.api.config.ConfigApiMixin.configs
+    def list(self, *, filters=None) -> _list[Config]: ...