[PR #6511/486f6553 backport][stable-7] VarDict module utils (#6594)

VarDict module utils (#6511)

* vardict: easy hadling of module variables

* fix copyright year

* initial tests passing

* small adjustments

* add tests

* add to BOTMETA

* remove unused import pytest

* Update plugins/module_utils/vardict.py

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

* minor refactor and documentation

* minor adjustments

* rename VarDict.var() to VarDict._var()

- plus add more docs

* fix method name in tests

---------

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

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

tests/unit/plugins/module_utils/test_vardict.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+# (c) 2023, Alexei Znamensky <russoz@gmail.com>
+# Copyright (c) 2023 Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+from ansible_collections.community.general.plugins.module_utils.vardict import VarDict
+
+
+def test_var_simple():
+    vd = VarDict()
+    vd["a"] = 123
+
+    var = vd._var("a")
+    assert var.output is True
+    assert var.diff is False
+    assert var.change is False
+    assert var.fact is False
+    assert var.initial_value == 123
+    assert var.value == 123
+
+    vd.a = 456
+    assert var.output is True
+    assert var.diff is False
+    assert var.change is False
+    assert var.fact is False
+    assert var.initial_value == 123
+    assert var.value == 456
+
+
+def test_var_diff_scalar():
+    vd = VarDict()
+    vd.set("aa", 123, diff=True)
+
+    var = vd._var("aa")
+    assert var.output is True
+    assert var.diff is True
+    assert var.change is True
+    assert var.fact is False
+    assert var.initial_value == 123
+    assert var.value == 123
+    assert vd.diff() is None
+
+    vd.aa = 456
+    assert var.output is True
+    assert var.diff is True
+    assert var.change is True
+    assert var.fact is False
+    assert var.initial_value == 123
+    assert var.value == 456
+    assert vd.diff() == {"before": {"aa": 123}, "after": {"aa": 456}}, "actual={0}".format(vd.diff())
+
+
+def test_var_diff_dict():
+    val_before = dict(x=0, y=10, z=10)
+    val_after = dict(x=0, y=30, z=10)
+
+    vd = VarDict()
+    vd.set("dd", val_before, diff=True)
+
+    var = vd._var("dd")
+    assert var.output is True
+    assert var.diff is True
+    assert var.change is True
+    assert var.fact is False
+    assert var.initial_value == val_before
+    assert var.value == val_before
+    assert vd.diff() is None
+
+    vd.dd = val_after
+    assert var.output is True
+    assert var.diff is True
+    assert var.change is True
+    assert var.fact is False
+    assert var.initial_value == val_before
+    assert var.value == val_after
+    assert vd.diff() == {"before": {"dd": val_before}, "after": {"dd": val_after}}, "actual={0}".format(vd.diff())
+
+    vd.set("aa", 123, diff=True)
+    vd.aa = 456
+    assert vd.diff() == {"before": {"aa": 123, "dd": val_before}, "after": {"aa": 456, "dd": val_after}}, "actual={0}".format(vd.diff())
+
+
+def test_vardict_set_meta():
+    vd = VarDict()
+    vd["jj"] = 123
+
+    var = vd._var("jj")
+    assert var.output is True
+    assert var.diff is False
+    assert var.change is False
+    assert var.fact is False
+    assert var.initial_value == 123
+    assert var.value == 123
+
+    vd.set_meta("jj", diff=True)
+    assert var.diff is True
+    assert var.change is True
+
+    vd.set_meta("jj", diff=False)
+    assert var.diff is False
+    assert var.change is False
+
+    vd.set_meta("jj", change=False)
+    vd.set_meta("jj", diff=True)
+    assert var.diff is True
+    assert var.change is False
+
+
+def test_vardict_change():
+    vd = VarDict()
+    vd.set("xx", 123, change=True)
+    vd.set("yy", 456, change=True)
+    vd.set("zz", 789, change=True)
+
+    vd.xx = 123
+    vd.yy = 456
+    assert vd.has_changed is False
+    vd.xx = 12345
+    assert vd.has_changed is True