Add typing information, 1/2 (#1176)

* Re-enable typing and improve config.

* Make mypy pass.

* Improve settings.

* First batch of types.

* Add more type hints.

* Fixes.

* Format.

* Fix split_port() without returning to previous type chaos.

* Continue with type hints (and ignores).

plugins/module_utils/_api/utils/build.py

@@ -17,26 +17,38 @@ import random
 import re
 import tarfile
 import tempfile
+import typing as t
 
 from ..constants import IS_WINDOWS_PLATFORM, WINDOWS_LONGPATH_PREFIX
 from . import fnmatch
 
 
+if t.TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
 _SEP = re.compile("/|\\\\") if IS_WINDOWS_PLATFORM else re.compile("/")
 
 
-def tar(path, exclude=None, dockerfile=None, fileobj=None, gzip=False):
+def tar(
+    path: str,
+    exclude: list[str] | None = None,
+    dockerfile: tuple[str, str | None] | tuple[None, None] | None = None,
+    fileobj: t.IO[bytes] | None = None,
+    gzip: bool = False,
+) -> t.IO[bytes]:
     root = os.path.abspath(path)
     exclude = exclude or []
     dockerfile = dockerfile or (None, None)
-    extra_files = []
+    extra_files: list[tuple[str, str]] = []
     if dockerfile[1] is not None:
+        assert dockerfile[0] is not None
         dockerignore_contents = "\n".join(
             (exclude or [".dockerignore"]) + [dockerfile[0]]
         )
         extra_files = [
             (".dockerignore", dockerignore_contents),
-            dockerfile,
+            dockerfile,  # type: ignore
         ]
     return create_archive(
         files=sorted(exclude_paths(root, exclude, dockerfile=dockerfile[0])),
@@ -47,7 +59,9 @@ def tar(path, exclude=None, dockerfile=None, fileobj=None, gzip=False):
     )
 
 
-def exclude_paths(root, patterns, dockerfile=None):
+def exclude_paths(
+    root: str, patterns: list[str], dockerfile: str | None = None
+) -> set[str]:
     """
     Given a root directory path and a list of .dockerignore patterns, return
     an iterator of all paths (both regular files and directories) in the root
@@ -64,7 +78,7 @@ def exclude_paths(root, patterns, dockerfile=None):
     return set(pm.walk(root))
 
 
-def build_file_list(root):
+def build_file_list(root: str) -> list[str]:
     files = []
     for dirname, dirnames, fnames in os.walk(root):
         for filename in fnames + dirnames:
@@ -74,7 +88,13 @@ def build_file_list(root):
     return files
 
 
-def create_archive(root, files=None, fileobj=None, gzip=False, extra_files=None):
+def create_archive(
+    root: str,
+    files: Sequence[str] | None = None,
+    fileobj: t.IO[bytes] | None = None,
+    gzip: bool = False,
+    extra_files: Sequence[tuple[str, str]] | None = None,
+) -> t.IO[bytes]:
     extra_files = extra_files or []
     if not fileobj:
         fileobj = tempfile.NamedTemporaryFile()
@@ -92,7 +112,7 @@ def create_archive(root, files=None, fileobj=None, gzip=False, extra_files=None)
         if i is None:
             # This happens when we encounter a socket file. We can safely
             # ignore it and proceed.
-            continue
+            continue  # type: ignore
 
         # Workaround https://bugs.python.org/issue32713
         if i.mtime < 0 or i.mtime > 8**11 - 1:
@@ -124,11 +144,11 @@ def create_archive(root, files=None, fileobj=None, gzip=False, extra_files=None)
     return fileobj
 
 
-def mkbuildcontext(dockerfile):
+def mkbuildcontext(dockerfile: io.BytesIO | t.IO[bytes]) -> t.IO[bytes]:
     f = tempfile.NamedTemporaryFile()  # pylint: disable=consider-using-with
     try:
         with tarfile.open(mode="w", fileobj=f) as t:
-            if isinstance(dockerfile, io.StringIO):
+            if isinstance(dockerfile, io.StringIO):  # type: ignore
                 raise TypeError("Please use io.BytesIO to create in-memory Dockerfiles")
             if isinstance(dockerfile, io.BytesIO):
                 dfinfo = tarfile.TarInfo("Dockerfile")
@@ -144,17 +164,17 @@ def mkbuildcontext(dockerfile):
     return f
 
 
-def split_path(p):
+def split_path(p: str) -> list[str]:
     return [pt for pt in re.split(_SEP, p) if pt and pt != "."]
 
 
-def normalize_slashes(p):
+def normalize_slashes(p: str) -> str:
     if IS_WINDOWS_PLATFORM:
         return "/".join(split_path(p))
     return p
 
 
-def walk(root, patterns, default=True):
+def walk(root: str, patterns: Sequence[str], default: bool = True) -> t.Generator[str]:
     pm = PatternMatcher(patterns)
     return pm.walk(root)
 
@@ -162,11 +182,11 @@ def walk(root, patterns, default=True):
 # Heavily based on
 # https://github.com/moby/moby/blob/master/pkg/fileutils/fileutils.go
 class PatternMatcher:
-    def __init__(self, patterns):
+    def __init__(self, patterns: Sequence[str]) -> None:
         self.patterns = list(filter(lambda p: p.dirs, [Pattern(p) for p in patterns]))
         self.patterns.append(Pattern("!.dockerignore"))
 
-    def matches(self, filepath):
+    def matches(self, filepath: str) -> bool:
         matched = False
         parent_path = os.path.dirname(filepath)
         parent_path_dirs = split_path(parent_path)
@@ -185,8 +205,8 @@ class PatternMatcher:
 
         return matched
 
-    def walk(self, root):
-        def rec_walk(current_dir):
+    def walk(self, root: str) -> t.Generator[str]:
+        def rec_walk(current_dir: str) -> t.Generator[str]:
             for f in os.listdir(current_dir):
                 fpath = os.path.join(os.path.relpath(current_dir, root), f)
                 if fpath.startswith("." + os.path.sep):
@@ -220,7 +240,7 @@ class PatternMatcher:
 
 
 class Pattern:
-    def __init__(self, pattern_str):
+    def __init__(self, pattern_str: str) -> None:
         self.exclusion = False
         if pattern_str.startswith("!"):
             self.exclusion = True
@@ -230,8 +250,7 @@ class Pattern:
         self.cleaned_pattern = "/".join(self.dirs)
 
     @classmethod
-    def normalize(cls, p):
-
+    def normalize(cls, p: str) -> list[str]:
         # Remove trailing spaces
         p = p.strip()
 
@@ -256,11 +275,13 @@ class Pattern:
                 i += 1
         return split
 
-    def match(self, filepath):
+    def match(self, filepath: str) -> bool:
         return fnmatch.fnmatch(normalize_slashes(filepath), self.cleaned_pattern)
 
 
-def process_dockerfile(dockerfile, path):
+def process_dockerfile(
+    dockerfile: str | None, path: str
+) -> tuple[str, str | None] | tuple[None, None]:
     if not dockerfile:
         return (None, None)
 
@@ -268,7 +289,7 @@ def process_dockerfile(dockerfile, path):
     if not os.path.isabs(dockerfile):
         abs_dockerfile = os.path.join(path, dockerfile)
         if IS_WINDOWS_PLATFORM and path.startswith(WINDOWS_LONGPATH_PREFIX):
-            abs_dockerfile = f"{WINDOWS_LONGPATH_PREFIX}{os.path.normpath(abs_dockerfile[len(WINDOWS_LONGPATH_PREFIX):])}"
+            abs_dockerfile = f"{WINDOWS_LONGPATH_PREFIX}{os.path.normpath(abs_dockerfile[len(WINDOWS_LONGPATH_PREFIX) :])}"
     if os.path.splitdrive(path)[0] != os.path.splitdrive(abs_dockerfile)[
         0
     ] or os.path.relpath(abs_dockerfile, path).startswith(".."):

plugins/module_utils/_api/utils/config.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import typing as t
 
 from ..constants import IS_WINDOWS_PLATFORM
 
@@ -24,11 +25,11 @@ LEGACY_DOCKER_CONFIG_FILENAME = ".dockercfg"
 log = logging.getLogger(__name__)
 
 
-def get_default_config_file():
+def get_default_config_file() -> str:
     return os.path.join(home_dir(), DOCKER_CONFIG_FILENAME)
 
 
-def find_config_file(config_path=None):
+def find_config_file(config_path: str | None = None) -> str | None:
     homedir = home_dir()
     paths = list(
         filter(
@@ -54,14 +55,14 @@ def find_config_file(config_path=None):
     return None
 
 
-def config_path_from_environment():
+def config_path_from_environment() -> str | None:
     config_dir = os.environ.get("DOCKER_CONFIG")
     if not config_dir:
         return None
     return os.path.join(config_dir, os.path.basename(DOCKER_CONFIG_FILENAME))
 
 
-def home_dir():
+def home_dir() -> str:
     """
     Get the user's home directory, using the same logic as the Docker Engine
     client - use %USERPROFILE% on Windows, $HOME/getuid on POSIX.
@@ -71,7 +72,7 @@ def home_dir():
     return os.path.expanduser("~")
 
 
-def load_general_config(config_path=None):
+def load_general_config(config_path: str | None = None) -> dict[str, t.Any]:
     config_file = find_config_file(config_path)
 
     if not config_file:

plugins/module_utils/_api/utils/decorators.py

@@ -12,16 +12,37 @@
 from __future__ import annotations
 
 import functools
+import typing as t
 
 from .. import errors
 from . import utils
 
 
-def minimum_version(version):
-    def decorator(f):
+if t.TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..api.client import APIClient
+
+    _Self = t.TypeVar("_Self")
+    _P = t.ParamSpec("_P")
+    _R = t.TypeVar("_R")
+
+
+def minimum_version(
+    version: str,
+) -> Callable[
+    [Callable[t.Concatenate[_Self, _P], _R]],
+    Callable[t.Concatenate[_Self, _P], _R],
+]:
+    def decorator(
+        f: Callable[t.Concatenate[_Self, _P], _R],
+    ) -> Callable[t.Concatenate[_Self, _P], _R]:
         @functools.wraps(f)
-        def wrapper(self, *args, **kwargs):
-            if utils.version_lt(self._version, version):
+        def wrapper(self: _Self, *args: _P.args, **kwargs: _P.kwargs) -> _R:
+            # We use _Self instead of APIClient since this is used for mixins for APIClient.
+            # This unfortunately means that self._version does not exist in the mixin,
+            # it only exists after mixing in. This is why we ignore types here.
+            if utils.version_lt(self._version, version):  # type: ignore
                 raise errors.InvalidVersion(
                     f"{f.__name__} is not available for version < {version}"
                 )
@@ -32,13 +53,16 @@ def minimum_version(version):
     return decorator
 
 
-def update_headers(f):
-    def inner(self, *args, **kwargs):
+def update_headers(
+    f: Callable[t.Concatenate[APIClient, _P], _R],
+) -> Callable[t.Concatenate[APIClient, _P], _R]:
+    def inner(self: APIClient, *args: _P.args, **kwargs: _P.kwargs) -> _R:
         if "HttpHeaders" in self._general_configs:
             if not kwargs.get("headers"):
                 kwargs["headers"] = self._general_configs["HttpHeaders"]
             else:
-                kwargs["headers"].update(self._general_configs["HttpHeaders"])
+                # We cannot (yet) model that kwargs["headers"] should be a dictionary
+                kwargs["headers"].update(self._general_configs["HttpHeaders"])  # type: ignore
         return f(self, *args, **kwargs)
 
     return inner

plugins/module_utils/_api/utils/fnmatch.py

@@ -28,16 +28,16 @@ import re
 
 __all__ = ["fnmatch", "fnmatchcase", "translate"]
 
-_cache = {}
+_cache: dict[str, re.Pattern] = {}
 _MAXCACHE = 100
 
 
-def _purge():
+def _purge() -> None:
     """Clear the pattern cache"""
     _cache.clear()
 
 
-def fnmatch(name, pat):
+def fnmatch(name: str, pat: str):
     """Test whether FILENAME matches PATTERN.
 
     Patterns are Unix shell style:
@@ -58,7 +58,7 @@ def fnmatch(name, pat):
     return fnmatchcase(name, pat)
 
 
-def fnmatchcase(name, pat):
+def fnmatchcase(name: str, pat: str) -> bool:
     """Test whether FILENAME matches PATTERN, including case.
     This is a version of fnmatch() which does not case-normalize
     its arguments.
@@ -74,7 +74,7 @@ def fnmatchcase(name, pat):
     return re_pat.match(name) is not None
 
 
-def translate(pat):
+def translate(pat: str) -> str:
     """Translate a shell PATTERN to a regular expression.
 
     There is no way to quote meta-characters.

plugins/module_utils/_api/utils/json_stream.py

@@ -13,14 +13,22 @@ from __future__ import annotations
 
 import json
 import json.decoder
+import typing as t
 
 from ..errors import StreamParseError
 
 
+if t.TYPE_CHECKING:
+    import re
+    from collections.abc import Callable
+
+    _T = t.TypeVar("_T")
+
+
 json_decoder = json.JSONDecoder()
 
 
-def stream_as_text(stream):
+def stream_as_text(stream: t.Generator[bytes | str]) -> t.Generator[str]:
     """
     Given a stream of bytes or text, if any of the items in the stream
     are bytes convert them to text.
@@ -33,20 +41,22 @@ def stream_as_text(stream):
         yield data
 
 
-def json_splitter(buffer):
+def json_splitter(buffer: str) -> tuple[t.Any, str] | None:
     """Attempt to parse a json object from a buffer. If there is at least one
     object, return it and the rest of the buffer, otherwise return None.
     """
     buffer = buffer.strip()
     try:
         obj, index = json_decoder.raw_decode(buffer)
-        rest = buffer[json.decoder.WHITESPACE.match(buffer, index).end() :]
+        ws: re.Pattern = json.decoder.WHITESPACE  # type: ignore[attr-defined]
+        m = ws.match(buffer, index)
+        rest = buffer[m.end() :] if m else buffer[index:]
         return obj, rest
     except ValueError:
         return None
 
 
-def json_stream(stream):
+def json_stream(stream: t.Generator[str | bytes]) -> t.Generator[t.Any]:
     """Given a stream of text, return a stream of json objects.
     This handles streams which are inconsistently buffered (some entries may
     be newline delimited, and others are not).
@@ -54,21 +64,24 @@ def json_stream(stream):
     return split_buffer(stream, json_splitter, json_decoder.decode)
 
 
-def line_splitter(buffer, separator="\n"):
+def line_splitter(buffer: str, separator: str = "\n") -> tuple[str, str] | None:
     index = buffer.find(str(separator))
     if index == -1:
         return None
     return buffer[: index + 1], buffer[index + 1 :]
 
 
-def split_buffer(stream, splitter=None, decoder=lambda a: a):
+def split_buffer(
+    stream: t.Generator[str | bytes],
+    splitter: Callable[[str], tuple[_T, str] | None],
+    decoder: Callable[[str], _T],
+) -> t.Generator[_T | str]:
     """Given a generator which yields strings and a splitter function,
     joins all input, splits on the separator and yields each chunk.
     Unlike string.split(), each chunk includes the trailing
     separator, except for the last one if none was found on the end
     of the input.
     """
-    splitter = splitter or line_splitter
     buffered = ""
 
     for data in stream_as_text(stream):

plugins/module_utils/_api/utils/ports.py

@@ -12,6 +12,11 @@
 from __future__ import annotations
 
 import re
+import typing as t
+
+
+if t.TYPE_CHECKING:
+    from collections.abc import Collection, Sequence
 
 
 PORT_SPEC = re.compile(
@@ -26,32 +31,42 @@ PORT_SPEC = re.compile(
 )
 
 
-def add_port_mapping(port_bindings, internal_port, external):
+def add_port_mapping(
+    port_bindings: dict[str, list[str | tuple[str, str | None] | None]],
+    internal_port: str,
+    external: str | tuple[str, str | None] | None,
+) -> None:
     if internal_port in port_bindings:
         port_bindings[internal_port].append(external)
     else:
         port_bindings[internal_port] = [external]
 
 
-def add_port(port_bindings, internal_port_range, external_range):
+def add_port(
+    port_bindings: dict[str, list[str | tuple[str, str | None] | None]],
+    internal_port_range: list[str],
+    external_range: list[str] | list[tuple[str, str | None]] | None,
+) -> None:
     if external_range is None:
         for internal_port in internal_port_range:
             add_port_mapping(port_bindings, internal_port, None)
     else:
-        ports = zip(internal_port_range, external_range)
-        for internal_port, external_port in ports:
-            add_port_mapping(port_bindings, internal_port, external_port)
+        for internal_port, external_port in zip(internal_port_range, external_range):
+            # mypy loses the exact type of eternal_port elements for some reason...
+            add_port_mapping(port_bindings, internal_port, external_port)  # type: ignore
 
 
-def build_port_bindings(ports):
-    port_bindings = {}
+def build_port_bindings(
+    ports: Collection[str],
+) -> dict[str, list[str | tuple[str, str | None] | None]]:
+    port_bindings: dict[str, list[str | tuple[str, str | None] | None]] = {}
     for port in ports:
         internal_port_range, external_range = split_port(port)
         add_port(port_bindings, internal_port_range, external_range)
     return port_bindings
 
 
-def _raise_invalid_port(port):
+def _raise_invalid_port(port: str) -> t.NoReturn:
     raise ValueError(
         f'Invalid port "{port}", should be '
         "[[remote_ip:]remote_port[-remote_port]:]"
@@ -59,39 +74,64 @@ def _raise_invalid_port(port):
     )
 
 
-def port_range(start, end, proto, randomly_available_port=False):
-    if not start:
+@t.overload
+def port_range(
+    start: str,
+    end: str | None,
+    proto: str,
+    randomly_available_port: bool = False,
+) -> list[str]: ...
+
+
+@t.overload
+def port_range(
+    start: str | None,
+    end: str | None,
+    proto: str,
+    randomly_available_port: bool = False,
+) -> list[str] | None: ...
+
+
+def port_range(
+    start: str | None,
+    end: str | None,
+    proto: str,
+    randomly_available_port: bool = False,
+) -> list[str] | None:
+    if start is None:
         return start
-    if not end:
+    if end is None:
         return [f"{start}{proto}"]
     if randomly_available_port:
         return [f"{start}-{end}{proto}"]
     return [f"{port}{proto}" for port in range(int(start), int(end) + 1)]
 
 
-def split_port(port):
-    if hasattr(port, "legacy_repr"):
-        # This is the worst hack, but it prevents a bug in Compose 1.14.0
-        # https://github.com/docker/docker-py/issues/1668
-        # TODO: remove once fixed in Compose stable
-        port = port.legacy_repr()
+def split_port(
+    port: str,
+) -> tuple[list[str], list[str] | list[tuple[str, str | None]] | None]:
     port = str(port)
     match = PORT_SPEC.match(port)
     if match is None:
         _raise_invalid_port(port)
     parts = match.groupdict()
 
-    host = parts["host"]
-    proto = parts["proto"] or ""
-    internal = port_range(parts["int"], parts["int_end"], proto)
-    external = port_range(parts["ext"], parts["ext_end"], "", len(internal) == 1)
+    host: str | None = parts["host"]
+    proto: str = parts["proto"] or ""
+    int_p: str = parts["int"]
+    ext_p: str = parts["ext"]
+    internal: list[str] = port_range(int_p, parts["int_end"], proto)  # type: ignore
+    external = port_range(ext_p or None, parts["ext_end"], "", len(internal) == 1)
 
     if host is None:
-        if external is not None and len(internal) != len(external):
+        if (external is not None and len(internal) != len(external)) or ext_p == "":
             raise ValueError("Port ranges don't match in length")
         return internal, external
+    external_or_none: Sequence[str | None]
     if not external:
-        external = [None] * len(internal)
-    elif len(internal) != len(external):
-        raise ValueError("Port ranges don't match in length")
-    return internal, [(host, ext_port) for ext_port in external]
+        external_or_none = [None] * len(internal)
+    else:
+        external_or_none = external
+        if len(internal) != len(external_or_none):
+            raise ValueError("Port ranges don't match in length")
+    return internal, [(host, ext_port) for ext_port in external_or_none]

plugins/module_utils/_api/utils/proxy.py

@@ -20,23 +20,23 @@ class ProxyConfig(dict):
     """
 
     @property
-    def http(self):
+    def http(self) -> str | None:
         return self.get("http")
 
     @property
-    def https(self):
+    def https(self) -> str | None:
         return self.get("https")
 
     @property
-    def ftp(self):
+    def ftp(self) -> str | None:
         return self.get("ftp")
 
     @property
-    def no_proxy(self):
+    def no_proxy(self) -> str | None:
         return self.get("no_proxy")
 
     @staticmethod
-    def from_dict(config):
+    def from_dict(config: dict[str, str]) -> ProxyConfig:
         """
         Instantiate a new ProxyConfig from a dictionary that represents a
         client configuration, as described in `the documentation`_.
@@ -51,7 +51,7 @@ class ProxyConfig(dict):
             no_proxy=config.get("noProxy"),
         )
 
-    def get_environment(self):
+    def get_environment(self) -> dict[str, str]:
         """
         Return a dictionary representing the environment variables used to
         set the proxy settings.
@@ -67,7 +67,7 @@ class ProxyConfig(dict):
             env["no_proxy"] = env["NO_PROXY"] = self.no_proxy
         return env
 
-    def inject_proxy_environment(self, environment):
+    def inject_proxy_environment(self, environment: list[str]) -> list[str]:
         """
         Given a list of strings representing environment variables, prepend the
         environment variables corresponding to the proxy settings.
@@ -82,5 +82,5 @@ class ProxyConfig(dict):
         # variables defined in "environment" to take precedence.
         return proxy_env + environment
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"ProxyConfig(http={self.http}, https={self.https}, ftp={self.ftp}, no_proxy={self.no_proxy})"

plugins/module_utils/_api/utils/socket.py

@@ -16,10 +16,15 @@ import os
 import select
 import socket as pysocket
 import struct
+import typing as t
 
 from ..transport.npipesocket import NpipeSocket
 
 
+if t.TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
 STDOUT = 1
 STDERR = 2
 
@@ -33,7 +38,7 @@ class SocketError(Exception):
 NPIPE_ENDED = 109
 
 
-def read(socket, n=4096):
+def read(socket, n: int = 4096) -> bytes | None:
     """
     Reads at most n bytes from socket
     """
@@ -58,6 +63,7 @@ def read(socket, n=4096):
     except EnvironmentError as e:
         if e.errno not in recoverable_errors:
             raise
+        return None  # TODO ???
     except Exception as e:
         is_pipe_ended = (
             isinstance(socket, NpipeSocket)
@@ -67,11 +73,11 @@ def read(socket, n=4096):
         if is_pipe_ended:
             # npipes do not support duplex sockets, so we interpret
             # a PIPE_ENDED error as a close operation (0-length read).
-            return ""
+            return b""
         raise
 
 
-def read_exactly(socket, n):
+def read_exactly(socket, n: int) -> bytes:
     """
     Reads exactly n bytes from socket
     Raises SocketError if there is not enough data
@@ -85,7 +91,7 @@ def read_exactly(socket, n):
     return data
 
 
-def next_frame_header(socket):
+def next_frame_header(socket) -> tuple[int, int]:
     """
     Returns the stream and size of the next frame of data waiting to be read
     from socket, according to the protocol defined here:
@@ -101,7 +107,7 @@ def next_frame_header(socket):
     return (stream, actual)
 
 
-def frames_iter(socket, tty):
+def frames_iter(socket, tty: bool) -> t.Generator[tuple[int, bytes]]:
     """
     Return a generator of frames read from socket. A frame is a tuple where
     the first item is the stream number and the second item is a chunk of data.
@@ -114,7 +120,7 @@ def frames_iter(socket, tty):
     return frames_iter_no_tty(socket)
 
 
-def frames_iter_no_tty(socket):
+def frames_iter_no_tty(socket) -> t.Generator[tuple[int, bytes]]:
     """
     Returns a generator of data read from the socket when the tty setting is
     not enabled.
@@ -135,20 +141,34 @@ def frames_iter_no_tty(socket):
             yield (stream, result)
 
 
-def frames_iter_tty(socket):
+def frames_iter_tty(socket) -> t.Generator[bytes]:
     """
     Return a generator of data read from the socket when the tty setting is
     enabled.
     """
     while True:
         result = read(socket)
-        if len(result) == 0:
+        if not result:
             # We have reached EOF
             return
         yield result
 
 
-def consume_socket_output(frames, demux=False):
+@t.overload
+def consume_socket_output(frames, demux: t.Literal[False] = False) -> bytes: ...
+
+
+@t.overload
+def consume_socket_output(frames, demux: t.Literal[True]) -> tuple[bytes, bytes]: ...
+
+
+@t.overload
+def consume_socket_output(
+    frames, demux: bool = False
+) -> bytes | tuple[bytes, bytes]: ...
+
+
+def consume_socket_output(frames, demux: bool = False) -> bytes | tuple[bytes, bytes]:
     """
     Iterate through frames read from the socket and return the result.
 
@@ -167,7 +187,7 @@ def consume_socket_output(frames, demux=False):
 
     # If the streams are demultiplexed, the generator yields tuples
     # (stdout, stderr)
-    out = [None, None]
+    out: list[bytes | None] = [None, None]
     for frame in frames:
         # It is guaranteed that for each frame, one and only one stream
         # is not None.
@@ -183,10 +203,10 @@ def consume_socket_output(frames, demux=False):
                 out[1] = frame[1]
             else:
                 out[1] += frame[1]
-    return tuple(out)
+    return tuple(out)  # type: ignore
 
 
-def demux_adaptor(stream_id, data):
+def demux_adaptor(stream_id: int, data: bytes) -> tuple[bytes | None, bytes | None]:
     """
     Utility to demultiplex stdout and stderr when reading frames from the
     socket.

plugins/module_utils/_api/utils/utils.py

@@ -18,6 +18,7 @@ import os
 import os.path
 import shlex
 import string
+import typing as t
 from urllib.parse import urlparse, urlunparse
 
 from ansible_collections.community.docker.plugins.module_utils._version import (
@@ -34,32 +35,23 @@ from ..constants import (
 from ..tls import TLSConfig
 
 
+if t.TYPE_CHECKING:
+    import ssl
+    from collections.abc import Mapping, Sequence
+
+
 URLComponents = collections.namedtuple(
     "URLComponents",
     "scheme netloc url params query fragment",
 )
 
 
-def create_ipam_pool(*args, **kwargs):
-    raise errors.DeprecatedMethod(
-        "utils.create_ipam_pool has been removed. Please use a "
-        "docker.types.IPAMPool object instead."
-    )
-
-
-def create_ipam_config(*args, **kwargs):
-    raise errors.DeprecatedMethod(
-        "utils.create_ipam_config has been removed. Please use a "
-        "docker.types.IPAMConfig object instead."
-    )
-
-
-def decode_json_header(header):
+def decode_json_header(header: str) -> dict[str, t.Any]:
     data = base64.b64decode(header).decode("utf-8")
     return json.loads(data)
 
 
-def compare_version(v1, v2):
+def compare_version(v1: str, v2: str) -> t.Literal[-1, 0, 1]:
     """Compare docker versions
 
     >>> v1 = '1.9'
@@ -80,43 +72,64 @@ def compare_version(v1, v2):
     return 1
 
 
-def version_lt(v1, v2):
+def version_lt(v1: str, v2: str) -> bool:
     return compare_version(v1, v2) > 0
 
 
-def version_gte(v1, v2):
+def version_gte(v1: str, v2: str) -> bool:
     return not version_lt(v1, v2)
 
 
-def _convert_port_binding(binding):
+def _convert_port_binding(
+    binding: (
+        tuple[str, str | int | None]
+        | tuple[str | int | None]
+        | dict[str, str]
+        | str
+        | int
+    ),
+) -> dict[str, str]:
     result = {"HostIp": "", "HostPort": ""}
+    host_port: str | int | None = ""
     if isinstance(binding, tuple):
         if len(binding) == 2:
-            result["HostPort"] = binding[1]
+            host_port = binding[1]  # type: ignore
             result["HostIp"] = binding[0]
         elif isinstance(binding[0], str):
             result["HostIp"] = binding[0]
         else:
-            result["HostPort"] = binding[0]
+            host_port = binding[0]
     elif isinstance(binding, dict):
         if "HostPort" in binding:
-            result["HostPort"] = binding["HostPort"]
+            host_port = binding["HostPort"]
             if "HostIp" in binding:
                 result["HostIp"] = binding["HostIp"]
         else:
             raise ValueError(binding)
     else:
-        result["HostPort"] = binding
-
-    if result["HostPort"] is None:
-        result["HostPort"] = ""
-    else:
-        result["HostPort"] = str(result["HostPort"])
+        host_port = binding
 
+    result["HostPort"] = str(host_port) if host_port is not None else ""
     return result
 
 
-def convert_port_bindings(port_bindings):
+def convert_port_bindings(
+    port_bindings: dict[
+        str | int,
+        tuple[str, str | int | None]
+        | tuple[str | int | None]
+        | dict[str, str]
+        | str
+        | int
+        | list[
+            tuple[str, str | int | None]
+            | tuple[str | int | None]
+            | dict[str, str]
+            | str
+            | int
+        ],
+    ],
+) -> dict[str, list[dict[str, str]]]:
     result = {}
     for k, v in port_bindings.items():
         key = str(k)
@@ -129,9 +142,11 @@ def convert_port_bindings(port_bindings):
     return result
 
 
-def convert_volume_binds(binds):
+def convert_volume_binds(
+    binds: list[str] | Mapping[str | bytes, dict[str, str | bytes] | bytes | str | int],
+) -> list[str]:
     if isinstance(binds, list):
-        return binds
+        return binds  # type: ignore
 
     result = []
     for k, v in binds.items():
@@ -149,7 +164,7 @@ def convert_volume_binds(binds):
             if "ro" in v:
                 mode = "ro" if v["ro"] else "rw"
             elif "mode" in v:
-                mode = v["mode"]
+                mode = v["mode"]  # type: ignore # TODO
             else:
                 mode = "rw"
 
@@ -165,9 +180,9 @@ def convert_volume_binds(binds):
             ]
             if "propagation" in v and v["propagation"] in propagation_modes:
                 if mode:
