Merge branch 'main' into update_fact_bracket

.pre-commit-config.yaml

@@ -36,11 +36,11 @@ repos:
         args: ["--filter-files"]
 
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.8.0
     hooks:
       - id: black
 
   - repo: https://github.com/pycqa/flake8
-    rev: 7.1.0
+    rev: 7.1.1
     hooks:
       - id: flake8

CHANGELOG.rst

@@ -4,6 +4,23 @@ Ansible Utils Collection Release Notes
 
 .. contents:: Topics
 
+v5.1.0
+======
+
+Minor Changes
+-------------
+
+- Allows the cli_parse module to find parser.template_path inside roles or collections when a path relative to the role/collection directory is provided.
+- Fix cli_parse module to require a connection.
+- Previously, the ansible.utils.ipcut filter only supported IPv6 addresses, leading to confusing error messages when used with IPv4 addresses. This fix ensures that the filter now appropriately handles both IPv4 and IPv6 addresses.
+- Removed conditional check for deprecated ansible.netcommon.cli_parse from ansible.utils.cli_parse
+- The from_xml filter returns a python dictionary instead of a json string.
+
+Documentation Changes
+---------------------
+
+- Add a wildcard mask/hostmask documentation to ipaddr filter doc page to obtain an IP address's wildcard mask/hostmask.
+
 v5.0.0
 ======
 

README.md

@@ -4,6 +4,19 @@
 
 The Ansible ``ansible.utils`` collection includes a variety of plugins that aid in the management, manipulation and visibility of data for the Ansible playbook developer.
 
