From 91cac4c8165b29d590482e2d39522fc2e1630d9d Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Mon, 24 Oct 2022 03:34:04 +1300
Subject: [PATCH] MH CmdModuleHelper: deprecation (#5370)

* MH CmdModuleHelper: deprecation

* add changelog fragment

* add deprecation comments in many parts of the code
---
 .../fragments/5370-mh-cmdmixin-deprecation.yaml  |  5 +++++
 plugins/module_utils/mh/mixins/cmd.py            | 16 ++++++++++++++++
 plugins/module_utils/mh/module_helper.py         |  8 ++++++++
 3 files changed, 29 insertions(+)
 create mode 100644 changelogs/fragments/5370-mh-cmdmixin-deprecation.yaml

diff --git a/changelogs/fragments/5370-mh-cmdmixin-deprecation.yaml b/changelogs/fragments/5370-mh-cmdmixin-deprecation.yaml
new file mode 100644
index 0000000000..4c4273358a
--- /dev/null
+++ b/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).
diff --git a/plugins/module_utils/mh/mixins/cmd.py b/plugins/module_utils/mh/mixins/cmd.py
index da2629f9fe..a7d3793949 100644
--- a/plugins/module_utils/mh/mixins/cmd.py
+++ b/plugins/module_utils/mh/mixins/cmd.py
@@ -34,6 +34,10 @@ class ArgFormat(object):
 
     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 @@ class ArgFormat(object):
 
 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 @@ class CmdMixin(object):
             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))
diff --git a/plugins/module_utils/mh/module_helper.py b/plugins/module_utils/mh/module_helper.py
index 4251285751..79b6f48752 100644
--- a/plugins/module_utils/mh/module_helper.py
+++ b/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