From 7fa859a3b893f58a791bc39083907b14ac0157c3 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Tue, 21 Jan 2025 07:38:14 +1300
Subject: [PATCH] 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 |  6 ++++++
 docs/docsite/rst/guide_modulehelper.rst         |  5 +++++
 plugins/module_utils/mh/base.py                 | 13 +++++++++++++
 3 files changed, 24 insertions(+)
 create mode 100644 changelogs/fragments/9577-mh-delegate-debug.yml

diff --git a/changelogs/fragments/9577-mh-delegate-debug.yml b/changelogs/fragments/9577-mh-delegate-debug.yml
new file mode 100644
index 0000000000..9d50f68806
--- /dev/null
+++ b/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).
diff --git a/docs/docsite/rst/guide_modulehelper.rst b/docs/docsite/rst/guide_modulehelper.rst
index e3c7a124cf..1f8d305643 100644
--- a/docs/docsite/rst/guide_modulehelper.rst
+++ b/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
 """"""""""
 
diff --git a/plugins/module_utils/mh/base.py b/plugins/module_utils/mh/base.py
index b10762eaba..cf054f59fd 100644
--- a/plugins/module_utils/mh/base.py
+++ b/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