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/errors.py

@@ -11,6 +11,8 @@
 
 from __future__ import annotations
 
+import typing as t
+
 from ansible.module_utils.common.text.converters import to_native
 
 from ._import_helper import HTTPError as _HTTPError
@@ -25,7 +27,7 @@ class DockerException(Exception):
     """
 
 
-def create_api_error_from_http_exception(e):
+def create_api_error_from_http_exception(e: _HTTPError) -> t.NoReturn:
     """
     Create a suitable APIError from requests.exceptions.HTTPError.
     """
@@ -52,14 +54,16 @@ class APIError(_HTTPError, DockerException):
     An HTTP error from the API.
     """
 
-    def __init__(self, message, response=None, explanation=None):
+    def __init__(
+        self, message: str | Exception, response=None, explanation: str | None = None
+    ) -> None:
         # requests 1.2 supports response as a keyword argument, but
         # requests 1.1 does not
         super().__init__(message)
         self.response = response
-        self.explanation = explanation
+        self.explanation = explanation or ""
 
-    def __str__(self):
+    def __str__(self) -> str:
         message = super().__str__()
 
         if self.is_client_error():
@@ -74,19 +78,20 @@ class APIError(_HTTPError, DockerException):
         return message
 
     @property
-    def status_code(self):
+    def status_code(self) -> int | None:
         if self.response is not None:
             return self.response.status_code
+        return None
 
-    def is_error(self):
+    def is_error(self) -> bool:
         return self.is_client_error() or self.is_server_error()
 
-    def is_client_error(self):
+    def is_client_error(self) -> bool:
         if self.status_code is None:
             return False
         return 400 <= self.status_code < 500
 
-    def is_server_error(self):
+    def is_server_error(self) -> bool:
         if self.status_code is None:
             return False
         return 500 <= self.status_code < 600
@@ -121,10 +126,10 @@ class DeprecatedMethod(DockerException):
 
 
 class TLSParameterError(DockerException):
-    def __init__(self, msg):
+    def __init__(self, msg: str) -> None:
         self.msg = msg
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.msg + (
             ". TLS configurations should map the Docker CLI "
             "client configurations. See "
@@ -142,7 +147,14 @@ class ContainerError(DockerException):
     Represents a container that has exited with a non-zero exit code.
     """
 
-    def __init__(self, container, exit_status, command, image, stderr):
+    def __init__(
+        self,
+        container: str,
+        exit_status: int,
+        command: list[str],
+        image: str,
+        stderr: str | None,
+    ):
         self.container = container
         self.exit_status = exit_status
         self.command = command
@@ -156,12 +168,12 @@ class ContainerError(DockerException):
 
 
 class StreamParseError(RuntimeError):
-    def __init__(self, reason):
+    def __init__(self, reason: Exception) -> None:
         self.msg = reason
 
 
 class BuildError(DockerException):
-    def __init__(self, reason, build_log):
+    def __init__(self, reason: str, build_log: str) -> None:
         super().__init__(reason)
         self.msg = reason
         self.build_log = build_log
@@ -171,7 +183,7 @@ class ImageLoadError(DockerException):
     pass
 
 
-def create_unexpected_kwargs_error(name, kwargs):
+def create_unexpected_kwargs_error(name: str, kwargs: dict[str, t.Any]) -> TypeError:
     quoted_kwargs = [f"'{k}'" for k in sorted(kwargs)]
     text = [f"{name}() "]
     if len(quoted_kwargs) == 1:
@@ -183,42 +195,44 @@ def create_unexpected_kwargs_error(name, kwargs):
 
 
 class MissingContextParameter(DockerException):
-    def __init__(self, param):
+    def __init__(self, param: str) -> None:
         self.param = param
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"missing parameter: {self.param}"
 
 
 class ContextAlreadyExists(DockerException):
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         self.name = name
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"context {self.name} already exists"
 
 
 class ContextException(DockerException):
-    def __init__(self, msg):
+    def __init__(self, msg: str) -> None:
         self.msg = msg
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.msg
 
 
 class ContextNotFound(DockerException):
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         self.name = name
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"context '{self.name}' not found"
 
 
 class MissingRequirementException(DockerException):
-    def __init__(self, msg, requirement, import_exception):
+    def __init__(
+        self, msg: str, requirement: str, import_exception: ImportError | str
+    ) -> None:
         self.msg = msg
         self.requirement = requirement
         self.import_exception = import_exception
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.msg