Add basic typing for module_utils (#11222)

* Add basic typing for module_utils.

* Apply some suggestions.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* Make pass again.

* Add more types as suggested.

* Normalize extra imports.

* Add more type hints.

* Improve typing.

* Add changelog fragment.

* Reduce changelog.

* Apply suggestions from code review.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* Fix typo.

* Cleanup.

* Improve types and make type checking happy.

* Let's see whether older Pythons barf on this.

* Revert "Let's see whether older Pythons barf on this."

This reverts commit 9973af3dbe.

* Add noqa.

---------

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

plugins/module_utils/manageiq.py

@@ -15,9 +15,13 @@ from __future__ import annotations
 
 import os
 import traceback
+import typing as t
 
 from ansible.module_utils.basic import missing_required_lib
 
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+
 CLIENT_IMP_ERR = None
 try:
     from manageiq_client.api import ManageIQClient
@@ -28,7 +32,7 @@ except ImportError:
     HAS_CLIENT = False
 
 
-def manageiq_argument_spec():
+def manageiq_argument_spec() -> dict[str, t.Any]:
     options = dict(
         url=dict(default=os.environ.get("MIQ_URL", None)),
         username=dict(default=os.environ.get("MIQ_USERNAME", None)),
@@ -43,27 +47,28 @@ def manageiq_argument_spec():
     )
 
 
-def check_client(module):
+def check_client(module: AnsibleModule) -> None:
     if not HAS_CLIENT:
         module.fail_json(msg=missing_required_lib("manageiq-client"), exception=CLIENT_IMP_ERR)
 
 
-def validate_connection_params(module):
-    params = module.params["manageiq_connection"]
+def validate_connection_params(module: AnsibleModule) -> dict[str, t.Any]:
+    params: dict[str, t.Any] = module.params["manageiq_connection"]
     error_str = "missing required argument: manageiq_connection[{}]"
-    url = params["url"]
-    token = params["token"]
-    username = params["username"]
-    password = params["password"]
+    url: str | None = params["url"]
+    token: str | None = params["token"]
+    username: str | None = params["username"]
+    password: str | None = params["password"]
 
     if (url and username and password) or (url and token):
         return params
     for arg in ["url", "username", "password"]:
         if params[arg] in (None, ""):
             module.fail_json(msg=error_str.format(arg))
+    raise AssertionError("should be unreachable")
 
 
-def manageiq_entities():
+def manageiq_entities() -> dict[str, str]:
     return {
         "provider": "providers",
         "host": "hosts",
@@ -87,7 +92,7 @@ class ManageIQ:
     class encapsulating ManageIQ API client.
     """
 
-    def __init__(self, module):
+    def __init__(self, module: AnsibleModule) -> None:
         # handle import errors
         check_client(module)
 
@@ -111,7 +116,7 @@ class ManageIQ:
             self.module.fail_json(msg=f"failed to open connection ({url}): {e}")
 
     @property
-    def module(self):
+    def module(self) -> AnsibleModule:
         """Ansible module module
 
         Returns:
@@ -120,7 +125,7 @@ class ManageIQ:
         return self._module
 
     @property
-    def api_url(self):
+    def api_url(self) -> str:
         """Base ManageIQ API
 
         Returns:
@@ -192,7 +197,7 @@ class ManageIQPolicies:
     Object to execute policies management operations of manageiq resources.
     """
 
-    def __init__(self, manageiq, resource_type, resource_id):
+    def __init__(self, manageiq: ManageIQ, resource_type, resource_id):
         self.manageiq = manageiq
 
         self.module = self.manageiq.module
@@ -330,7 +335,7 @@ class ManageIQTags:
     Object to execute tags management operations of manageiq resources.
     """
 
-    def __init__(self, manageiq, resource_type, resource_id):
+    def __init__(self, manageiq: ManageIQ, resource_type, resource_id):
         self.manageiq = manageiq
 
         self.module = self.manageiq.module