dcnm_fabric (Ready for review)

plugins/module_utils/common/conversion.py

@@ -0,0 +1,173 @@
+# Copyright (c) 2024 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+__author__ = "Allen Robel"
+
+import inspect
+import re
+
+
+class ConversionUtils:
+    """
+    Utility methods for converting, translating, and validating values.
+
+    - bgp_asn_is_valid: Return True if value is a valid BGP ASN, False otherwise.
+    - make_boolean: Return value converted to boolean, if possible.
+    - make_int: Return value converted to int, if possible.
+    - make_none: Return None if value is a string representation of a None type.
+    - reject_boolean_string: Reject quoted boolean values e.g. "False", "true"
+    - translate_mac_address: Convert mac address to dotted-quad format expected by the controller.
+    - validate_fabric_name: Validate the fabric name meets the requirements of the controller.
+    """
+
+    def __init__(self):
+        self.class_name = self.__class__.__name__
+
+        re_asn_str = "^(((\\+)?[1-9]{1}[0-9]{0,8}|(\\+)?[1-3]{1}[0-9]{1,9}|(\\+)?[4]"
+        re_asn_str += "{1}([0-1]{1}[0-9]{8}|[2]{1}([0-8]{1}[0-9]{7}|[9]{1}([0-3]{1}"
+        re_asn_str += "[0-9]{6}|[4]{1}([0-8]{1}[0-9]{5}|[9]{1}([0-5]{1}[0-9]{4}|[6]"
+        re_asn_str += "{1}([0-6]{1}[0-9]{3}|[7]{1}([0-1]{1}[0-9]{2}|[2]{1}([0-8]{1}"
+        re_asn_str += "[0-9]{1}|[9]{1}[0-5]{1})))))))))|([1-5]\\d{4}|[1-9]\\d{0,3}|6"
+        re_asn_str += "[0-4]\\d{3}|65[0-4]\\d{2}|655[0-2]\\d|6553[0-5])"
+        re_asn_str += "(\\.([1-5]\\d{4}|[1-9]\\d{0,3}|6[0-4]\\d{3}|65[0-4]"
+        re_asn_str += "\\d{2}|655[0-2]\\d|6553[0-5]|0))?)$"
+        self.re_asn = re.compile(re_asn_str)
+        self.re_valid_fabric_name = re.compile(r"[a-zA-Z]+[a-zA-Z0-9_-]*")
+
+        self.bgp_as_invalid_reason = None
+
+    def bgp_as_is_valid(self, value):
+        """
+        -   Return True if value is a valid BGP ASN.
+        -   Return False, otherwise.
+        -   Set ConversionUtils().bgp_as_invalid_reason to a string with the
+            reason why the value is not a valid BGP ASN.
+
+        Usage example:
+
+        ```python
+        conversion = ConversionUtils()
+        if not conversion.bgp_as_is_valid(value):
+            print(conversion.bgp_as_invalid_reason)
+        ```
+        """
+        if isinstance(value, float):
+            msg = f"BGP ASN ({value}) cannot be type float() due to "
+            msg += "loss of trailing zeros. "
+            msg += "Use a string or integer instead."
+            self.bgp_as_invalid_reason = msg
+            return False
+        try:
+            asn = str(value)
+        except UnicodeEncodeError:
+            msg = f"BGP ASN ({value}) could not be converted to a string."
+            self.bgp_as_invalid_reason = msg
+            return False
+        if not self.re_asn.match(asn):
+            msg = f"BGP ASN {value} failed regex validation."
+            self.bgp_as_invalid_reason = msg
+            return False
+        return True
+
+    @staticmethod
+    def make_boolean(value):
+        """
+        - Return value converted to boolean, if possible.
+        - Return value, otherwise.
+        """
+        if str(value).lower() in ["true", "yes"]:
+            return True
+        if str(value).lower() in ["false", "no"]:
+            return False
+        return value
+
+    @staticmethod
+    def make_int(value):
+        """
+        - Return value converted to int, if possible.
+        - Return value, otherwise.
+        """
+        # Don't convert boolean values to integers
+        if isinstance(value, bool):
+            return value
+        try:
+            return int(value)
+        except (ValueError, TypeError):
+            return value
+
+    @staticmethod
+    def make_none(value):
+        """
+        - Return None if value is a string representation of a None type
+        - Return value, otherwise.
+        """
+        if str(value).lower() in {"", "none", "null"}:
+            return None
+        return value
+
+    @staticmethod
+    def reject_boolean_string(parameter, value) -> None:
+        """
+        -   Reject quoted boolean values e.g. "False", "true"
+        -   Raise ``ValueError`` with informative message if the value is
+            a string representation of a boolean.
+        """
+        if isinstance(value, int):
+            return
+        if isinstance(value, bool):
+            return
+        if str(value).lower() in ["true", "false"]:
+            msg = f"Parameter {parameter}, value '{value}', "
+            msg += "is a quoted string representation of a boolean. "
+            msg += "Please remove the quotes and try again "
+            msg += "(e.g. True/False or true/false, instead of "
+            msg += "'True'/'False' or 'true'/'false')."
+            raise ValueError(msg)
+
+    @staticmethod
+    def translate_mac_address(mac_addr):
+        """
+        -   Accept mac address with any (or no) punctuation and convert it
+            into the dotted-quad format that the controller expects.
+        -   On success, return translated mac address.
+        -   On failure, raise ``ValueError``.
+        """
+        mac_addr = re.sub(r"[\W\s_]", "", mac_addr)
+        if not re.search("^[A-Fa-f0-9]{12}$", mac_addr):
+            raise ValueError(f"Invalid MAC address: {mac_addr}")
+        return "".join((mac_addr[:4], ".", mac_addr[4:8], ".", mac_addr[8:]))
+
+    def validate_fabric_name(self, value):
+        """
+        -   Validate the fabric name meets the requirements of the controller.
+        -   Raise ``TypeError`` if value is not a string.
+        -   Raise ``ValueError`` if value does not meet the requirements.
+        """
+        method_name = inspect.stack()[0][3]  # pylint: disable=unused-variable
+
+        if not isinstance(value, str):
+            msg = f"{self.class_name}.{method_name}: "
+            msg += f"Invalid fabric name. Expected string. Got {value}."
+            raise TypeError(msg)
+
+        if re.fullmatch(self.re_valid_fabric_name, value) is not None:
+            return
+        msg = f"{self.class_name}.{method_name}: "
+        msg += f"Invalid fabric name: {value}. "
+        msg += "Fabric name must start with a letter A-Z or a-z and "
+        msg += "contain only the characters in: [A-Z,a-z,0-9,-,_]."
+        raise ValueError(msg)

