Fix invariance issues for links, ports and group_add params

stubs/docker/docker/api/container.pyi

@@ -1,6 +1,6 @@
 import datetime
 from _typeshed import Incomplete
-from typing import Literal, TypedDict, overload, type_check_only
+from typing import Any, Literal, TypedDict, overload, type_check_only
 from typing_extensions import TypeAlias
 
 from docker._types import WaitContainerResponse
@@ -61,7 +61,9 @@ class ContainerApiMixin:
         detach: bool = False,
         stdin_open: bool = False,
         tty: bool = False,
-        ports: list[int] | None = None,
+        # 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[Incomplete, Incomplete]] | list[Any] | None = None,
         environment: dict[str, str] | list[str] | None = None,
         volumes: str | list[str] | None = None,
         network_disabled: bool = False,

stubs/docker/docker/api/network.pyi

@@ -1,4 +1,5 @@
 from _typeshed import Incomplete
+from collections.abc import Iterable
 from typing import Any, Literal, TypedDict, type_check_only
 from typing_extensions import TypeAlias
 
@@ -43,7 +44,7 @@ class NetworkApiMixin:
         ipv4_address: Incomplete | None = None,
         ipv6_address: Incomplete | None = None,
         aliases: Incomplete | None = None,
-        links: Incomplete | None = None,
+        links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
         link_local_ips: Incomplete | None = None,
         driver_opt: Incomplete | None = None,
         mac_address: Incomplete | None = None,

stubs/docker/docker/models/containers.pyi

@@ -1,5 +1,6 @@
 import datetime
 from _typeshed import Incomplete
+from collections.abc import Iterable, Mapping
 from typing import Literal, NamedTuple, TypedDict, overload
 from typing_extensions import NotRequired
 
@@ -152,7 +153,7 @@ class ContainerCollection(Collection[Container]):
         entrypoint: str | list[str] | None = None,
         environment: dict[str, str] | list[str] | None = None,
         extra_hosts: dict[str, str] | None = None,
-        group_add: list[str | int] | None = None,
+        group_add: Iterable[str | int] | None = None,
         healthcheck: dict[Incomplete, Incomplete] | None = None,
         hostname: str | None = None,
         init: bool | None = None,
@@ -161,7 +162,7 @@ class ContainerCollection(Collection[Container]):
         isolation: str | None = None,
         kernel_memory: str | int | None = None,
         labels: dict[str, str] | list[str] | None = None,
-        links: dict[str, str | None] | None = None,
+        links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
         log_config: LogConfig | None = None,
         lxc_conf: dict[Incomplete, Incomplete] | None = None,
         mac_address: str | None = None,
@@ -181,7 +182,7 @@ class ContainerCollection(Collection[Container]):
         pid_mode: str | None = None,
         pids_limit: int | None = None,
         platform: str | None = None,
-        ports: dict[str, int | list[int] | tuple[str, int] | None] | None = None,
+        ports: Mapping[str, int | list[int] | tuple[str, int] | None] | None = None,
         privileged: bool = False,
         publish_all_ports: bool = False,
         read_only: bool | None = None,
@@ -247,7 +248,7 @@ class ContainerCollection(Collection[Container]):
         entrypoint: str | list[str] | None = None,
         environment: dict[str, str] | list[str] | None = None,
         extra_hosts: dict[str, str] | None = None,
-        group_add: list[str | int] | None = None,
+        group_add: Iterable[str | int] | None = None,
         healthcheck: dict[Incomplete, Incomplete] | None = None,
         hostname: str | None = None,
         init: bool | None = None,
@@ -256,7 +257,7 @@ class ContainerCollection(Collection[Container]):
         isolation: str | None = None,
         kernel_memory: str | int | None = None,
         labels: dict[str, str] | list[str] | None = None,
-        links: dict[str, str | None] | None = None,
+        links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
         log_config: LogConfig | None = None,
         lxc_conf: dict[Incomplete, Incomplete] | None = None,
         mac_address: str | None = None,
@@ -276,7 +277,7 @@ class ContainerCollection(Collection[Container]):
         pid_mode: str | None = None,
         pids_limit: int | None = None,
         platform: str | None = None,
