version 1.1.0

- avoid mutation of desired_config in dict_diff function
- documentation
- repo updates

Author: Simon Kowallik

Makefile

@@ -46,8 +46,13 @@ isort:
 
 code-format: isort black ruff # more is MORE!
 
-test:
-	PYTHONPATH=$PWD cd ansible_collections/f5_ps_ansible/f5os && pytest tests/unit/plugins/module_utils/test_utils.py 
+doc: docs ## alias for docs
+
+docs:
+	python3 docs/f5os/ansible_module_autodoc.py
+
+pytests:
+	cd ansible_collections/f5_ps_ansible/f5os && PYTHONPATH=$(BASE_DIR) pytest tests/unit/plugins/module_utils/test_utils.py
 
 tests: test
 

ansible_collections/f5_ps_ansible/f5os/galaxy.yml

@@ -1,7 +1,7 @@
 ---
 namespace: f5_ps_ansible
 name: f5os
-version: 1.0.0
+version: 1.1.0
 readme: README.md
 authors:
 - Simon Kowallik <[email protected]>

ansible_collections/f5_ps_ansible/f5os/plugins/module_utils/utils.py

@@ -3,6 +3,8 @@
 # Copyright: Simon Kowallik for the F5 DevCentral Community
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+from copy import deepcopy
+
 from ansible.module_utils.connection import Connection
 
 
@@ -101,7 +103,7 @@ def dicts_equal(d1, d2, remove_keys=[]) -> bool:
     Values with integers and floats are compared as strings, hence the type is ignored.
     """
 
-    def _process_lists(d1, d2):
+    def _process_lists(_d1, _d2):
         def _sort_key(element):
             if isinstance(element, dict):
                 return (3, str(element))  # Assign a higher priority to dicts
@@ -114,68 +116,64 @@ def _sort_key(element):
             else:
                 return (4, str(element))  # Catch-all for other types
 
-        if len(d1) != len(d2):
+        if len(_d1) != len(_d2):
             return False
 
         # sort lists by type and value
-        _l1 = sorted(d1, key=_sort_key)
-        _l2 = sorted(d2, key=_sort_key)
+        _l1 = sorted(_d1, key=_sort_key)
+        _l2 = sorted(_d2, key=_sort_key)
 
-        for i in range(len(_l1)):
-            if isinstance(_l1[i], dict):
-                print(f"_l1[{i}] is dict")
-                if not dicts_equal(_l1[i], _l2[i]):
+        for i, item in enumerate(_l1):
+            if isinstance(item, dict):
+                if not dicts_equal(item, _l2[i]):
                     return False
-            elif isinstance(_l1[i], list):
-                print(f"_l1[{i}] is list")
-                if not _process_lists(_l1[i], _l2[i]):
+            elif isinstance(item, list):
+                if not _process_lists(item, _l2[i]):
                     return False
             else:
-                print(f"_l1[{i}] is other")
-                if str(_l1[i]) not in [
+                if str(item) not in [
                     str(entry) for entry in _l2 if not isinstance(entry, (list, dict))
                 ]:
                     return False
         return True
 
+    _d1 = deepcopy(d1)
+    _d2 = deepcopy(d2)
+
     if remove_keys:
-        d1 = recurse_remove_keys(d1, remove_keys)
-        d2 = recurse_remove_keys(d2, remove_keys)
+        _d1 = recurse_remove_keys(_d1, remove_keys)
+        _d2 = recurse_remove_keys(_d2, remove_keys)
 
     # simplest case: if the dictionaries are the same object, they are the same
-    if d1 == d2:
+    if _d1 == _d2:
         return True
 
     # If the types are different, the dictionaries are different
-    if type(d1) != type(d2):
+    if type(_d1) != type(_d2):
         return False
 
     # If the dictionaries are not the same length, they are different
-    if len(d1) != len(d2):
+    if len(_d1) != len(_d2):
         return False
 
     # If the dictionaries are empty, they are the same
-    if len(d1) == 0:
+    if len(_d1) == 0:
         return False
 
     # If the dictionaries are not empty, compare the keys
-    if set(d1) != set(d2):
+    if set(_d1) != set(_d2):
         return False
 
     # If the keys are the same, compare the values
-    for key in d1.keys():
-        print(f"key: {key}")
-        if isinstance(d1[key], dict):
-            print(f"{key} is dict")
-            if not dicts_equal(d1[key], d2[key]):
+    for key in _d1.keys():
+        if isinstance(_d1[key], dict):
+            if not dicts_equal(_d1[key], _d2[key]):
                 return False
-        elif isinstance(d1[key], list):
-            print(f"{key} is list")
-            if not _process_lists(d1[key], d2[key]):
+        elif isinstance(_d1[key], list):
+            if not _process_lists(_d1[key], _d2[key]):
                 return False
         else:
-            print(f"{key} is other")
-            if not str(d1[key]) == str(d2[key]):
+            if str(_d1[key]) != str(_d2[key]):
                 return False
 
     return True

ansible_collections/f5_ps_ansible/f5os/plugins/modules/f5os_restconf_config.py

@@ -61,7 +61,8 @@
 notes:
     - This module requires the f5networks.f5os collection to be installed on the ansible controller.
     - This module uses the httpapi of the f5networks.f5os collection.
-    - When using config_query the jmespath module is required.
+    - When using config_query jmespath module is required.
+    - For better diff support, deepdiff module is recommended.
 """
 
 EXAMPLES = r"""
@@ -94,11 +95,13 @@
     method: PATCH  # Use PATCH to partially update the configuration
     config:
       openconfig-lldp:config:
+        # the PATCH method will only update these keys:
         enabled: 'true'
         f5-lldp:max-neighbors-per-port: 50
-        # all missing keys of this entity need to be in keys_ignore,
-        # otherwise change detection will fail and ansible will always report a change
     keys_ignore:
+      # keys_ignore has all remaining keys of this API endpoint.
+      # The ansible module will therefore ignore the values in the
+      # below keys when comparing the desired and current configuration.
       - f5-lldp:reinit-delay
       - f5-lldp:tx-delay
       - f5-lldp:tx-hold

ansible_collections/f5_ps_ansible/f5os/tests/unit/plugins/module_utils/test_utils.py

@@ -183,10 +183,17 @@ def test_types(self, d1, d2, result):
              { "one": [ {"t": "1", "k": "a", "1": True}, [1, 3, 2, True, False], {"t": "2", "l": ["XXXX", 2, "c"]}, ], "list": [2, 1, 3,] },
             False),
         ])
+
     def test_deep(self, d1, d2, result):
         assert dicts_equal(d1, d2) == result
 
+    def test_mutation(self):
+        '''must not mutate input dictionaries'''
+        d1 = {"list": [{"key1": 1, "key2": 2}]}
+        d2 = {"list": [{"key2": 2}]}
 
+        assert dicts_equal(d1, d2, remove_keys=['key1']) == True
+        assert d1 == {"list": [{"key1": 1, "key2": 2}]}
 
 class Test_remove_state_property:
     TEST_NTP = [