ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

ansible/modules/iptables.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: iptables
 short_description: Modify iptables rules
@@ -67,7 +67,7 @@ options:
     description:
       - Which version of the IP protocol this rule should apply to.
     type: str
-    choices: [ ipv4, ipv6 ]
+    choices: [ ipv4, ipv6, both ]
     default: ipv4
   chain:
     description:
@@ -394,9 +394,9 @@ options:
     type: bool
     default: false
     version_added: "2.15"
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Block specific IP
   ansible.builtin.iptables:
     chain: INPUT
@@ -543,7 +543,7 @@ EXAMPLES = r'''
       - "443"
       - "8081:8083"
     jump: ACCEPT
-'''
+"""
 
 import re
 
@@ -564,6 +564,7 @@ BINS = dict(
 ICMP_TYPE_OPTIONS = dict(
     ipv4='--icmp-type',
     ipv6='--icmpv6-type',
+    both='--icmp-type --icmpv6-type',
 )
 
 
@@ -614,7 +615,6 @@ def append_wait(rule, param, flag):
 
 def construct_rule(params):
     rule = []
-    append_wait(rule, params['wait'], '-w')
     append_param(rule, params['protocol'], '-p', False)
     append_param(rule, params['source'], '-s', False)
     append_param(rule, params['destination'], '-d', False)
@@ -701,6 +701,8 @@ def push_arguments(iptables_path, action, params, make_rule=True):
     cmd.extend([action, params['chain']])
     if action == '-I' and params['rule_num']:
         cmd.extend([params['rule_num']])
+    if params['wait']:
+        cmd.extend(['-w', params['wait']])
     if make_rule:
         cmd.extend(construct_rule(params))
     return cmd
@@ -781,7 +783,7 @@ def main():
             table=dict(type='str', default='filter', choices=['filter', 'nat', 'mangle', 'raw', 'security']),
             state=dict(type='str', default='present', choices=['absent', 'present']),
             action=dict(type='str', default='append', choices=['append', 'insert']),
-            ip_version=dict(type='str', default='ipv4', choices=['ipv4', 'ipv6']),
+            ip_version=dict(type='str', default='ipv4', choices=['ipv4', 'ipv6', 'both']),
             chain=dict(type='str'),
             rule_num=dict(type='str'),
             protocol=dict(type='str'),
@@ -861,86 +863,97 @@ def main():
         rule=' '.join(construct_rule(module.params)),
         state=module.params['state'],
         chain_management=module.params['chain_management'],
+        wait=module.params['wait'],
     )
 
-    ip_version = module.params['ip_version']
-    iptables_path = module.get_bin_path(BINS[ip_version], True)
+    ip_version = ['ipv4', 'ipv6'] if module.params['ip_version'] == 'both' else [module.params['ip_version']]
+    iptables_path = [module.get_bin_path('iptables', True) if ip_version == 'ipv4' else module.get_bin_path('ip6tables', True) for ip_version in ip_version]
 
-    if module.params.get('log_prefix', None) or module.params.get('log_level', None):
-        if module.params['jump'] is None:
-            module.params['jump'] = 'LOG'
-        elif module.params['jump'] != 'LOG':
-            module.fail_json(msg="Logging options can only be used with the LOG jump target.")
+    both_changed = False
 
-    # Check if wait option is supported
-    iptables_version = LooseVersion(get_iptables_version(iptables_path, module))
+    for path in iptables_path:
+        if module.params.get('log_prefix', None) or module.params.get('log_level', None):
+            if module.params['jump'] is None:
+                module.params['jump'] = 'LOG'
+            elif module.params['jump'] != 'LOG':
+                module.fail_json(msg="Logging options can only be used with the LOG jump target.")
 
-    if iptables_version >= LooseVersion(IPTABLES_WAIT_SUPPORT_ADDED):
-        if iptables_version < LooseVersion(IPTABLES_WAIT_WITH_SECONDS_SUPPORT_ADDED):
-            module.params['wait'] = ''
-    else:
-        module.params['wait'] = None
-
-    # Flush the table
-    if args['flush'] is True:
-        args['changed'] = True
-        if not module.check_mode:
-            flush_table(iptables_path, module, module.params)
-
-    # Set the policy
-    elif module.params['policy']:
-        current_policy = get_chain_policy(iptables_path, module, module.params)
-        if not current_policy:
-            module.fail_json(msg='Can\'t detect current policy')
-
-        changed = current_policy != module.params['policy']
-        args['changed'] = changed
-        if changed and not module.check_mode:
-            set_chain_policy(iptables_path, module, module.params)
-
-    # Delete the chain if there is no rule in the arguments
-    elif (args['state'] == 'absent') and not args['rule']:
-        chain_is_present = check_chain_present(
-            iptables_path, module, module.params
-        )
-        args['changed'] = chain_is_present
-
-        if (chain_is_present and args['chain_management'] and not module.check_mode):
-            delete_chain(iptables_path, module, module.params)
+        # Check if wait option is supported
+        iptables_version = LooseVersion(get_iptables_version(path, module))
 
-    else:
-        # Create the chain if there are no rule arguments
-        if (args['state'] == 'present') and not args['rule']:
+        if iptables_version >= LooseVersion(IPTABLES_WAIT_SUPPORT_ADDED):
+            if iptables_version < LooseVersion(IPTABLES_WAIT_WITH_SECONDS_SUPPORT_ADDED):
+                module.params['wait'] = ''
+        else:
+            module.params['wait'] = None
+
+        # Flush the table
+        if args['flush'] is True:
+            args['changed'] = True
+            both_changed = True
+            if not module.check_mode:
+                flush_table(path, module, module.params)
+
+        # Set the policy
+        elif module.params['policy']:
+            current_policy = get_chain_policy(path, module, module.params)
+            if not current_policy:
+                module.fail_json(msg='Can\'t detect current policy')
+
+            changed = current_policy != module.params['policy']
+            args['changed'] = changed
+            both_changed = both_changed or changed
+            if changed and not module.check_mode:
+                set_chain_policy(path, module, module.params)
+
+        # Delete the chain if there is no rule in the arguments
+        elif (args['state'] == 'absent') and not args['rule']:
             chain_is_present = check_chain_present(
-                iptables_path, module, module.params
+                path, module, module.params
             )
-            args['changed'] = not chain_is_present
+            args['changed'] = chain_is_present
+            both_changed = both_changed or chain_is_present
 
-            if (not chain_is_present and args['chain_management'] and not module.check_mode):
-                create_chain(iptables_path, module, module.params)
+            if (chain_is_present and args['chain_management'] and not module.check_mode):
+                delete_chain(path, module, module.params)
 
         else:
-            insert = (module.params['action'] == 'insert')
-            rule_is_present = check_rule_present(
-                iptables_path, module, module.params
-            )
+            # Create the chain if there are no rule arguments
+            if (args['state'] == 'present') and not args['rule']:
+                chain_is_present = check_chain_present(
+                    path, module, module.params
+                )
+                args['changed'] = not chain_is_present
+                both_changed = both_changed or not chain_is_present
 
-            should_be_present = (args['state'] == 'present')
-            # Check if target is up to date
-            args['changed'] = (rule_is_present != should_be_present)
-            if args['changed'] is False:
-                # Target is already up to date
-                module.exit_json(**args)
+                if (not chain_is_present and args['chain_management'] and not module.check_mode):
+                    create_chain(path, module, module.params)
 
-            # Modify if not check_mode
-            if not module.check_mode:
-                if should_be_present:
-                    if insert:
-                        insert_rule(iptables_path, module, module.params)
+            else:
+                insert = (module.params['action'] == 'insert')
+                rule_is_present = check_rule_present(
+                    path, module, module.params
+                )
+
+                should_be_present = (args['state'] == 'present')
+                # Check if target is up to date
+                args['changed'] = (rule_is_present != should_be_present)
+                both_changed = both_changed or (rule_is_present != should_be_present)
+                if args['changed'] is False:
+                    # Target is already up to date
+                    continue
+
+                # Modify if not check_mode
+                if not module.check_mode:
+                    if should_be_present:
+                        if insert:
+                            insert_rule(path, module, module.params)
+                        else:
+                            append_rule(path, module, module.params)
                     else:
-                        append_rule(iptables_path, module, module.params)
-                else:
-                    remove_rule(iptables_path, module, module.params)
+                        remove_rule(path, module, module.params)
+
+    args['changed'] = both_changed
 
     module.exit_json(**args)
 

ansible/modules/known_hosts.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: known_hosts
 short_description: Add or remove a host from the C(known_hosts) file
@@ -65,9 +65,9 @@ extends_documentation_fragment:
   - action_common_attributes
 author:
 - Matthew Vernon (@mcv21)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Tell the host about our servers it might want to ssh to
   ansible.builtin.known_hosts:
     path: /etc/ssh/ssh_known_hosts
@@ -87,7 +87,7 @@ EXAMPLES = r'''
     key: '[host1.example.com]:2222 ssh-rsa ASDeararAIUHI324324' # some key gibberish
     path: /etc/ssh/ssh_known_hosts
     state: present
-'''
+"""
 
 # Makes sure public host keys are present or absent in the given known_hosts
 # file.