-                    mode = ",".join([mode, v["propagation"]])
+                    mode = ",".join([mode, v["propagation"]])  # type: ignore # TODO
                 else:
-                    mode = v["propagation"]
+                    mode = v["propagation"]  # type: ignore # TODO
 
             result.append(f"{k}:{bind}:{mode}")
         else:
@@ -177,7 +192,7 @@ def convert_volume_binds(binds):
     return result
 
 
-def convert_tmpfs_mounts(tmpfs):
+def convert_tmpfs_mounts(tmpfs: dict[str, str] | list[str]) -> dict[str, str]:
     if isinstance(tmpfs, dict):
         return tmpfs
 
@@ -204,9 +219,11 @@ def convert_tmpfs_mounts(tmpfs):
     return result
 
 
-def convert_service_networks(networks):
+def convert_service_networks(
+    networks: list[str | dict[str, str]],
+) -> list[dict[str, str]]:
     if not networks:
-        return networks
+        return networks  # type: ignore
     if not isinstance(networks, list):
         raise TypeError("networks parameter must be a list.")
 
@@ -218,17 +235,17 @@ def convert_service_networks(networks):
     return result
 
 
-def parse_repository_tag(repo_name):
+def parse_repository_tag(repo_name: str) -> tuple[str, str | None]:
     parts = repo_name.rsplit("@", 1)
     if len(parts) == 2:
