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/context/api.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import json
 import os
+import typing as t
 
 from .. import errors
 from .config import (
@@ -24,7 +25,11 @@ from .config import (
 from .context import Context
 
 
-def create_default_context():
+if t.TYPE_CHECKING:
+    from ..tls import TLSConfig
+
+
+def create_default_context() -> Context:
     host = None
     if os.environ.get("DOCKER_HOST"):
         host = os.environ.get("DOCKER_HOST")
@@ -42,7 +47,7 @@ class ContextAPI:
     DEFAULT_CONTEXT = None
 
     @classmethod
-    def get_default_context(cls):
+    def get_default_context(cls) -> Context:
         context = cls.DEFAULT_CONTEXT
         if context is None:
             context = create_default_context()
@@ -52,13 +57,13 @@ class ContextAPI:
     @classmethod
     def create_context(
         cls,
-        name,
-        orchestrator=None,
-        host=None,
-        tls_cfg=None,
-        default_namespace=None,
-        skip_tls_verify=False,
-    ):
+        name: str,
+        orchestrator: str | None = None,
+        host: str | None = None,
+        tls_cfg: TLSConfig | None = None,
+        default_namespace: str | None = None,
+        skip_tls_verify: bool = False,
+    ) -> Context:
         """Creates a new context.
         Returns:
             (Context): a Context object.
@@ -108,7 +113,7 @@ class ContextAPI:
         return ctx
 
     @classmethod
-    def get_context(cls, name=None):
+    def get_context(cls, name: str | None = None) -> Context | None:
         """Retrieves a context object.
         Args:
             name (str): The name of the context
@@ -136,7 +141,7 @@ class ContextAPI:
         return Context.load_context(name)
 
     @classmethod
-    def contexts(cls):
+    def contexts(cls) -> list[Context]:
         """Context list.
         Returns:
             (Context): List of context objects.
@@ -170,7 +175,7 @@ class ContextAPI:
         return contexts
 
     @classmethod
-    def get_current_context(cls):
+    def get_current_context(cls) -> Context | None:
         """Get current context.
         Returns:
             (Context): current context object.
@@ -178,7 +183,7 @@ class ContextAPI:
         return cls.get_context()
 
     @classmethod
-    def set_current_context(cls, name="default"):
+    def set_current_context(cls, name: str = "default") -> None:
         ctx = cls.get_context(name)
         if not ctx:
             raise errors.ContextNotFound(name)
@@ -188,7 +193,7 @@ class ContextAPI:
             raise errors.ContextException(f"Failed to set current context: {err}")
 
     @classmethod
-    def remove_context(cls, name):
+    def remove_context(cls, name: str) -> None:
         """Remove a context. Similar to the ``docker context rm`` command.
 
         Args:
@@ -220,7 +225,7 @@ class ContextAPI:
         ctx.remove()
 
     @classmethod
-    def inspect_context(cls, name="default"):
+    def inspect_context(cls, name: str = "default") -> dict[str, t.Any]:
         """Inspect a context. Similar to the ``docker context inspect`` command.
 
         Args:

plugins/module_utils/_api/context/config.py

@@ -23,7 +23,7 @@ from ..utils.utils import parse_host
 METAFILE = "meta.json"
 
 
-def get_current_context_name_with_source():
+def get_current_context_name_with_source() -> tuple[str, str]:
     if os.environ.get("DOCKER_HOST"):
         return "default", "DOCKER_HOST environment variable set"
     if os.environ.get("DOCKER_CONTEXT"):
@@ -41,11 +41,11 @@ def get_current_context_name_with_source():
     return "default", "fallback value"
 
 
-def get_current_context_name():
+def get_current_context_name() -> str:
     return get_current_context_name_with_source()[0]
 
 
-def write_context_name_to_docker_config(name=None):
+def write_context_name_to_docker_config(name: str | None = None) -> Exception | None:
     if name == "default":
         name = None
     docker_cfg_path = find_config_file()
@@ -62,44 +62,45 @@ def write_context_name_to_docker_config(name=None):
     elif name:
         config["currentContext"] = name
     else:
-        return
+        return None
     if not docker_cfg_path:
         docker_cfg_path = get_default_config_file()
     try:
         with open(docker_cfg_path, "wt", encoding="utf-8") as f:
             json.dump(config, f, indent=4)
+        return None
     except Exception as e:  # pylint: disable=broad-exception-caught
         return e
 
 
-def get_context_id(name):
+def get_context_id(name: str) -> str:
     return hashlib.sha256(name.encode("utf-8")).hexdigest()
 
 
-def get_context_dir():
+def get_context_dir() -> str:
     docker_cfg_path = find_config_file() or get_default_config_file()
     return os.path.join(os.path.dirname(docker_cfg_path), "contexts")
 
 
-def get_meta_dir(name=None):
+def get_meta_dir(name: str | None = None) -> str:
     meta_dir = os.path.join(get_context_dir(), "meta")
     if name:
         return os.path.join(meta_dir, get_context_id(name))
     return meta_dir
 
 
-def get_meta_file(name):
+def get_meta_file(name) -> str:
     return os.path.join(get_meta_dir(name), METAFILE)
 
 
-def get_tls_dir(name=None, endpoint=""):
+def get_tls_dir(name: str | None = None, endpoint: str = "") -> str:
     context_dir = get_context_dir()
     if name:
         return os.path.join(context_dir, "tls", get_context_id(name), endpoint)
     return os.path.join(context_dir, "tls")
 
 
-def get_context_host(path=None, tls=False):
+def get_context_host(path: str | None = None, tls: bool = False) -> str:
     host = parse_host(path, IS_WINDOWS_PLATFORM, tls)
     if host == DEFAULT_UNIX_SOCKET:
         # remove http+ from default docker socket url

plugins/module_utils/_api/context/context.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import json
 import os
+import typing as t
 from shutil import copyfile, rmtree
 
 from ..errors import ContextException
@@ -33,21 +34,21 @@ class Context:
 
     def __init__(
         self,
-        name,
-        orchestrator=None,
-        host=None,
-        endpoints=None,
-        skip_tls_verify=False,
-        tls=False,
-        description=None,
-    ):
+        name: str,
+        orchestrator: str | None = None,
+        host: str | None = None,
+        endpoints: dict[str, dict[str, t.Any]] | None = None,
+        skip_tls_verify: bool = False,
+        tls: bool = False,
+        description: str | None = None,
+    ) -> None:
         if not name:
             raise ValueError("Name not provided")
         self.name = name
         self.context_type = None
         self.orchestrator = orchestrator
         self.endpoints = {}
