ModuleHelper variables management (#2162) (#2178)

* added metadata for variables in module helper

* adjustments

* added separate support for tracking changes

* rewrote the diff code

* added integration test for module_helper

* using ansible.module_utils.common.dict_transformations.dict_merge

* improved dependency management

* restore ModuleHelper to base classes of CmdStateModuleHelper

* added assertions to ensure the failing module name appears in the error messages

* added test code for state-based modules

* fixed test name

* renamed class to VarMeta

* small fixes

* fixes from the PR

* fixed VarDict.__set_attr__

* added VarDict.__getitem__()

* added changelog fragment

* adjustments per PR

* ModuleHelper.output is now aware of conflicting variable names

* Update plugins/module_utils/module_helper.py

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit d2070277e8)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

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

@@ -0,0 +1,69 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# (c) 2021, Alexei Znamensky <russoz@gmail.com>
+#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+module: mdepfail
+author: "Alexei Znamensky (@russoz)"
+short_description: Simple module for testing
+description:
+  - Simple module test description.
+options:
+  a:
+    description: aaaa
+    type: int
+  b:
+    description: bbbb
+    type: str
+  c:
+    description: cccc
+    type: str
+'''
+
+EXAMPLES = ""
+
+RETURN = ""
+
+from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
+from ansible.module_utils.basic import missing_required_lib
+
+with ModuleHelper.dependency("nopackagewiththisname", missing_required_lib("nopackagewiththisname")):
+    import nopackagewiththisname
+
+
+class MSimple(ModuleHelper):
+    output_params = ('a', 'b', 'c')
+    module = dict(
+        argument_spec=dict(
+            a=dict(type='int'),
+            b=dict(type='str'),
+            c=dict(type='str'),
+        ),
+    )
+
+    def __init_module__(self):
+        self.vars.set('value', None)
+        self.vars.set('abc', "abc", diff=True)
+
+    def __run__(self):
+        if (0 if self.vars.a is None else self.vars.a) >= 100:
+            raise Exception("a >= 100")
+        if self.vars.c == "abc change":
+            self.vars['abc'] = "changed abc"
+        if self.vars.get('a', 0) == 2:
+            self.vars['b'] = str(self.vars.b) * 2
+            self.vars['c'] = str(self.vars.c) * 2
+
+
+def main():
+    msimple = MSimple()
+    msimple.run()
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,65 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# (c) 2021, Alexei Znamensky <russoz@gmail.com>
+#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+module: msimple
+author: "Alexei Znamensky (@russoz)"
+short_description: Simple module for testing
+description:
+  - Simple module test description.
+options:
+  a:
+    description: aaaa
+    type: int
+  b:
+    description: bbbb
+    type: str
+  c:
+    description: cccc
+    type: str
+'''
+
+EXAMPLES = ""
+
+RETURN = ""
+
+from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
+
+
+class MSimple(ModuleHelper):
+    output_params = ('a', 'b', 'c')
+    module = dict(
+        argument_spec=dict(
+            a=dict(type='int'),
+            b=dict(type='str'),
+            c=dict(type='str'),
+        ),
+    )
+
+    def __init_module__(self):
+        self.vars.set('value', None)
+        self.vars.set('abc', "abc", diff=True)
+
+    def __run__(self):
+        if (0 if self.vars.a is None else self.vars.a) >= 100:
+            raise Exception("a >= 100")
+        if self.vars.c == "abc change":
+            self.vars['abc'] = "changed abc"
+        if self.vars.get('a', 0) == 2:
+            self.vars['b'] = str(self.vars.b) * 2
+            self.vars['c'] = str(self.vars.c) * 2
+
+
+def main():
+    msimple = MSimple()
+    msimple.run()
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,77 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# (c) 2021, Alexei Znamensky <russoz@gmail.com>
+#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+module: mstate
+author: "Alexei Znamensky (@russoz)"
+short_description: State-based module for testing
+description:
+  - State-based module test description.
+options:
+  a:
+    description: aaaa
+    type: int
+    required: yes
+  b:
+    description: bbbb
+    type: str
+  c:
+    description: cccc
+    type: str
+  state:
+    description: test states
+    type: str
+    choices: [join, b_x_a, c_x_a, both_x_a]
+    default: join
+'''
+
+EXAMPLES = ""
+
+RETURN = ""
+
+from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
+
+
+class MState(StateModuleHelper):
+    output_params = ('a', 'b', 'c', 'state')
+    module = dict(
+        argument_spec=dict(
+            a=dict(type='int', required=True),
+            b=dict(type='str'),
+            c=dict(type='str'),
+            state=dict(type='str', choices=['join', 'b_x_a', 'c_x_a', 'both_x_a', 'nop'], default='join'),
+        ),
+    )
+
+    def __init_module__(self):
+        self.vars.set('result', "abc", diff=True)
+
+    def state_join(self):
+        self.vars['result'] = "".join([str(self.vars.a), str(self.vars.b), str(self.vars.c)])
+
+    def state_b_x_a(self):
+        self.vars['result'] = str(self.vars.b) * self.vars.a
+
+    def state_c_x_a(self):
+        self.vars['result'] = str(self.vars.c) * self.vars.a
+
+    def state_both_x_a(self):
+        self.vars['result'] = (str(self.vars.b) + str(self.vars.c)) * self.vars.a
+
+    def state_nop(self):
+        pass
+
+
+def main():
+    mstate = MState()
+    mstate.run()
+
+
+if __name__ == '__main__':
+    main()