@@ -102,7 +102,6 @@ EXAMPLES = r'''
 
 import base64
 import copy
-import errno
 import hashlib
 import hmac
 import os
@@ -169,11 +168,10 @@ def enforce_state(module, params):
     if replace_or_add or found != (state == "present"):
         try:
             inf = open(path, "r")
-        except IOError as e:
-            if e.errno == errno.ENOENT:
-                inf = None
-            else:
-                module.fail_json(msg="Failed to read %s: %s" % (path, str(e)))
+        except FileNotFoundError:
+            inf = None
+        except OSError as ex:
+            raise Exception(f"Failed to read {path!r}.") from ex
         try:
             with tempfile.NamedTemporaryFile(mode='w+', dir=os.path.dirname(path), delete=False) as outf:
                 if inf is not None:
@@ -184,8 +182,8 @@ def enforce_state(module, params):
                     inf.close()
                 if state == 'present':
                     outf.write(key)
-        except (IOError, OSError) as e:
-            module.fail_json(msg="Failed to write to file %s: %s" % (path, to_native(e)))
+        except OSError as ex:
+            raise Exception(f"Failed to write to file {path!r}.") from ex
         else:
             module.atomic_move(outf.name, path)
 
@@ -195,13 +193,13 @@ def enforce_state(module, params):
 
 
 def sanity_check(module, host, key, sshkeygen):
-    '''Check supplied key is sensible
+    """Check supplied key is sensible
 
     host and key are parameters provided by the user; If the host
     provided is inconsistent with the key supplied, then this function
     quits, providing an error to the user.
     sshkeygen is the path to ssh-keygen, found earlier with get_bin_path
-    '''
+    """
     # If no key supplied, we're doing a removal, and have nothing to check here.
     if not key:
         return
