Fix dnf/dnf5 documentation for exclude parameter (#87034)

* Sanity fix
* Test dnf `exclude` parameter


Co-authored-by: Patrick Kingston <pkingsto@redhat.com>

changelogs/fragments/87026-clarify-dnf-exclude-docs.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - dnf - clarify that the ``exclude`` parameter works with all ``state`` values, not just ``present`` and ``latest`` (https://github.com/ansible/ansible/issues/87026)
+  - dnf5 - clarify that the ``exclude`` parameter works with all ``state`` values, not just ``present`` and ``latest`` (https://github.com/ansible/ansible/issues/87026)

lib/ansible/modules/dnf.py

@@ -117,8 +117,8 @@ options:
     version_added: "2.4"
   exclude:
     description:
-      - Package name(s) to exclude when O(state=present), or latest. This can be a
-        list or a comma separated string.
+      - Package name(s) to exclude from the operation. This can be a list or a comma separated string.
+      - Works with all O(state) values, including V(absent), V(present), and V(latest).
     version_added: "2.7"
     type: list
     elements: str

lib/ansible/modules/dnf5.py

@@ -95,8 +95,8 @@ options:
     default: "no"
   exclude:
     description:
-      - Package name(s) to exclude when O(state=present) or O(state=latest). This can be a
-        list or a comma separated string.
+      - Package name(s) to exclude from the operation. This can be a list or a comma separated string.
+      - Works with all O(state) values, including V(absent), V(present), and V(latest).
     type: list
     elements: str
     default: []

test/integration/targets/dnf/tasks/exclude.yml

@@ -0,0 +1,69 @@
+- name: Test `exclude`
+  block:
+  - name: Ensure no lsof
+    dnf:
+      name: lsof
+      state: removed
+
+  - name: Try installing lsof latest with exclude
+    dnf:
+      name: lsof
+      state: latest
+      exclude: ls*
+    register: latest_excluded
+    ignore_errors: true
+
+  - name: Try installing lsof present with exclude
+    dnf:
+      name: lsof
+      state: present
+      exclude: lsof
+    register: present_excluded
+    ignore_errors: true
+
+  - name: Install lsof present with non-matching exclude
+    dnf:
+      name: lsof
+      state: present
+      exclude: neovim
+    register: present_non_matching_exclude
+
+  - name: Try removing lsof with matching exclude
+    dnf:
+      name: lsof
+      state: absent
+      exclude: lsof
+    register: absent_excluded
+    ignore_errors: true
+
+  - name: Try removing lsof with non-matching exclude
+    dnf:
+      name: lsof
+      state: absent
+      exclude: neovim
+    register: absent_non_matching_exclude
+
+  - name: Assert correct exclude behavior (dnf5)
+    assert:
+      that:
+        - latest_excluded is failed
+        - present_excluded is failed
+        - present_non_matching_exclude is changed
+        - absent_excluded is not changed
+        - absent_non_matching_exclude is changed
+    when: dnf5
+
+  - name: Assert correct exclude behavior (dnf4)
+    assert:
+      that:
+        - latest_excluded is not changed
+        - present_excluded is not changed
+        - present_non_matching_exclude is changed
+        - absent_excluded is not changed
+        - absent_non_matching_exclude is changed
+    when: not dnf5
+  always:
+    - name: Ensure no lsof
+      dnf:
+        name: lsof
+        state: absent

test/integration/targets/dnf/tasks/main.yml

@@ -44,6 +44,7 @@
     - include_tasks: cacheonly.yml
     - include_tasks: multilib.yml
     - include_tasks: dnf_config.yml
+    - include_tasks: exclude.yml
 
 # Attempting to install a different RHEL release in a tmpdir doesn't work (rhel8 beta)
 - include_tasks: dnfreleasever.yml