module helper: delegate debug() to AnsibleModule (#9577)

* module helper: delegate debug() to AnsibleModule

* add changelog frag

* add comments for future

* use deprecate()

* fix errors

changelogs/fragments/9577-mh-delegate-debug.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - MH module utils - delegate ``debug`` to the underlying ``AnsibleModule`` instance or issues a warning if an attribute already exists with that name (https://github.com/ansible-collections/community.general/pull/9577).
+deprecated_features:
+  - >
+    MH module utils - attribute ``debug`` definition in subclasses of MH is now deprecated, as that name will become a delegation to ``AnsibleModule`` in
+    community.general 12.0.0, and any such attribute will be overridden by that delegation in that version (https://github.com/ansible-collections/community.general/pull/9577).

docs/docsite/rst/guide_modulehelper.rst

@@ -468,6 +468,11 @@ Additionally, MH will also delegate:
 - ``diff_mode`` to ``self.module._diff``
 - ``verbosity`` to ``self.module._verbosity``
 
+Starting in community.general 10.3.0, MH will also delegate the method ``debug`` to ``self.module``.
+If any existing module already has a ``debug`` attribute defined, a warning message will be generated,
+requesting it to be renamed. Upon the release of community.general 12.0.0, the delegation will be
+preemptive and will override any existing method or property in the subclasses.
+
 Decorators
 """"""""""
 

plugins/module_utils/mh/base.py

@@ -15,6 +15,7 @@ from ansible_collections.community.general.plugins.module_utils.mh.deco import m
 class ModuleHelperBase(object):
     module = None
     ModuleHelperException = _MHE
+    # in 12.0.0 add 'debug' to the tuple
     _delegated_to_module = (
         'check_mode', 'get_bin_path', 'warn', 'deprecate',
     )
@@ -28,6 +29,18 @@ class ModuleHelperBase(object):
         if not isinstance(self.module, AnsibleModule):
             self.module = AnsibleModule(**self.module)
 
+        # in 12.0.0 remove this if statement entirely
+        if hasattr(self, 'debug'):
+            msg = (
+                "This class ({cls}) has an attribute 'debug' defined and that is deprecated. "
+                "Method 'debug' will be an integral part of ModuleHelper in community.general "
+                "12.0.0, delegated to the underlying AnsibleModule object. "
+                "Please rename the existing attribute to prevent this message from showing.".format(cls=self.__class__.__name__)
+            )
+            self.deprecate(msg, version="12.0.0", collection_name="community.general")
+        else:
+            self._delegated_to_module = self._delegated_to_module + ('debug',)
+
     @property
     def diff_mode(self):
         return self.module._diff