-        return tuple(parts)
+        return tuple(parts)  # type: ignore
     parts = repo_name.rsplit(":", 1)
     if len(parts) == 2 and "/" not in parts[1]:
-        return tuple(parts)
+        return tuple(parts)  # type: ignore
     return repo_name, None
 
 
-def parse_host(addr, is_win32=False, tls=False):
+def parse_host(addr: str | None, is_win32: bool = False, tls: bool = False) -> str:
     # Sensible defaults
     if not addr and is_win32:
         return DEFAULT_NPIPE
@@ -308,7 +325,7 @@ def parse_host(addr, is_win32=False, tls=False):
     ).rstrip("/")
 
 
-def parse_devices(devices):
+def parse_devices(devices: Sequence[dict[str, str] | str]) -> list[dict[str, str]]:
     device_list = []
     for device in devices:
         if isinstance(device, dict):
@@ -337,7 +354,10 @@ def parse_devices(devices):
     return device_list
 
 
-def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):
+def kwargs_from_env(
+    assert_hostname: bool | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> dict[str, t.Any]:
     if not environment:
         environment = os.environ
     host = environment.get("DOCKER_HOST")
@@ -347,14 +367,14 @@ def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):
 
     # empty string for tls verify counts as "false".
     # Any value or 'unset' counts as true.