+## Communication
+
+* Join the Ansible forum:
+  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others.
+  * [Posts tagged with 'network'](https://forum.ansible.com/tag/network): subscribe to participate in collection-related conversations.```
+  * [Ansible Network Automation Working Group](https://forum.ansible.com/g/network-wg/): by joining the team you will automatically get subscribed to the posts tagged with [network](https://forum.ansible.com/tags/network).
+  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+
+* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
+
+For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
+
 <!--start requires_ansible-->
 ## Ansible version compatibility
 

changelogs/changelog.yaml

@@ -442,9 +442,35 @@ releases:
         - Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions
           are EoL now.
       release_summary:
-        "With this release, the minimum required version of `ansible-core`
+        With this release, the minimum required version of `ansible-core`
         for this collection is `2.15.0`. The last version known to be compatible with
-        `ansible-core` versions below `2.15` is v4.1.0."
+        `ansible-core` versions below `2.15` is v4.1.0.
     fragments:
       - bump_215.yaml
     release_date: "2024-06-10"
+  5.1.0:
+    changes:
+      doc_changes:
+        - Add a wildcard mask/hostmask documentation to ipaddr filter doc page to obtain
+          an IP address's wildcard mask/hostmask.
+      minor_changes:
+        - Allows the cli_parse module to find parser.template_path inside roles or collections
+          when a path relative to the role/collection directory is provided.
+        - Fix cli_parse module to require a connection.
+        - Previously, the ansible.utils.ipcut filter only supported IPv6 addresses,
+          leading to confusing error messages when used with IPv4 addresses. This fix
+          ensures that the filter now appropriately handles both IPv4 and IPv6 addresses.
+        - Removed conditional check for deprecated ansible.netcommon.cli_parse from
+          ansible.utils.cli_parse
+        - The from_xml filter returns a python dictionary instead of a json string.
+    fragments:
+      - 200.yaml
+      - 203.yaml
+      - 204.yaml
+      - 324.yaml
+      - 358_ipcut.yaml
+      - add_template_path.yaml
+      - fix_cli_parse.yaml
+      - fix_from_xml.yaml
+      - todo_condition.yml
+    release_date: "2024-08-05"

changelogs/fragments/0-readme.yml

@@ -0,0 +1,3 @@
+---
+trivial:
+  - README.md - Add Communication section with Forum information.

galaxy.yml

@@ -19,4 +19,4 @@ tags:
   - data
   - validation
   - utils
-version: 5.0.0
+version: 5.1.0

plugins/filter/ipcut.py

@@ -105,10 +105,15 @@ def _ipcut(*args, **kwargs):
 
 
 def ipcut(value, amount):
-    ipv6_oct = []
     try:
         ip = netaddr.IPAddress(value)
-        ipv6address = ip.bits().replace(":", "")
+        if ip.version == 6:
+            ip_bits = ip.bits().replace(":", "")
+        elif ip.version == 4:
+            ip_bits = ip.bits().replace(".", "")
+        else:
+            msg = "Unknown IP Address Version: {0}".format(ip.version)
+            raise AnsibleFilterError(msg)
     except (netaddr.AddrFormatError, ValueError):
         msg = "You must pass a valid IP address; {0} is invalid".format(value)
         raise AnsibleFilterError(msg)
@@ -120,20 +125,27 @@ def ipcut(value, amount):
         raise AnsibleFilterError(msg)
     else:
         if amount < 0:
-            ipsub = ipv6address[amount:]
+            ipsub = ip_bits[amount:]
         else:
-            ipsub = ipv6address[0:amount]
-
-    ipsubfinal = []
-
-    for i in range(0, len(ipsub), 16):
-        oct_sub = i + 16
-        ipsubfinal.append(ipsub[i:oct_sub])
-
-    for i in ipsubfinal:
-        x = hex(int(i, 2))
-        ipv6_oct.append(x.replace("0x", ""))
-    return str(":".join(ipv6_oct))
+            ipsub = ip_bits[0:amount]
+
+    if ip.version == 6:
+        ipv4_oct = []
+        for i in range(0, len(ipsub), 16):
+            oct_sub = i + 16
+            ipv4_oct.append(
+                hex(int(ipsub[i:oct_sub], 2)).replace("0x", ""),
+            )
+        result = str(":".join(ipv4_oct))
+    else:  # ip.version == 4:
+        ipv4_oct = []
+        for i in range(0, len(ipsub), 8):
+            oct_sub = i + 8
+            ipv4_oct.append(
+                str(int(ipsub[i:oct_sub], 2)),
+            )
+        result = str(".".join(ipv4_oct))
+    return result
 
 
 class FilterModule(object):

plugins/filter/next_nth_usable.py

@@ -118,17 +118,23 @@ def next_nth_usable(value, offset):
     Returns the next nth usable ip within a network described by value.
     """
     try:
+        v = None
         vtype = ipaddr(value, "type")
         if vtype == "address":
             v = ipaddr(value, "cidr")
         elif vtype == "network":
             v = ipaddr(value, "subnet")
 
-        v = netaddr.IPNetwork(v)
+        if v is not None:
+            v = netaddr.IPNetwork(v)
+        else:
+            return False
     except Exception:
         return False
+
     if not isinstance(offset, int):
         raise AnsibleFilterError("Must pass in an integer")
+
     if v.size > 1:
         first_usable, last_usable = _first_last(v)
         nth_ip = int(netaddr.IPAddress(int(v.ip) + offset))

plugins/filter/previous_nth_usable.py

@@ -117,13 +117,18 @@ def previous_nth_usable(value, offset):
     Returns the previous nth usable ip within a network described by value.
     """
     try:
+        v = None
         vtype = ipaddr(value, "type")
         if vtype == "address":
             v = ipaddr(value, "cidr")
         elif vtype == "network":
             v = ipaddr(value, "subnet")
 
-        v = netaddr.IPNetwork(v)
+        if v is not None:
+            v = netaddr.IPNetwork(v)
+        else:
+            return False
+
     except Exception:
         return False
 

plugins/plugin_utils/from_xml.py

@@ -44,7 +44,7 @@ def from_xml(data, engine):
         if not HAS_XMLTODICT:
             _raise_error("Missing required library xmltodict")
         try:
-            res = xmltodict.parse(data)
+            res = xmltodict.parse(data, dict_constructor=dict)
         except Exception:
             _raise_error("Input Xml is not valid")
         return res

tests/integration/targets/utils_from_xml/tasks/simple.yaml

@@ -19,10 +19,12 @@
 
 - name: Integration tests with and without default engine as xmltodict and
   ansible.builtin.assert:
-    that: "{{ output == item.test }}"
+    that: "{{ output == test_item.test }}"
   loop:
     - test: "{{ data | ansible.utils.from_xml() }}"
     - test: "{{ data | ansible.utils.from_xml('xmltodict') }}"
+  loop_control:
+    loop_var: test_item
 
 - name: Setup invalid xml as input to ansible.utils.from_xml.
   ansible.builtin.set_fact: