filetree lookup: document RETURN value state (#11997)

* Clarify 'state' parameter description in filetree.py

Updated the description for the 'state' parameter to clarify entry types and their meanings.

* Apply suggestion from felixfontein related to description

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

---------

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

.azure-pipelines/azure-pipelines.yml

@@ -96,19 +96,6 @@ stages:
             - test: 2
             - test: 3
             - test: 4
-  - stage: Sanity_2_18
-    displayName: Sanity 2.18
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          nameFormat: Test {0}
-          testFormat: 2.18/sanity/{0}
-          targets:
-            - test: 1
-            - test: 2
-            - test: 3
-            - test: 4
 ### Units
   - stage: Units_2_21
     displayName: Units 2.21
@@ -149,18 +136,6 @@ stages:
             - test: 3.8
             - test: "3.11"
             - test: "3.13"
-  - stage: Units_2_18
-    displayName: Units 2.18
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          nameFormat: Python {0}
-          testFormat: 2.18/units/{0}/1
-          targets:
-            - test: 3.8
-            - test: "3.11"
-            - test: "3.13"
 
 ## Remote
   - stage: Remote_2_21_extra_vms
@@ -239,22 +214,6 @@ stages:
             - 1
             - 2
             - 3
-  - stage: Remote_2_18
-    displayName: Remote 2.18
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.18/{0}
-          targets:
-            # - name: macOS 14.3
-            #   test: macos/14.3
-            - name: FreeBSD 14.1
-              test: freebsd/14.1
-          groups:
-            - 1
-            - 2
-            - 3
 
 ### Docker
   - stage: Docker_2_21
@@ -309,24 +268,6 @@ stages:
             - 1
             - 2
             - 3
-  - stage: Docker_2_18
-    displayName: Docker 2.18
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.18/linux/{0}
-          targets:
-            - name: Fedora 40
-              test: fedora40
-            - name: Alpine 3.20
-              test: alpine320
-            - name: Ubuntu 24.04
-              test: ubuntu2404
-          groups:
-            - 1
-            - 2
-            - 3
 
 ### Community Docker
   - stage: Docker_community_2_21
@@ -385,17 +326,6 @@ stages:
 #          testFormat: 2.19/generic/{0}/1
 #          targets:
 #            - test: '3.9'
-#            - test: '3.13'
-#  - stage: Generic_2_18
-#    displayName: Generic 2.18
-#    dependsOn: []
-#    jobs:
-#      - template: templates/matrix.yml
-#        parameters:
-#          nameFormat: Python {0}
-#          testFormat: 2.18/generic/{0}/1
-#          targets:
-#            - test: '3.8'
 #            - test: '3.13'
 
   - stage: Summary
@@ -404,25 +334,20 @@ stages:
       - Sanity_2_21
       - Sanity_2_20
       - Sanity_2_19
-      - Sanity_2_18
       - Units_2_21
       - Units_2_20
       - Units_2_19
-      - Units_2_18
       - Remote_2_21_extra_vms
       - Remote_2_21
       - Remote_2_20
       - Remote_2_19
-      - Remote_2_18
       - Docker_2_21
       - Docker_2_20
       - Docker_2_19
-      - Docker_2_18
       - Docker_community_2_21
 # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled.
 #      - Generic_2_21
 #      - Generic_2_20
 #      - Generic_2_19
-#      - Generic_2_18
     jobs:
       - template: templates/coverage.yml

.github/workflows/ansible-test.yml

@@ -31,6 +31,7 @@ jobs:
         ansible:
           - '2.16'
           - '2.17'
+          - '2.18'
     runs-on: ubuntu-latest
     steps:
       - name: Perform sanity testing
@@ -70,6 +71,12 @@ jobs:
             python: '3.10'
           - ansible: '2.17'
             python: '3.12'
+          - ansible: '2.18'
+            python: '3.8'
+          - ansible: '2.18'
+            python: '3.11'
+          - ansible: '2.18'
+            python: '3.13'
 
     steps:
       - name: >-
@@ -180,6 +187,43 @@ jobs:
             docker: ubuntu2004
             python: ''
             target: azp/posix/3/
+          # 2.18
+          - ansible: '2.18'
+            docker: fedora40
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.18'
+            docker: fedora40
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.18'
+            docker: fedora40
+            python: ''
+            target: azp/posix/3/
+          - ansible: '2.18'
+            docker: ubuntu2404
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.18'
+            docker: ubuntu2404
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.18'
+            docker: ubuntu2404
+            python: ''
+            target: azp/posix/3/
+          - ansible: '2.18'
+            docker: alpine320
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.18'
+            docker: alpine320
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.18'
+            docker: alpine320
+            python: ''
+            target: azp/posix/3/
 
     steps:
       - name: >-

changelogs/fragments/11.4.8.yml

@@ -0,0 +1 @@
+release_summary: Bugfix release.

changelogs/fragments/11909-fix-favicon-url.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "mattermost, rocketchat, slack - update default ``icon_url`` to ansible favicon (https://github.com/ansible-collections/community.general/pull/11909)."

changelogs/fragments/11959-xml-boolean-value.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - "xml - emit an error when ``value`` is not a string, pointing to the offending xpath
+    (https://github.com/ansible-collections/community.general/issues/7171,
+    https://github.com/ansible-collections/community.general/pull/11959)."

changelogs/fragments/11972-odbc-fix-commit-fetch-order.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - odbc - fetch rows before committing to fix ``HY010`` function sequence error (https://github.com/ansible-collections/community.general/issues/5395, https://github.com/ansible-collections/community.general/pull/11972).

galaxy.yml

@@ -5,7 +5,7 @@
 
 namespace: community
 name: general
-version: 11.4.7
+version: 11.4.8
 readme: README.md
 authors:
   - Ansible (https://github.com/ansible)

plugins/connection/saltstack.py

@@ -14,7 +14,29 @@ author: Michael Scherer (@mscherer) <misc@zarb.org>
 name: saltstack
 short_description: Allow ansible to piggyback on salt minions
 description:
-  - This allows you to use existing Saltstack infrastructure to connect to targets.
+  - Run commands or put/fetch files to Salt minions by using the local Salt master as transport.
+  - Ansible must run directly on the Salt master; this plugin uses C(salt.client.LocalClient)
+    and does not support connecting to a remote Salt master.
+requirements:
+  - the C(salt) Python package must be installed on the Salt master (the Ansible controller)
+options:
+  remote_addr:
+    description:
+      - The Salt minion ID to target.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+notes:
+  - Ansible must be run from the Salt master host; the plugin cannot reach a remote Salt master.
+  - The inventory hostname (or O(remote_addr)) is treated as the Salt minion ID, not as a DNS
+    name or IP address.
+  - The Salt master and its minion keys must already be configured and accepted before using
+    this connection plugin.
+  - File transfer via P(community.general.saltstack#connection) uses C(hashutil.base64_decodefile)
+    (put) and C(cp.get_file_str) (fetch); these Salt execution modules must be available on
+    the targeted minions.
 """
 
 import os

plugins/lookup/filetree.py

@@ -80,8 +80,12 @@ _raw:
       description: The permissions the resulting file or directory.
       type: str
     state:
-      description: TODO.
+      description:
+        - Type of the resulting file or directory.
+        - V(directory) for a directory, V(file) for a regular file, V(link) for a symbolic link.
+        - Other file types are skipped and not returned.
       type: str
+      choices: [directory, file, link]
     owner:
       description: Name of the user that owns the file/directory.
       type: raw

plugins/lookup/lmdb_kv.py

@@ -15,7 +15,7 @@ short_description: Fetch data from LMDB
 description:
   - This lookup returns a list of results from an LMDB DB corresponding to a list of items given to it.
 requirements:
-  - lmdb (Python library U(https://lmdb.readthedocs.io/en/release/))
+  - lmdb (Python library U(https://lmdb.readthedocs.io/en/latest/))
 options:
   _terms:
     description: List of keys to query.
@@ -46,8 +46,8 @@ EXAMPLES = r"""
   ansible.builtin.assert:
     that:
       - item == 'Belgium'
-    vars:
-      - lmdb_kv_db: jp.mdb
+  vars:
+    - lmdb_kv_db: jp.mdb
   with_community.general.lmdb_kv:
     - be
 """

plugins/modules/iso_customize.py

@@ -68,7 +68,6 @@ options:
         type: str
         required: true
 notes:
-  - The C(pycdlib) library states it supports Python 2.7 and 3.4+.
   - The function C(add_file) in pycdlib is designed to overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12
     / Joliet / UDF. But it does not overwrite the existing file in ISO with Rock Ridge 1.09 / 1.10. So we take workaround
     "delete the existing file and then add file for ISO with Rock Ridge".

plugins/modules/mattermost.py

@@ -66,7 +66,7 @@ options:
     type: str
     description:
       - URL for the message sender's icon.
-    default: https://docs.ansible.com/favicon.ico
+    default: https://docs.ansible.com/favicon/favicon.ico
   priority:
     type: str
     description:
@@ -139,7 +139,7 @@ def main():
             text=dict(type='str'),
             channel=dict(type='str'),
             username=dict(type='str', default='Ansible'),
-            icon_url=dict(type='str', default='https://docs.ansible.com/favicon.ico'),
+            icon_url=dict(type='str', default='https://docs.ansible.com/favicon/favicon.ico'),
             priority=dict(type='str', choices=['important', 'urgent']),
             validate_certs=dict(default=True, type='bool'),
             attachments=dict(type='list', elements='dict'),

plugins/modules/odbc.py

@@ -134,8 +134,6 @@ def main():
             cursor.execute(query, params)
         else:
             cursor.execute(query)
-        if commit:
-            cursor.commit()
         try:
             # Get the rows out into an 2d array
             for row in cursor.fetchall():
@@ -162,6 +160,8 @@ def main():
         except Exception as e:
             module.fail_json(msg="Exception while reading rows: {0}".format(to_native(e)))
 
+        if commit:
+            cursor.commit()
         cursor.close()
     except Exception as e:
         module.fail_json(msg="Failed to execute query: {0}".format(to_native(e)))

plugins/modules/ohai.py

@@ -31,6 +31,8 @@ author:
 """
 
 EXAMPLES = r"""
+# fmt: console
+
 ansible webservers -m ohai --tree=/tmp/ohaidata
 ...
 """

plugins/modules/packet_volume_attachment.py

@@ -86,7 +86,7 @@ EXAMPLES = r"""
 
   tasks:
     - name: Create volume
-      packet_volume:
+      community.general.packet_volume:
         description: "{{ volname }}"
         project_id: "{{ project_id }}"
         facility: ewr1
@@ -98,7 +98,7 @@ EXAMPLES = r"""
           snapshot_frequency: 1day
 
     - name: Create a device
-      packet_device:
+      community.general.packet_device:
         project_id: "{{ project_id }}"
         hostnames: "{{ devname }}"
         operating_system: ubuntu_16_04

plugins/modules/rocketchat.py

@@ -63,7 +63,7 @@ options:
     type: str
     description:
       - URL for the message sender's icon.
-    default: "https://docs.ansible.com/favicon.ico"
+    default: "https://docs.ansible.com/favicon/favicon.ico"
   icon_emoji:
     type: str
     description:
@@ -226,7 +226,7 @@ def main():
             msg=dict(type='str'),
             channel=dict(type='str'),
             username=dict(type='str', default='Ansible'),
-            icon_url=dict(type='str', default='https://docs.ansible.com/favicon.ico'),
+            icon_url=dict(type='str', default='https://docs.ansible.com/favicon/favicon.ico'),
             icon_emoji=dict(type='str'),
             link_names=dict(type='int', default=1, choices=[0, 1]),
             validate_certs=dict(default=True, type='bool'),

plugins/modules/slack.py

@@ -87,7 +87,7 @@ options:
     type: str
     description:
       - URL for the message sender's icon.
-    default: https://docs.ansible.com/favicon.ico
+    default: https://docs.ansible.com/favicon/favicon.ico
   icon_emoji:
     type: str
     description:
@@ -457,7 +457,7 @@ def main():
             channel=dict(type='str'),
             thread_id=dict(type='str'),
             username=dict(type='str', default='Ansible'),
-            icon_url=dict(type='str', default='https://docs.ansible.com/favicon.ico'),
+            icon_url=dict(type='str', default='https://docs.ansible.com/favicon/favicon.ico'),
             icon_emoji=dict(type='str'),
             link_names=dict(type='int', default=1, choices=[0, 1]),
             parse=dict(type='str', choices=['none', 'full']),

plugins/modules/xml.py

@@ -689,6 +689,16 @@ def set_target_inner(module, tree, xpath, namespaces, attribute, value):
         module.fail_json(msg="Xpath %s does not reference a node! tree is %s" %
                              (xpath, etree.tostring(tree, pretty_print=True)))
 
+    if not isinstance(value, str):
+        target = ("attribute '{attribute}' at xpath '{xpath}'" if attribute else "element text at xpath '{xpath}'").format(attribute=attribute, xpath=xpath)
+        module.fail_json(
+            msg=(
+                "A non-string value {value!r} was parsed for {target}. ".format(value=value, target=target) +
+                "YAML values for booleans, octals, floats may not yield the string you intended. "
+                """Quote the value to be explicit, like `value: "yes"`."""
+            )
+        )
+
     for element in tree.xpath(xpath, namespaces=namespaces):
         if not attribute:
             changed = changed or (element.text != value)

tests/integration/targets/xml/tasks/main.yml

@@ -60,6 +60,7 @@
     - include_tasks: test-remove-element.yml
     - include_tasks: test-remove-element-nochange.yml
     - include_tasks: test-set-attribute-value.yml
+    - include_tasks: test-set-attribute-value-boolean.yml
     - include_tasks: test-set-children-elements.yml
     - include_tasks: test-set-children-elements-level.yml
     - include_tasks: test-set-children-elements-value.yml

tests/integration/targets/xml/tasks/test-set-attribute-value-boolean.yml

@@ -0,0 +1,59 @@
+---
+# Copyright (c) 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
+
+# Regression test for https://github.com/ansible-collections/community.general/issues/7171
+# Passing an unquoted YAML boolean as `value` must now fail with an explicit error.
+
+- name: Setup test fixture
+  copy:
+    src: fixtures/ansible-xml-beers.xml
+    dest: /tmp/ansible-xml-beers.xml
+
+
+- name: "Set '/business/rating/@subjective' to boolean false (unquoted YAML boolean) - must fail"
+  xml:
+    path: /tmp/ansible-xml-beers.xml
+    xpath: /business/rating
+    attribute: subjective
+    value: false
+  register: set_attribute_boolean_false
+  ignore_errors: true
+
+- name: Assert that passing a boolean attribute value raises an error
+  assert:
+    that:
+      - set_attribute_boolean_false is failed
+      - "'was parsed for' in set_attribute_boolean_false.msg"
+      - "'attribute' in set_attribute_boolean_false.msg"
+
+
+- name: "Set '/business/rating' text content to boolean true (unquoted YAML boolean) - must fail"
+  xml:
+    path: /tmp/ansible-xml-beers.xml
+    xpath: /business/rating
+    value: true
+  register: set_element_boolean_true
+  ignore_errors: true
+
+- name: Assert that passing a boolean element value raises an error
+  assert:
+    that:
+      - set_element_boolean_true is failed
+      - "'was parsed for' in set_element_boolean_true.msg"
+      - "'element text' in set_element_boolean_true.msg"
+
+
+- name: "Set '/business/rating/@subjective' to quoted string 'false' - must succeed"
+  xml:
+    path: /tmp/ansible-xml-beers.xml
+    xpath: /business/rating
+    attribute: subjective
+    value: "false"
+  register: set_attribute_string_false
+
+- name: Assert that passing a quoted string attribute value succeeds
+  assert:
+    that:
+      - set_attribute_string_false is changed