@@ -220,9 +218,8 @@ def sanity_check(module, host, key, sshkeygen):
         try:
             outf.write(key)
             outf.flush()
-        except IOError as e:
-            module.fail_json(msg="Failed to write to temporary file %s: %s" %
-                             (outf.name, to_native(e)))
+        except OSError as ex:
+            raise Exception(f"Failed to write to temporary file {outf.name!r}.") from ex
 
         sshkeygen_command = [sshkeygen, '-F', host, '-f', outf.name]
         rc, stdout, stderr = module.run_command(sshkeygen_command)
@@ -232,7 +229,7 @@ def sanity_check(module, host, key, sshkeygen):
 
 
 def search_for_host_key(module, host, key, path, sshkeygen):
-    '''search_for_host_key(module,host,key,path,sshkeygen) -> (found,replace_or_add,found_line)
+    """search_for_host_key(module,host,key,path,sshkeygen) -> (found,replace_or_add,found_line)
 
     Looks up host and keytype in the known_hosts file path; if it's there, looks to see
     if one of those entries matches key. Returns:
@@ -241,7 +238,7 @@ def search_for_host_key(module, host, key, path, sshkeygen):
     found_line (int or None): the line where a key of the same type was found
     if found=False, then replace is always False.
     sshkeygen is the path to ssh-keygen, found earlier with get_bin_path
-    '''
+    """
     if os.path.exists(path) is False:
         return False, False, None
 
@@ -304,14 +301,14 @@ def hash_host_key(host, key):
 
 
 def normalize_known_hosts_key(key):
-    '''
+    """
     Transform a key, either taken from a known_host file or provided by the
     user, into a normalized form.
     The host part (which might include multiple hostnames or be hashed) gets
     replaced by the provided host. Also, any spurious information gets removed
     from the end (like the username@host tag usually present in hostkeys, but
     absent in known_hosts files)