plugins/module_utils/common/exceptions.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2024 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+__author__ = "Allen Robel"
+
+
+class ControllerResponseError(Exception):
+    pass

plugins/module_utils/common/params_validate.py

@@ -326,7 +326,7 @@ def _ipaddress_guard(self, expected_type, value: Any, param: str) -> None:
 
         The ipaddress module accepts int and bool types and converts
         them to IP addresses or networks.  E.g. True becomes 0.0.0.1,
-        False becomes 0.0.0.0, 1 becomse 0.0.0.1, etc.  Because of
+        False becomes 0.0.0.0, 1 becomes 0.0.0.1, etc.  Because of
         this, we need to fail int and bool values if expected_type is
         one of ipv4, ipv6, ipv4_subnet, or ipv6_subnet.
         """

plugins/module_utils/common/results.py

@@ -39,13 +39,13 @@ class Results:
         -   Typically done by transferring RestSend's responses to the
             Results instance
     3. Register the results of the task with Results, using:
-        -   Results.register_task_results()
+        -   Results.register_task_result()
         -   Typically done after the task is complete
 
     Results should be instantiated in the main Ansible Task class and passed
     to all other task classes.  The task classes should populate the Results
     instance with the results of the task and then register the results with
-    Results.register_task_results().  This may be done within a separate class
+    Results.register_task_result().  This may be done within a separate class
     (as in the example below, where FabricDelete() class is called from the
     TaskDelete() class.  The Results instance can then be used to build the
     final result, by calling Results.build_final_result().
@@ -95,7 +95,7 @@ def commit(self):
             ...
             self.fabric_delete.fabric_names = ["FABRIC_1", "FABRIC_2"]
             self.fabric_delete.results = self.results
-            # results.register_task_results() is called within the
+            # results.register_task_result() is called within the
             # commit() method of the FabricDelete class.
             self.fabric_delete.commit()
 
@@ -221,6 +221,7 @@ def did_anything_change(self) -> bool:
         msg += f"self.result_current: {self.result_current}, "
         msg += f"self.diff: {self.diff}"
         self.log.debug(msg)
+
         if self.check_mode is True:
             return False
         if self.action == "query":
@@ -232,9 +233,13 @@ def did_anything_change(self) -> bool:
             return True
         if self.result_current.get("changed", None) is False:
             return False
-        if len(self.diff) != 0:
-            return True
-        return False
+        for diff in self.diff:
+            something_changed = False
+            test_diff = copy.deepcopy(diff)
+            test_diff.pop("sequence_number", None)
+            if len(test_diff) != 0:
+                something_changed = True
+        return something_changed
 
     def register_task_result(self):
         """