Change MH to use the module_utils.vardict.VarDict (#8226)

* change MH to use the module_utils.vardict.VarDict

* remove VarsMixin from superclasses of MH

* bump vardict deprecation to 11.0.0 + add old/new vardict selection in MH

* improve backawards compatibility

* improve backawards compatibility

* use new vardict in some modules, make adjustments

* add changelog frag

* adjustment after rebase

changelogs/fragments/8226-mh-vardict.yml

@@ -0,0 +1,10 @@
+deprecated_features:
+  - ModuleHelper vars module_utils - bump deprecation of ``VarMeta``, ``VarDict`` and ``VarsMixin`` to version 11.0.0 (https://github.com/ansible-collections/community.general/pull/8226).
+  - ModuleHelper module_utils - deprecate use of ``VarsMixin`` in favor of using the ``VardDict`` module_utils (https://github.com/ansible-collections/community.general/pull/8226).
+minor_changes:
+  - gconftool2 - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).
+  - kernel_blacklist - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).
+  - opkg - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).
+  - pipx - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).
+  - xfconf - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).
+  - xfconf_info - use ``ModuleHelper`` with ``VarDict`` (https://github.com/ansible-collections/community.general/pull/8226).

plugins/module_utils/mh/mixins/vars.py

@@ -14,7 +14,7 @@ class VarMeta(object):
     """
     DEPRECATION WARNING
 
-    This class is deprecated and will be removed in community.general 10.0.0
+    This class is deprecated and will be removed in community.general 11.0.0
     Modules should use the VarDict from plugins/module_utils/vardict.py instead.
     """
 
@@ -70,7 +70,7 @@ class VarDict(object):
     """
     DEPRECATION WARNING
 
-    This class is deprecated and will be removed in community.general 10.0.0
+    This class is deprecated and will be removed in community.general 11.0.0
     Modules should use the VarDict from plugins/module_utils/vardict.py instead.
     """
     def __init__(self):
@@ -139,7 +139,7 @@ class VarsMixin(object):
     """
     DEPRECATION WARNING
 
-    This class is deprecated and will be removed in community.general 10.0.0
+    This class is deprecated and will be removed in community.general 11.0.0
     Modules should use the VarDict from plugins/module_utils/vardict.py instead.
     """
     def __init__(self, module=None):

plugins/module_utils/mh/module_helper.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
-# (c) 2020, Alexei Znamensky <russoz@gmail.com>
+# (c) 2020-2024, Alexei Znamensky <russoz@gmail.com>
-# Copyright (c) 2020, Ansible Project
+# Copyright (c) 2020-2024, Ansible Project
 # Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
 # SPDX-License-Identifier: BSD-2-Clause
 
@@ -10,22 +10,40 @@ __metaclass__ = type
 
 from ansible.module_utils.common.dict_transformations import dict_merge
 
+from ansible_collections.community.general.plugins.module_utils.vardict import VarDict as _NewVarDict  # remove "as NewVarDict" in 11.0.0
 # (TODO: remove AnsibleModule!) pylint: disable-next=unused-import
-from ansible_collections.community.general.plugins.module_utils.mh.base import ModuleHelperBase, AnsibleModule  # noqa: F401
+from ansible_collections.community.general.plugins.module_utils.mh.base import AnsibleModule  # noqa: F401 DEPRECATED, remove in 11.0.0
+from ansible_collections.community.general.plugins.module_utils.mh.base import ModuleHelperBase
 from ansible_collections.community.general.plugins.module_utils.mh.mixins.state import StateMixin
-from ansible_collections.community.general.plugins.module_utils.mh.mixins.vars import VarsMixin
+# (TODO: remove mh.mixins.vars!) pylint: disable-next=unused-import
+from ansible_collections.community.general.plugins.module_utils.mh.mixins.vars import VarsMixin, VarDict as _OldVarDict  # noqa: F401 remove in 11.0.0
 from ansible_collections.community.general.plugins.module_utils.mh.mixins.deprecate_attrs import DeprecateAttrsMixin
 
 
-class ModuleHelper(DeprecateAttrsMixin, VarsMixin, ModuleHelperBase):
+class ModuleHelper(DeprecateAttrsMixin, ModuleHelperBase):
     facts_name = None
     output_params = ()
     diff_params = ()
     change_params = ()
     facts_params = ()
+    use_old_vardict = True      # remove in 11.0.0
+    mute_vardict_deprecation = False
 
     def __init__(self, module=None):
-        super(ModuleHelper, self).__init__(module)
+        if self.use_old_vardict:  # remove first half of the if in 11.0.0
+            self.vars = _OldVarDict()
+            super(ModuleHelper, self).__init__(module)
+            if not self.mute_vardict_deprecation:
+                self.module.deprecate(
+                    "This class is using the old VarDict from ModuleHelper, which is deprecated. "
+                    "Set the class variable use_old_vardict to False and make the necessary adjustments."
+                    "The old VarDict class will be removed in community.general 11.0.0",
+                    version="11.0.0", collection_name="community.general"
+                )
+        else:
+            self.vars = _NewVarDict()
+            super(ModuleHelper, self).__init__(module)
+
         for name, value in self.module.params.items():
             self.vars.set(
                 name, value,
@@ -35,6 +53,12 @@ class ModuleHelper(DeprecateAttrsMixin, VarsMixin, ModuleHelperBase):
                 fact=name in self.facts_params,
             )
 
+    def update_vars(self, meta=None, **kwargs):
+        if meta is None:
+            meta = {}
+        for k, v in kwargs.items():
+            self.vars.set(k, v, **meta)
+
     def update_output(self, **kwargs):
         self.update_vars(meta={"output": True}, **kwargs)
 
@@ -42,7 +66,10 @@ class ModuleHelper(DeprecateAttrsMixin, VarsMixin, ModuleHelperBase):
         self.update_vars(meta={"fact": True}, **kwargs)
 
     def _vars_changed(self):
-        return any(self.vars.has_changed(v) for v in self.vars.change_vars())
+        if self.use_old_vardict:
+            return any(self.vars.has_changed(v) for v in self.vars.change_vars())
+
+        return self.vars.has_changed
 
     def has_changed(self):
         return self.changed or self._vars_changed()

plugins/modules/gconftool2.py

@@ -123,6 +123,7 @@ class GConftool(StateModuleHelper):
         ],
         supports_check_mode=True,
     )