-        ports: dict[str, int | list[int] | tuple[str, int] | None] | None = None,
+        ports: Mapping[str, int | list[int] | tuple[str, int] | None] | None = None,
         privileged: bool = False,
         publish_all_ports: bool = False,
         read_only: bool | None = None,
@@ -338,7 +339,7 @@ class ContainerCollection(Collection[Container]):
         entrypoint: str | list[str] | None = None,
         environment: dict[str, str] | list[str] | None = None,
         extra_hosts: dict[str, str] | None = None,
-        group_add: list[str | int] | None = None,
+        group_add: Iterable[str | int] | None = None,
         healthcheck: dict[Incomplete, Incomplete] | None = None,
         hostname: str | None = None,
         init: bool | None = None,
@@ -347,7 +348,7 @@ class ContainerCollection(Collection[Container]):
         isolation: str | None = None,
         kernel_memory: str | int | None = None,
         labels: dict[str, str] | list[str] | None = None,
-        links: dict[str, str | None] | None = None,
+        links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]] | None = None,
         log_config: LogConfig | None = None,
         lxc_conf: dict[Incomplete, Incomplete] | None = None,
         mac_address: str | None = None,
@@ -367,7 +368,7 @@ class ContainerCollection(Collection[Container]):
         pid_mode: str | None = None,
         pids_limit: int | None = None,
         platform: str | None = None,
-        ports: dict[str, int | list[int] | tuple[str, int] | None] | None = None,
+        ports: Mapping[str, int | list[int] | tuple[str, int] | None] | None = None,
         privileged: bool = False,
         publish_all_ports: bool = False,
         read_only: bool | None = None,

stubs/docker/docker/types/containers.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Incomplete
 from collections.abc import Iterable, Mapping
-from typing import Final, Literal
+from typing import Any, Final, Literal
 
 from docker._types import ContainerWeightDevice
 
@@ -76,7 +76,7 @@ class HostConfig(dict[str, Incomplete]):
         port_bindings: Mapping[int | str, Incomplete] | None = None,
         lxc_conf: dict[str, Incomplete] | list[dict[str, Incomplete]] | None = None,
         publish_all_ports: bool = False,
-        links: Mapping[str, str | None] | None = None,
+        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,
@@ -154,7 +154,9 @@ class ContainerConfig(dict[str, Incomplete]):
         detach: bool = False,
         stdin_open: bool = False,
         tty: bool = False,
-        ports: Mapping[str, int | list[int] | tuple[str, int] | None] | None = None,
+        # 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[Incomplete, Incomplete]] | list[Any] | None = None,
         environment: dict[str, str] | list[str] | None = None,
         volumes: str | list[str] | None = None,
         network_disabled: bool = False,

stubs/docker/docker/types/networks.pyi

@@ -1,11 +1,12 @@
 from _typeshed import Incomplete
+from collections.abc import Iterable
 
 class EndpointConfig(dict[str, Incomplete]):
     def __init__(
         self,
         version: str,
         aliases: list[Incomplete] | None = None,
-        links: dict[str, str] | 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,

stubs/docker/docker/utils/utils.pyi

@@ -1,4 +1,5 @@
 from _typeshed import Incomplete
+from collections.abc import Iterable, Mapping
 from typing import NamedTuple
 
 class URLComponents(NamedTuple):
@@ -15,7 +16,7 @@ def decode_json_header(header): ...
 def compare_version(v1, v2): ...
 def version_lt(v1, v2): ...
 def version_gte(v1, v2): ...
-def convert_port_bindings(port_bindings): ...
+def convert_port_bindings(port_bindings: Mapping[str, int | list[int] | tuple[str, int] | None]): ...
 def convert_volume_binds(binds): ...
 def convert_tmpfs_mounts(tmpfs): ...
 def convert_service_networks(networks): ...
@@ -26,7 +27,7 @@ def kwargs_from_env(environment: Incomplete | None = None): ...
 def convert_filters(filters): ...
 def datetime_to_timestamp(dt): ...
 def parse_bytes(s): ...
-def normalize_links(links): ...
+def normalize_links(links: dict[str, str] | dict[str, None] | dict[str, str | None] | Iterable[tuple[str, str | None]]): ...
 def parse_env_file(env_file): ...
 def split_command(command): ...
 def format_environment(environment): ...