MH CmdModuleHelper: deprecation (#5370)

* MH CmdModuleHelper: deprecation

* add changelog fragment

* add deprecation comments in many parts of the code

changelogs/fragments/5370-mh-cmdmixin-deprecation.yaml

@@ -0,0 +1,5 @@
+deprecated_features:
+  - CmdMixin module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370).
+  - CmdModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370).
+  - CmdStateModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370).
+  - ArgFormat module utils - deprecated along ``CmdMixin``, in favor of the ``cmd_runner_fmt`` module util (https://github.com/ansible-collections/community.general/pull/5370).

plugins/module_utils/mh/mixins/cmd.py

@@ -34,6 +34,10 @@ def deco(f):
 
     def __init__(self, name, fmt=None, style=FORMAT, stars=0):
         """
+        THIS CLASS IS BEING DEPRECATED.
+        It was never meant to be used outside the scope of CmdMixin, and CmdMixin is being deprecated.
+        See the deprecation notice in ``CmdMixin.__init__()`` below.
+
         Creates a CLI-formatter for one specific argument. The argument may be a module parameter or just a named parameter for
         the CLI command execution.
         :param name: Name of the argument to be formatted
@@ -88,6 +92,9 @@ def to_text(self, value):
 
 class CmdMixin(object):
     """
+    THIS CLASS IS BEING DEPRECATED.
+    See the deprecation notice in ``CmdMixin.__init__()`` below.
+
     Mixin for mapping module options to running a CLI command with its arguments.
     """
     command = None
@@ -110,6 +117,15 @@ def custom_formats(self):
             result[param] = ArgFormat(param, **fmt_spec)
         return result
 
+    def __init__(self, *args, **kwargs):
+        super(CmdMixin, self).__init__(*args, **kwargs)
+        self.module.deprecate(
+            'The CmdMixin used in classes CmdModuleHelper and CmdStateModuleHelper is being deprecated. '
+            'Modules should use community.general.plugins.module_utils.cmd_runner.CmdRunner instead.',
+            version='8.0.0',
+            collection_name='community.general',
+        )
+
     def _calculate_args(self, extra_params=None, params=None):
         def add_arg_formatted_param(_cmd_args, arg_format, _value):
             args = list(arg_format.to_text(_value))

plugins/module_utils/mh/module_helper.py

@@ -84,8 +84,16 @@ class StateModuleHelper(StateMixin, ModuleHelper):
 
 
 class CmdModuleHelper(CmdMixin, ModuleHelper):
+    """
+    THIS CLASS IS BEING DEPRECATED.
+    See the deprecation notice in ``CmdMixin.__init__()``.
+    """
     pass
 
 
 class CmdStateModuleHelper(CmdMixin, StateMixin, ModuleHelper):
+    """
+    THIS CLASS IS BEING DEPRECATED.
+    See the deprecation notice in ``CmdMixin.__init__()``.
+    """
     pass