+    use_old_vardict = False
 
     def __init_module__(self):
         self.runner = gconftool2_runner(self.module, check_rc=True)

plugins/modules/kernel_blacklist.py

@@ -67,6 +67,7 @@ class Blacklist(StateModuleHelper):
         ),
         supports_check_mode=True,
     )
+    mute_vardict_deprecation = True
 
     def __init_module__(self):
         self.pattern = re.compile(r'^blacklist\s+{0}$'.format(re.escape(self.vars.name)))

plugins/modules/opkg.py

@@ -127,6 +127,7 @@ class Opkg(StateModuleHelper):
             executable=dict(type="path"),
         ),
     )
+    use_old_vardict = False
 
     def __init_module__(self):
         self.vars.set("install_c", 0, output=False, change=True)

plugins/modules/pipx.py

@@ -201,6 +201,7 @@ class PipX(StateModuleHelper):
         ],
         supports_check_mode=True,
     )
+    use_old_vardict = False
 
     def _retrieve_installed(self):
         def process_list(rc, out, err):

plugins/modules/xfconf.py

@@ -187,6 +187,7 @@ class XFConfProperty(StateModuleHelper):
         required_together=[('value', 'value_type')],
         supports_check_mode=True,
     )
+    use_old_vardict = False
 
     default_state = 'present'
 
@@ -196,7 +197,7 @@ class XFConfProperty(StateModuleHelper):
                                                                                  self.vars.channel)
         self.vars.set('previous_value', self._get())
         self.vars.set('type', self.vars.value_type)
-        self.vars.meta('value').set(initial_value=self.vars.previous_value)
+        self.vars.set_meta('value', initial_value=self.vars.previous_value)
 
     def process_command_output(self, rc, out, err):
         if err.rstrip() == self.does_not:

plugins/modules/xfconf_info.py

@@ -139,6 +139,7 @@ class XFConfInfo(ModuleHelper):
         ),
         supports_check_mode=True,
     )
+    use_old_vardict = False
 
     def __init_module__(self):
         self.runner = xfconf_runner(self.module, check_rc=True)
@@ -176,7 +177,7 @@ class XFConfInfo(ModuleHelper):
             proc = self._process_list_properties
 
         with self.runner.context('list_arg channel property', output_process=proc) as ctx:
-            result = ctx.run(**self.vars)
+            result = ctx.run(**self.vars.as_dict())
 
         if not self.vars.list_arg and self.vars.is_array:
             output = "value_array"

tests/integration/targets/module_helper/library/mstate.py

@@ -49,6 +49,7 @@ class MState(StateModuleHelper):
             state=dict(type='str', choices=['join', 'b_x_a', 'c_x_a', 'both_x_a', 'nop'], default='join'),
         ),
     )
+    use_old_vardict = False
 
     def __init_module__(self):
         self.vars.set('result', "abc", diff=True)