-    '''
+    """
     key = key.strip()  # trim trailing newline
     k = key.split()
     d = dict()
@@ -337,9 +334,10 @@ def compute_diff(path, found_line, replace_or_add, state, key):
     }
     try:
         inf = open(path, "r")
-    except IOError as e:
-        if e.errno == errno.ENOENT:
-            diff['before_header'] = '/dev/null'
+    except FileNotFoundError:
+        diff['before_header'] = '/dev/null'
+    except OSError:
+        pass
     else:
         diff['before'] = inf.read()
         inf.close()

ansible/modules/lineinfile.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: lineinfile
 short_description: Manage lines in text files
@@ -152,9 +152,9 @@ author:
     - Daniel Hokka Zakrissoni (@dhozac)
     - Ahti Kitsik (@ahtik)
     - Jose Angel Munoz (@imjoseangel)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # NOTE: Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
 - name: Ensure SELinux is set to enforcing mode
   ansible.builtin.lineinfile:
@@ -237,9 +237,9 @@ EXAMPLES = r'''
     regexp: ^(host=).*
     line: \g<1>{{ hostname }}
     backrefs: yes
-'''
+"""
 
-RETURN = r'''#'''
+RETURN = r"""#"""
 
 import os
 import re

ansible/modules/meta.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 module: meta
 short_description: Execute Ansible 'actions'
 version_added: '1.2'
@@ -83,9 +83,9 @@ seealso:
 - module: ansible.builtin.fail
 author:
     - Ansible Core Team
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # Example showing flushing handlers on demand, not at end of play
 - ansible.builtin.template:
     src: new.j2
@@ -131,4 +131,4 @@ EXAMPLES = r'''
   when:
   - ansible_distribution == 'CentOS'
   - ansible_distribution_major_version == '6'
-'''
+"""

ansible/modules/mount_facts.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2024 Ansible Project
+# Copyright: Contributors to the Ansible project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import annotations
@@ -359,7 +359,7 @@ def gen_mounts_from_stdout(stdout: str) -> t.Iterable[MountInfo]:
         elif pattern is BSD_MOUNT_RE:
             # the group containing fstype is comma separated, and may include whitespace
             mount_info = match.groupdict()
-            parts = re.split(r"\s*,\s*", match.group("fstype"), 1)
+            parts = re.split(r"\s*,\s*", match.group("fstype"), maxsplit=1)
             if len(parts) == 1:
                 mount_info["fstype"] = parts[0]
             else:

ansible/modules/package.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: package
 version_added: 2.0
@@ -66,8 +66,8 @@ attributes:
 notes:
     - While M(ansible.builtin.package) abstracts package managers to ease dealing with multiple distributions, package name often differs for the same software.
 
-'''
-EXAMPLES = '''
+"""
+EXAMPLES = """
 - name: Install ntpdate
   ansible.builtin.package:
     name: ntpdate
@@ -85,4 +85,10 @@ EXAMPLES = '''
       - httpd
       - mariadb-server
     state: latest
-'''
+
+- name: Use the dnf package manager to install httpd
+  ansible.builtin.package:
+    name: httpd
+    state: present
+    use: dnf
+"""

ansible/modules/package_facts.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 module: package_facts
 short_description: Package information as facts
 description:
@@ -23,7 +23,7 @@ options:
     default: ['auto']
     choices:
         auto: Depending on O(strategy), will match the first or all package managers provided, in order
