Add parameter types to docker.models.images.ImageCollection.build (#12196)

Introduce stubs-only module `docker._types`.

stubs/docker/@tests/stubtest_allowlist.txt

@@ -11,3 +11,6 @@ docker.models.resource.Collection.model
 
 # keyword arguments are now unsupported
 docker.api.container.ContainerApiMixin.start
+
+# Internal-use module for types shared by multiple modules.
+docker._types

stubs/docker/docker/_types.pyi

@@ -0,0 +1,8 @@
+# Internal-use module for types shared by multiple modules.
+# This does not match a module in docker-py.
+
+from typing_extensions import 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

stubs/docker/docker/models/images.pyi

@@ -1,11 +1,21 @@
 from collections.abc import Iterator
-from typing import Any, Literal, overload
+from io import StringIO
+from typing import IO, Any, Literal, TypedDict, overload, type_check_only
 from typing_extensions import TypeAlias
 
+from docker._types import JSON
+
 from .resource import Collection, Model
 
 _ImageList: TypeAlias = list[Image]  # To resolve conflicts with a method called "list"
 
+@type_check_only
+class _ContainerLimits(TypedDict, total=False):
+    memory: int
+    memswap: int
+    cpushares: int
+    cpusetcpus: str
+
 class Image(Model):
     @property
     def labels(self) -> dict[str, Any]: ...
@@ -31,7 +41,35 @@ class RegistryData(Model):
 
 class ImageCollection(Collection[Image]):
     model: type[Image]
-    def build(self, **kwargs) -> tuple[Image, Iterator[Any]]: ...
+    def build(
+        self,
+        *,
+        path: str | None = None,
+        fileobj: StringIO | IO[bytes] | None = None,
+        tag: str | None = None,
+        quiet: bool = False,
+        nocache: bool = False,
+        rm: bool = False,
+        timeout: int | None = None,
+        custom_context: bool = False,
+        encoding: str | None = None,
+        pull: bool = False,
+        forcerm: bool = False,
+        dockerfile: str | None = None,
+        buildargs: dict[str, Any] | None = None,
+        container_limits: _ContainerLimits | None = None,
+        shmsize: int | None = None,
+        labels: dict[str, Any] | None = None,
+        # need to use list, because the type must be json serializable
+        cache_from: list[str] | None = None,
+        target: str | None = None,
+        network_mode: str | None = None,
+        squash: bool | None = None,
+        extra_hosts: list[str] | dict[str, str] | None = None,
+        platform: str | None = None,
+        isolation: str | None = None,
+        use_config_proxy: bool = True,
+    ) -> tuple[Image, Iterator[JSON]]: ...
     def get(self, name: str) -> Image: ...
     def get_registry_data(self, name, auth_config: dict[str, Any] | None = None) -> RegistryData: ...
     def list(self, name: str | None = None, all: bool = False, filters: dict[str, Any] | None = None) -> _ImageList: ...

stubs/docker/docker/utils/json_stream.pyi

@@ -1,17 +1,14 @@
 import json
 from collections.abc import Callable, Generator, Iterator
 from typing import Any
-from typing_extensions import TypeAlias
+
+from docker._types import JSON
 
 json_decoder: json.JSONDecoder
 
-# 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
-
 def stream_as_text(stream: Iterator[str | bytes]) -> Generator[str, None, None]: ...
-def json_splitter(buffer: str) -> tuple[_JSON, str] | None: ...
-def json_stream(stream: Iterator[str]) -> Generator[_JSON, None, None]: ...
+def json_splitter(buffer: str) -> tuple[JSON, str] | None: ...
+def json_stream(stream: Iterator[str]) -> Generator[JSON, None, None]: ...
 def line_splitter(buffer: str, separator: str = "\n") -> tuple[str, str] | None: ...
 def split_buffer(
     stream: Iterator[str | bytes], splitter: Callable[[str], tuple[str, str]] | None = None, decoder: Callable[[str], Any] = ...