-    tls_verify = environment.get("DOCKER_TLS_VERIFY")
-    if tls_verify == "":
+    tls_verify_str = environment.get("DOCKER_TLS_VERIFY")
+    if tls_verify_str == "":
         tls_verify = False
     else:
-        tls_verify = tls_verify is not None
+        tls_verify = tls_verify_str is not None
     enable_tls = cert_path or tls_verify
 
-    params = {}
+    params: dict[str, t.Any] = {}
 
     if host:
         params["base_url"] = host
@@ -377,14 +397,13 @@ def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):
         ),
         ca_cert=os.path.join(cert_path, "ca.pem"),
         verify=tls_verify,
-        ssl_version=ssl_version,
         assert_hostname=assert_hostname,
     )
 
     return params
 
 
-def convert_filters(filters):
+def convert_filters(filters: Mapping[str, bool | str | list[str]]) -> str:
     result = {}
     for k, v in filters.items():
         if isinstance(v, bool):
@@ -397,7 +416,7 @@ def convert_filters(filters):
     return json.dumps(result)
 
 
-def parse_bytes(s):
+def parse_bytes(s: int | float | str) -> int | float:
     if isinstance(s, (int, float)):
         return s
     if len(s) == 0:
@@ -435,14 +454,16 @@ def parse_bytes(s):
     return s
 
 
