Make all doc fragments, module utils, and plugin utils private (#11896)

* Make all doc fragments private.

* Make all plugin utils private.

* Make all module utils private.

* Reformat.

* Changelog fragment.

* Update configs and ignores.

* Adjust unit test names.

plugins/module_utils/_mh/base.py

@@ -0,0 +1,97 @@
+# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils.basic import AnsibleModule
+
+from ansible_collections.community.general.plugins.module_utils._mh.deco import module_fails_on_exception
+from ansible_collections.community.general.plugins.module_utils._mh.exceptions import ModuleHelperException as _MHE
+
+
+class ModuleHelperBase:
+    module: dict[str, t.Any] | None = None  # TODO: better spec using t.TypedDict
+    ModuleHelperException = _MHE
+    _delegated_to_module: tuple[str, ...] = (
+        "check_mode",
+        "get_bin_path",
+        "warn",
+        "deprecate",
+        "debug",
+    )
+
+    def __init__(self, module=None):
+        self._changed = False
+
+        if module:
+            self.module = module
+
+        if not isinstance(self.module, AnsibleModule):
+            self.module = AnsibleModule(**self.module)
+
+    @property
+    def diff_mode(self):
+        return self.module._diff
+
+    @property
+    def verbosity(self):
+        return self.module._verbosity
+
+    def do_raise(self, *args, **kwargs) -> t.NoReturn:
+        raise _MHE(*args, **kwargs)
+
+    def __getattr__(self, attr):
+        if attr in self._delegated_to_module:
+            return getattr(self.module, attr)
+        raise AttributeError(f"ModuleHelperBase has no attribute '{attr}'")
+
+    def __init_module__(self):
+        pass
+
+    def __run__(self):
+        raise NotImplementedError()
+
+    def __quit_module__(self):
+        pass
+
+    def __changed__(self):
+        raise NotImplementedError()
+
+    @property
+    def changed(self) -> bool:
+        try:
+            return self.__changed__()
+        except NotImplementedError:
+            return self._changed
+
+    @changed.setter
+    def changed(self, value: bool) -> None:
+        self._changed = value
+
+    def has_changed(self):
+        raise NotImplementedError()
+
+    @property
+    def output(self):
+        raise NotImplementedError()
+
+    @module_fails_on_exception
+    def run(self):
+        self.__init_module__()
+        self.__run__()
+        self.__quit_module__()
+        output = self.output
+        if "failed" not in output:
+            output["failed"] = False
+        self.module.exit_json(changed=self.has_changed(), **output)
+
+    @classmethod
+    def execute(cls, module=None):
+        cls(module).run()

plugins/module_utils/_mh/deco.py

@@ -0,0 +1,122 @@
+# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import traceback
+from contextlib import contextmanager
+from functools import wraps
+
+from ansible_collections.community.general.plugins.module_utils._mh.exceptions import (
+    ModuleHelperException,
+    _UnhandledSentinel,
+)
+
+_unhandled_exceptions: tuple[type[Exception], ...] = (_UnhandledSentinel,)
+
+
+def cause_changes(when=None):
+    def deco(func):
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            try:
+                func(self, *args, **kwargs)
+                if when == "success":
+                    self.changed = True
+            except Exception:
+                if when == "failure":
+                    self.changed = True
+                raise
+            finally:
+                if when == "always":
+                    self.changed = True
+
+        return wrapper
+
+    return deco
+
+
+@contextmanager
+def no_handle_exceptions(*exceptions: type[Exception]):
+    global _unhandled_exceptions
+    current = _unhandled_exceptions
+    _unhandled_exceptions = tuple(exceptions)
+    try:
+        yield
+    finally:
+        _unhandled_exceptions = current
+
+
+def module_fails_on_exception(func):
+    conflict_list = ("msg", "exception", "output", "vars", "changed")
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        def fix_key(k):
+            return k if k not in conflict_list else f"_{k}"
+
+        def fix_var_conflicts(output):
+            result = {fix_key(k): v for k, v in output.items()}
+            return result
+
+        try:
+            func(self, *args, **kwargs)
+        except _unhandled_exceptions:
+            # re-raise exception without further processing
+            raise
+        except ModuleHelperException as e:
+            if e.update_output:
+                self.update_output(e.update_output)
+            # patchy solution to resolve conflict with output variables
+            output = fix_var_conflicts(self.output)
+            self.module.fail_json(
+                msg=e.msg, exception=traceback.format_exc(), output=self.output, vars=self.vars.output(), **output
+            )
+        except Exception as e:
+            # patchy solution to resolve conflict with output variables
+            output = fix_var_conflicts(self.output)
+            msg = f"Module failed with exception: {str(e).strip()}"
+            self.module.fail_json(
+                msg=msg, exception=traceback.format_exc(), output=self.output, vars=self.vars.output(), **output
+            )
+
+    return wrapper
+
+
+def check_mode_skip(func):
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        if not self.module.check_mode:
+            return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+def check_mode_skip_returns(callable=None, value=None):
+    def deco(func):
+        if callable is not None:
+
+            @wraps(func)
+            def wrapper_callable(self, *args, **kwargs):
+                if self.module.check_mode:
+                    return callable(self, *args, **kwargs)
+                return func(self, *args, **kwargs)
+
+            return wrapper_callable
+
+        else:
+
+            @wraps(func)
+            def wrapper_value(self, *args, **kwargs):
+                if self.module.check_mode:
+                    return value
+                return func(self, *args, **kwargs)
+
+            return wrapper_value
+
+    return deco

plugins/module_utils/_mh/exceptions.py

@@ -0,0 +1,24 @@
+# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+
+class ModuleHelperException(Exception):
+    def __init__(self, msg: str, update_output: dict[str, t.Any] | None = None, *args, **kwargs) -> None:
+        self.msg: str = msg or f"Module failed with exception: {self}"
+        if update_output is None:
+            update_output = {}
+        self.update_output: dict[str, t.Any] = update_output
+        super().__init__(*args)
+
+
+class _UnhandledSentinel(Exception):
+    pass

plugins/module_utils/_mh/mixins/deprecate_attrs.py

@@ -0,0 +1,77 @@
+# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+class DeprecateAttrsMixin:
+    def _deprecate_setup(
+        self, attr: str, target: object | None, module: AnsibleModule | None
+    ) -> tuple[object, AnsibleModule, dict[str, t.Any], dict[str, t.Any]]:
+        if target is None:
+            target = self
+        if not hasattr(target, attr):
+            raise ValueError(f"Target {target} has no attribute {attr}")
+        if module is None:
+            if isinstance(target, AnsibleModule):
+                module = target
+            elif hasattr(target, "module") and isinstance(target.module, AnsibleModule):
+                module = target.module
+            else:
+                raise ValueError(
+                    "Failed to automatically discover the AnsibleModule instance. Pass 'module' parameter explicitly."
+                )
+
+        # setup internal state dicts
+        value_attr = "__deprecated_attr_value"
+        trigger_attr = "__deprecated_attr_trigger"
+        if not hasattr(target, value_attr):
+            setattr(target, value_attr, {})
+        if not hasattr(target, trigger_attr):
+            setattr(target, trigger_attr, {})
+        value_dict = getattr(target, value_attr)
+        trigger_dict = getattr(target, trigger_attr)
+        return target, module, value_dict, trigger_dict
+
+    def _deprecate_attr(
+        self,
+        attr: str,
+        msg: str,
+        version: str | None = None,
+        date: str | None = None,
+        collection_name: str | None = None,
+        target: object | None = None,
+        value=None,
+        module: AnsibleModule | None = None,
+    ) -> None:
+        target, module, value_dict, trigger_dict = self._deprecate_setup(attr, target, module)
+
+        value_dict[attr] = getattr(target, attr, value)
+        trigger_dict[attr] = False
+
+        def _trigger():
+            if not trigger_dict[attr]:
+                module.deprecate(msg, version=version, date=date, collection_name=collection_name)
+                trigger_dict[attr] = True
+
+        def _getter(_self):
+            _trigger()
+            return value_dict[attr]
+
+        def _setter(_self, new_value):
+            _trigger()
+            value_dict[attr] = new_value
+
+        # override attribute
+        prop = property(_getter)
+        setattr(target, attr, prop)
+        setattr(target, f"_{attr}_setter", prop.setter(_setter))

plugins/module_utils/_mh/mixins/state.py

@@ -0,0 +1,43 @@
+# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+
+class StateMixin:
+    state_param: str = "state"
+    default_state: str | None = None
+
+    def _state(self) -> str:
+        state: str = self.module.params.get(self.state_param)  # type: ignore[attr-defined]
+        return self.default_state if state is None else state
+
+    def _method(self, state: str) -> str:
+        return f"{self.state_param}_{state}"
+
+    def __run__(self):
+        state = self._state()
+        self.vars.state = state
+
+        # resolve aliases
+        if state not in self.module.params:
+            aliased = [name for name, param in self.module.argument_spec.items() if state in param.get("aliases", [])]
+            if aliased:
+                state = aliased[0]
+                self.vars.effective_state = state
+
+        method = self._method(state)
+        if not hasattr(self, method):
+            return self.__state_fallback__()
+        func = getattr(self, method)
+        return func()
+
+    def __state_fallback__(self) -> t.NoReturn:
+        raise ValueError(f"Cannot find method: {self._method(self._state())}")

plugins/module_utils/_mh/module_helper.py

@@ -0,0 +1,81 @@
+# (c) 2020-2024, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2020-2024, Ansible Project
+# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils.common.dict_transformations import dict_merge
+
+from ansible_collections.community.general.plugins.module_utils._mh.base import ModuleHelperBase
+from ansible_collections.community.general.plugins.module_utils._mh.mixins.deprecate_attrs import DeprecateAttrsMixin
+from ansible_collections.community.general.plugins.module_utils._mh.mixins.state import StateMixin
+from ansible_collections.community.general.plugins.module_utils._vardict import VarDict
+
+if t.TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from ansible.module_utils.basic import AnsibleModule
+
+
+class ModuleHelper(DeprecateAttrsMixin, ModuleHelperBase):
+    facts_name: str | None = None
+    output_params: Sequence[str] = ()
+    diff_params: Sequence[str] = ()
+    change_params: Sequence[str] = ()
+    facts_params: Sequence[str] = ()
+
+    def __init__(self, module: AnsibleModule | dict[str, t.Any] | None = None) -> None:
+        super().__init__(module)
+
+        self.vars = VarDict()
+        for name, value in self.module.params.items():  # type: ignore[union-attr]
+            self.vars.set(
+                name,
+                value,
+                diff=name in self.diff_params,
+                output=name in self.output_params,
+                change=None if not self.change_params else name in self.change_params,
+                fact=name in self.facts_params,
+            )
+
+    def update_vars(self, meta: dict[str, t.Any] | None = None, **kwargs: t.Any) -> None:
+        if meta is None:
+            meta = {}
+        for k, v in kwargs.items():
+            self.vars.set(k, v, **meta)
+
+    def update_output(self, **kwargs: t.Any) -> None:
+        self.update_vars(meta={"output": True}, **kwargs)
+
+    def update_facts(self, **kwargs: t.Any) -> None:
+        self.update_vars(meta={"fact": True}, **kwargs)
+
+    def _vars_changed(self) -> bool:
+        return self.vars.has_changed
+
+    def has_changed(self) -> bool:
+        return self.changed or self._vars_changed()
+
+    @property
+    def output(self) -> dict[str, t.Any]:
+        result = dict(self.vars.output())
+        if self.facts_name:
+            facts = self.vars.facts()
+            if facts is not None:
+                result["ansible_facts"] = {self.facts_name: facts}
+        if self.diff_mode:
+            diff = result.get("diff", {})
+            vars_diff = self.vars.diff() or {}
+            result["diff"] = dict_merge(dict(diff), vars_diff)
+
+        return result
+
+
+class StateModuleHelper(StateMixin, ModuleHelper):
+    pass