-        rpm: For RPM based distros, requires RPM Python bindings, not installed by default on Suse (python3-rpm)
+        rpm: For RPM based distros, requires RPM Python bindings, not installed by default on Suse or Fedora 41+ (python3-rpm)
         yum: Alias to rpm
         dnf: Alias to rpm
         dnf5: Alias to rpm
@@ -67,9 +67,9 @@ attributes:
         support: full
     platform:
         platforms: posix
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Gather the package facts
   ansible.builtin.package_facts:
     manager: auto
@@ -83,9 +83,9 @@ EXAMPLES = '''
     msg: "{{ ansible_facts.packages['foobar'] | length }} versions of foobar are installed!"
   when: "'foobar' in ansible_facts.packages"
 
-'''
+"""
 
-RETURN = '''
+RETURN = """
 ansible_facts:
   description: Facts to add to ansible_facts.
   returned: always
@@ -248,7 +248,7 @@ ansible_facts:
             ],
           }
         }
-'''
+"""
 
 import re
 
@@ -460,7 +460,7 @@ def main():
 
     # get supported pkg managers
     PKG_MANAGERS = get_all_pkg_managers()
-    PKG_MANAGER_NAMES = [x.lower() for x in PKG_MANAGERS.keys()]
+    PKG_MANAGER_NAMES = sorted([x.lower() for x in PKG_MANAGERS.keys()])
     # add aliases
     PKG_MANAGER_NAMES.extend([alias for alist in ALIASES.values() for alias in alist])
 
@@ -510,12 +510,24 @@ def main():
 
         manager = PKG_MANAGERS[pkgmgr]()
         try:
+            packages_found = {}
             if manager.is_available(handle_exceptions=False):
-                found += 1
                 try:
-                    packages.update(manager.get_packages())
+                    packages_found = manager.get_packages()
                 except Exception as e:
                     module.warn('Failed to retrieve packages with %s: %s' % (pkgmgr, to_text(e)))
+
+            # only consider 'found' if it results in something
+            if packages_found:
+                found += 1
+                for k in packages_found.keys():
+                    if k in packages:
+                        packages[k].extend(packages_found[k])
+                    else:
+                        packages[k] = packages_found[k]
+            else:
+                module.warn('Found "%s" but no associated packages' % (pkgmgr))
+
         except Exception as e:
             if pkgmgr in module.params['manager']:
                 module.warn('Requested package manager %s was not usable by this module: %s' % (pkgmgr, to_text(e)))

ansible/modules/pause.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: pause
 short_description: Pause playbook execution
@@ -65,9 +65,9 @@ attributes:
 notes:
       - Starting in 2.2, if you specify 0 or negative for minutes or seconds, it will wait for 1 second, previously it would wait indefinitely.
       - User input is not captured or echoed, regardless of echo setting, when minutes or seconds is specified.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Pause for 5 minutes to build app cache
   ansible.builtin.pause:
     minutes: 5
@@ -83,9 +83,9 @@ EXAMPLES = '''
   ansible.builtin.pause:
     prompt: "Enter a secret"
     echo: no
-'''
+"""
 
-RETURN = '''
+RETURN = """
 user_input:
   description: User input from interactive console
   returned: if no waiting time set
@@ -116,4 +116,4 @@ echo:
   returned: always
   type: bool
   sample: true
-'''
+"""

ansible/modules/ping.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: ping
 version_added: historical
@@ -41,9 +41,9 @@ seealso:
 author:
   - Ansible Core Team
   - Michael DeHaan
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 # Test we can logon to 'webservers' and execute python with json lib.
 # ansible webservers -m ansible.builtin.ping
 
@@ -53,15 +53,15 @@ EXAMPLES = '''
 - name: Induce an exception to see what happens
   ansible.builtin.ping:
     data: crash
-'''
+"""
 
-RETURN = '''
+RETURN = """
 ping:
     description: Value provided with the O(data) parameter.
     returned: success
     type: str
     sample: pong
-'''
+"""
 
 from ansible.module_utils.basic import AnsibleModule