-def normalize_links(links):
+def normalize_links(links: dict[str, str] | Sequence[tuple[str, str]]) -> list[str]:
     if isinstance(links, dict):
-        links = links.items()
+        sorted_links = sorted(links.items())
+    else:
+        sorted_links = sorted(links)
 
-    return [f"{k}:{v}" if v else k for k, v in sorted(links)]
+    return [f"{k}:{v}" if v else k for k, v in sorted_links]
 
 
-def parse_env_file(env_file):
+def parse_env_file(env_file: str | os.PathLike) -> dict[str, str]:
     """
     Reads a line-separated environment file.
     The format of each line should be "key=value".
@@ -451,7 +472,6 @@ def parse_env_file(env_file):
 
     with open(env_file, "rt", encoding="utf-8") as f:
         for line in f:
-
             if line[0] == "#":
                 continue
 
@@ -471,11 +491,11 @@ def parse_env_file(env_file):
     return environment
 
 
-def split_command(command):
+def split_command(command: str) -> list[str]:
     return shlex.split(command)
 
 
-def format_environment(environment):
+def format_environment(environment: Mapping[str, str | bytes]) -> list[str]:
     def format_env(key, value):
         if value is None:
             return key
@@ -487,16 +507,9 @@ def format_environment(environment):
     return [format_env(*var) for var in environment.items()]
 
 
-def format_extra_hosts(extra_hosts, task=False):
+def format_extra_hosts(extra_hosts: Mapping[str, str], task: bool = False) -> list[str]:
     # Use format dictated by Swarm API if container is part of a task
     if task:
         return [f"{v} {k}" for k, v in sorted(extra_hosts.items())]
 
     return [f"{k}:{v}" for k, v in sorted(extra_hosts.items())]
-
-
-def create_host_config(self, *args, **kwargs):
-    raise errors.DeprecatedMethod(
-        "utils.create_host_config has been removed. Please use a "
-        "docker.types.HostConfig object instead."
-    )