diff --git a/changelogs/fragments/9577-mh-delegate-debug.yml b/changelogs/fragments/9577-mh-delegate-debug.yml new file mode 100644 index 00000000000..9d50f68806e --- /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 e3c7a124cff..1f8d3056433 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 b10762eaba4..cf054f59fd0 100644 --- a/plugins/module_utils/mh/base.py +++ b/plugins/module_utils/mh/base.py @@ -15,6 +15,7 @@ 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 @@ def __init__(self, module=None): 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