-        self.tls_cfg = {}
+        self.tls_cfg: dict[str, TLSConfig] = {}
         self.meta_path = IN_MEMORY
         self.tls_path = IN_MEMORY
         self.description = description
@@ -89,12 +90,12 @@ class Context:
 
     def set_endpoint(
         self,
-        name="docker",
-        host=None,
-        tls_cfg=None,
-        skip_tls_verify=False,
-        def_namespace=None,
-    ):
+        name: str = "docker",
+        host: str | None = None,
+        tls_cfg: TLSConfig | None = None,
+        skip_tls_verify: bool = False,
+        def_namespace: str | None = None,
+    ) -> None:
         self.endpoints[name] = {
             "Host": get_context_host(host, not skip_tls_verify or tls_cfg is not None),
             "SkipTLSVerify": skip_tls_verify,
@@ -105,11 +106,11 @@ class Context:
         if tls_cfg:
             self.tls_cfg[name] = tls_cfg
 
-    def inspect(self):
+    def inspect(self) -> dict[str, t.Any]:
         return self()
 
     @classmethod
-    def load_context(cls, name):
+    def load_context(cls, name: str) -> t.Self | None:
         meta = Context._load_meta(name)
         if meta:
             instance = cls(
@@ -125,12 +126,12 @@ class Context:
         return None
 
     @classmethod
-    def _load_meta(cls, name):
+    def _load_meta(cls, name: str) -> dict[str, t.Any] | None:
         meta_file = get_meta_file(name)
         if not os.path.isfile(meta_file):
             return None
 
-        metadata = {}
+        metadata: dict[str, t.Any] = {}
         try:
             with open(meta_file, "rt", encoding="utf-8") as f:
                 metadata = json.load(f)
@@ -154,7 +155,7 @@ class Context:
 
         return metadata
 
-    def _load_certs(self):
+    def _load_certs(self) -> None:
         certs = {}
         tls_dir = get_tls_dir(self.name)
         for endpoint in self.endpoints:
@@ -184,7 +185,7 @@ class Context:
         self.tls_cfg = certs
         self.tls_path = tls_dir
 
-    def save(self):
+    def save(self) -> None:
         meta_dir = get_meta_dir(self.name)
         if not os.path.isdir(meta_dir):
             os.makedirs(meta_dir)
@@ -216,54 +217,54 @@ class Context:
         self.meta_path = get_meta_dir(self.name)
         self.tls_path = get_tls_dir(self.name)
 
-    def remove(self):
+    def remove(self) -> None:
         if os.path.isdir(self.meta_path):
             rmtree(self.meta_path)
         if os.path.isdir(self.tls_path):
             rmtree(self.tls_path)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: '{self.name}'>"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return json.dumps(self.__call__(), indent=2)
 
-    def __call__(self):
+    def __call__(self) -> dict[str, t.Any]:
         result = self.Metadata
         result.update(self.TLSMaterial)
         result.update(self.Storage)
         return result
 
-    def is_docker_host(self):
+    def is_docker_host(self) -> bool:
         return self.context_type is None
 
     @property
-    def Name(self):  # pylint: disable=invalid-name
+    def Name(self) -> str:  # pylint: disable=invalid-name
         return self.name
 
     @property
-    def Host(self):  # pylint: disable=invalid-name
+    def Host(self) -> str | None:  # pylint: disable=invalid-name
         if not self.orchestrator or self.orchestrator == "swarm":
             endpoint = self.endpoints.get("docker", None)
             if endpoint:
-                return endpoint.get("Host", None)
+                return endpoint.get("Host", None)  # type: ignore
             return None
 
-        return self.endpoints[self.orchestrator].get("Host", None)
+        return self.endpoints[self.orchestrator].get("Host", None)  # type: ignore
 
     @property
-    def Orchestrator(self):  # pylint: disable=invalid-name
+    def Orchestrator(self) -> str | None:  # pylint: disable=invalid-name
         return self.orchestrator
 
     @property
-    def Metadata(self):  # pylint: disable=invalid-name
-        meta = {}
+    def Metadata(self) -> dict[str, t.Any]:  # pylint: disable=invalid-name
+        meta: dict[str, t.Any] = {}
         if self.orchestrator:
             meta = {"StackOrchestrator": self.orchestrator}
         return {"Name": self.name, "Metadata": meta, "Endpoints": self.endpoints}
 
     @property
-    def TLSConfig(self):  # pylint: disable=invalid-name
+    def TLSConfig(self) -> TLSConfig | None:  # pylint: disable=invalid-name
         key = self.orchestrator
         if not key or key == "swarm":
             key = "docker"
@@ -272,13 +273,15 @@ class Context:
         return None
 
     @property
-    def TLSMaterial(self):  # pylint: disable=invalid-name
-        certs = {}
+    def TLSMaterial(self) -> dict[str, t.Any]:  # pylint: disable=invalid-name
+        certs: dict[str, t.Any] = {}
         for endpoint, tls in self.tls_cfg.items():
-            cert, key = tls.cert
-            certs[endpoint] = list(map(os.path.basename, [tls.ca_cert, cert, key]))
+            paths = [tls.ca_cert, *tls.cert] if tls.cert else [tls.ca_cert]
+            certs[endpoint] = [
+                os.path.basename(path) if path else None for path in paths
+            ]
         return {"TLSMaterial": certs}
 
     @property
-    def Storage(self):  # pylint: disable=invalid-name
+    def Storage(self) -> dict[str, t.Any]:  # pylint: disable=invalid-name
         return {"Storage": {"MetadataPath": self.meta_path, "TLSPath": self.tls_path}}