ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/modules/command.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: command
 short_description: Execute commands on targets
@@ -117,9 +117,9 @@ seealso:
 author:
     - Ansible Core Team
     - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Return motd to registered var
   ansible.builtin.command: cat /etc/motd
   register: mymotd
@@ -173,9 +173,9 @@ EXAMPLES = r'''
 - name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
   ansible.builtin.command: cat {{ myfile|quote }}
   register: myoutput
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 msg:
   description: changed
   returned: always
@@ -228,7 +228,7 @@ stderr_lines:
   returned: always
   type: list
   sample: [u'ls cannot access foo: No such file or directory', u'ls …']
-'''
+"""
 
 import datetime
 import glob
@@ -249,6 +249,7 @@ def main():
         argument_spec=dict(
             _raw_params=dict(),
             _uses_shell=dict(type='bool', default=False),
+            cmd=dict(),
             argv=dict(type='list', elements='str'),
             chdir=dict(type='path'),
             executable=dict(),
@@ -260,12 +261,14 @@ def main():
             stdin_add_newline=dict(type='bool', default=True),
             strip_empty_ends=dict(type='bool', default=True),
         ),
+        required_one_of=[['_raw_params', 'cmd', 'argv']],
+        mutually_exclusive=[['_raw_params', 'cmd', 'argv']],
         supports_check_mode=True,
     )
     shell = module.params['_uses_shell']
     chdir = module.params['chdir']
     executable = module.params['executable']
-    args = module.params['_raw_params']
+    args = module.params['_raw_params'] or module.params['cmd']
     argv = module.params['argv']
     creates = module.params['creates']
     removes = module.params['removes']
@@ -281,16 +284,6 @@ def main():
         module.warn("As of Ansible 2.4, the parameter 'executable' is no longer supported with the 'command' module. Not using '%s'." % executable)
         executable = None
 
-    if (not args or args.strip() == '') and not argv:
-        r['rc'] = 256
-        r['msg'] = "no command given"
-        module.fail_json(**r)
-
-    if args and argv:
-        r['rc'] = 256
-        r['msg'] = "only command or argv can be given, not both"
-        module.fail_json(**r)
-
     if not shell and args:
         args = shlex.split(args)
 

ansible/modules/copy.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: copy
 version_added: historical
@@ -109,7 +109,6 @@ options:
     description:
     - This flag indicates that filesystem links in the source tree, if they exist, should be followed.
     type: bool
-    default: yes
     version_added: '2.4'
   checksum:
     description:
@@ -155,9 +154,9 @@ attributes:
   vault:
     support: full
     version_added: '2.2'
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Copy file with owner and permissions
   ansible.builtin.copy:
     src: /srv/myfiles/foo.conf
@@ -220,9 +219,9 @@ EXAMPLES = r'''
     src: /etc/foo.conf
     dest: /path/to/link  # link to /path/to/file
     follow: no
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 dest:
     description: Destination file/path.
     returned: success
@@ -283,18 +282,15 @@ state:
     returned: success
     type: str
     sample: file
-'''
+"""
 
 import errno
 import filecmp
-import grp
 import os
 import os.path
-import pwd
 import shutil
 import stat
 import tempfile
-import traceback
 
 from ansible.module_utils.common.text.converters import to_bytes, to_native
 from ansible.module_utils.basic import AnsibleModule
@@ -306,9 +302,9 @@ class AnsibleModuleError(Exception):
 
 
 def split_pre_existing_dir(dirname):
-    '''
+    """
     Return the first pre-existing directory and a list of the new directories that will be created.
-    '''
+    """
     head, tail = os.path.split(dirname)
     b_head = to_bytes(head, errors='surrogate_or_strict')
     if head == '':
@@ -324,9 +320,9 @@ def split_pre_existing_dir(dirname):
 
 
 def adjust_recursive_directory_permissions(pre_existing_dir, new_directory_list, module, directory_args, changed):
-    '''
+    """
     Walk the new directories list and make sure that permissions are as we would expect
-    '''
+    """
 
     if new_directory_list:
         working_dir = os.path.join(pre_existing_dir, new_directory_list.pop(0))
@@ -336,67 +332,24 @@ def adjust_recursive_directory_permissions(pre_existing_dir, new_directory_list,
     return changed
 
 
+def chown_path(module, path, owner, group):
+    """Update the owner/group if specified and different from the current owner/group."""
+    changed = module.set_owner_if_different(path, owner, False)
+    return module.set_group_if_different(path, group, changed)
+
+
 def chown_recursive(path, module):
     changed = False
     owner = module.params['owner']
     group = module.params['group']
 
-    if owner is not None:
-        if not module.check_mode:
-            for dirpath, dirnames, filenames in os.walk(path):
-                owner_changed = module.set_owner_if_different(dirpath, owner, False)
-                if owner_changed is True:
-                    changed = owner_changed
-                for dir in [os.path.join(dirpath, d) for d in dirnames]:
-                    owner_changed = module.set_owner_if_different(dir, owner, False)
-                    if owner_changed is True:
-                        changed = owner_changed
-                for file in [os.path.join(dirpath, f) for f in filenames]:
-                    owner_changed = module.set_owner_if_different(file, owner, False)
-                    if owner_changed is True:
-                        changed = owner_changed
-        else:
-            uid = pwd.getpwnam(owner).pw_uid
-            for dirpath, dirnames, filenames in os.walk(path):
-                owner_changed = (os.stat(dirpath).st_uid != uid)
-                if owner_changed is True:
-                    changed = owner_changed
-                for dir in [os.path.join(dirpath, d) for d in dirnames]:
-                    owner_changed = (os.stat(dir).st_uid != uid)
-                    if owner_changed is True:
-                        changed = owner_changed
-                for file in [os.path.join(dirpath, f) for f in filenames]:
-                    owner_changed = (os.stat(file).st_uid != uid)
-                    if owner_changed is True:
-                        changed = owner_changed
-    if group is not None:
-        if not module.check_mode:
-            for dirpath, dirnames, filenames in os.walk(path):
-                group_changed = module.set_group_if_different(dirpath, group, False)
-                if group_changed is True:
-                    changed = group_changed
-                for dir in [os.path.join(dirpath, d) for d in dirnames]:
-                    group_changed = module.set_group_if_different(dir, group, False)
-                    if group_changed is True:
-                        changed = group_changed
-                for file in [os.path.join(dirpath, f) for f in filenames]:
-                    group_changed = module.set_group_if_different(file, group, False)
-                    if group_changed is True:
-                        changed = group_changed
-        else:
-            gid = grp.getgrnam(group).gr_gid
-            for dirpath, dirnames, filenames in os.walk(path):
-                group_changed = (os.stat(dirpath).st_gid != gid)
-                if group_changed is True:
-                    changed = group_changed
-                for dir in [os.path.join(dirpath, d) for d in dirnames]:
-                    group_changed = (os.stat(dir).st_gid != gid)
-                    if group_changed is True:
-                        changed = group_changed
-                for file in [os.path.join(dirpath, f) for f in filenames]:
-                    group_changed = (os.stat(file).st_gid != gid)
-                    if group_changed is True:
-                        changed = group_changed
+    # TODO: Consolidate with the other methods calling set_*_if_different method, this is inefficient.
+    for dirpath, dirnames, filenames in os.walk(path):
+        changed |= chown_path(module, dirpath, owner, group)
+        for subdir in [os.path.join(dirpath, d) for d in dirnames]:
+            changed |= chown_path(module, subdir, owner, group)
+        for filepath in [os.path.join(dirpath, f) for f in filenames]:
+            changed |= chown_path(module, filepath, owner, group)
 
     return changed
 
@@ -424,10 +377,7 @@ def copy_diff_files(src, dest, module):
                 shutil.copyfile(b_src_item_path, b_dest_item_path)
                 shutil.copymode(b_src_item_path, b_dest_item_path)
 
-            if owner is not None:
-                module.set_owner_if_different(b_dest_item_path, owner, False)
-            if group is not None:
-                module.set_group_if_different(b_dest_item_path, group, False)
+            chown_path(module, b_dest_item_path, owner, group)
             changed = True
     return changed
 
@@ -459,10 +409,7 @@ def copy_left_only(src, dest, module):
 
             if os.path.islink(b_src_item_path) and os.path.isfile(b_src_item_path) and local_follow is True:
                 shutil.copyfile(b_src_item_path, b_dest_item_path)
-                if owner is not None:
-                    module.set_owner_if_different(b_dest_item_path, owner, False)
-                if group is not None:
-                    module.set_group_if_different(b_dest_item_path, group, False)
+                chown_path(module, b_dest_item_path, owner, group)
 
             if os.path.islink(b_src_item_path) and os.path.isfile(b_src_item_path) and local_follow is False:
                 linkto = os.readlink(b_src_item_path)
@@ -471,11 +418,7 @@ def copy_left_only(src, dest, module):
             if not os.path.islink(b_src_item_path) and os.path.isfile(b_src_item_path):
                 shutil.copyfile(b_src_item_path, b_dest_item_path)
                 shutil.copymode(b_src_item_path, b_dest_item_path)
-
-                if owner is not None:
-                    module.set_owner_if_different(b_dest_item_path, owner, False)
-                if group is not None:
-                    module.set_group_if_different(b_dest_item_path, group, False)
+                chown_path(module, b_dest_item_path, owner, group)
 
             if not os.path.islink(b_src_item_path) and os.path.isdir(b_src_item_path):
                 shutil.copytree(b_src_item_path, b_dest_item_path, symlinks=not local_follow)
@@ -503,6 +446,21 @@ def copy_common_dirs(src, dest, module):
     return changed
 
 
+def copy_directory(src, dest, module):
+    if not os.path.exists(dest):
+        if not module.check_mode:
+            shutil.copytree(src, dest, symlinks=not module.params['local_follow'])
+            chown_recursive(dest, module)
+        changed = True
+    else:
+        diff_files_changed = copy_diff_files(src, dest, module)
+        left_only_changed = copy_left_only(src, dest, module)
+        common_dirs_changed = copy_common_dirs(src, dest, module)
+        owner_group_changed = chown_recursive(dest, module)
+        changed = any([diff_files_changed, left_only_changed, common_dirs_changed, owner_group_changed])
+    return changed
+
+
 def main():
 
     module = AnsibleModule(
@@ -516,7 +474,7 @@ def main():
             force=dict(type='bool', default=True),
             validate=dict(type='str'),
             directory_mode=dict(type='raw'),
-            remote_src=dict(type='bool'),
+            remote_src=dict(type='bool', default=False),
             local_follow=dict(type='bool'),
             checksum=dict(type='str'),
             follow=dict(type='bool', default=False),
@@ -653,12 +611,8 @@ def main():
                 if validate:
                     # if we have a mode, make sure we set it on the temporary
                     # file source as some validations may require it
-                    if mode is not None:
-                        module.set_mode_if_different(src, mode, False)
-                    if owner is not None:
-                        module.set_owner_if_different(src, owner, False)
-                    if group is not None:
-                        module.set_group_if_different(src, group, False)
+                    module.set_mode_if_different(src, mode, False)
+                    chown_path(module, src, owner, group)
                     if "%s" not in validate:
                         module.fail_json(msg="validate must contain %%s: %s" % (validate))
                     (rc, out, err) = module.run_command(validate % src)
@@ -683,63 +637,22 @@ def main():
                 module.atomic_move(b_mysrc, dest, unsafe_writes=module.params['unsafe_writes'], keep_dest_attrs=not remote_src)
 
             except (IOError, OSError):
-                module.fail_json(msg="failed to copy: %s to %s" % (src, dest), traceback=traceback.format_exc())
+                module.fail_json(msg=f"Failed to copy {src!r} to {dest!r}.")
         changed = True
 
     # If neither have checksums, both src and dest are directories.
-    if checksum_src is None and checksum_dest is None:
-        if remote_src and os.path.isdir(module.params['src']):
-            b_src = to_bytes(module.params['src'], errors='surrogate_or_strict')
-            b_dest = to_bytes(module.params['dest'], errors='surrogate_or_strict')
-
-            if src.endswith(os.path.sep) and os.path.isdir(module.params['dest']):
-                diff_files_changed = copy_diff_files(b_src, b_dest, module)
-                left_only_changed = copy_left_only(b_src, b_dest, module)
-                common_dirs_changed = copy_common_dirs(b_src, b_dest, module)
-                owner_group_changed = chown_recursive(b_dest, module)
-                if diff_files_changed or left_only_changed or common_dirs_changed or owner_group_changed:
-                    changed = True
-
-            if src.endswith(os.path.sep) and not os.path.exists(module.params['dest']):
-                b_basename = to_bytes(os.path.basename(src), errors='surrogate_or_strict')
-                b_dest = to_bytes(os.path.join(b_dest, b_basename), errors='surrogate_or_strict')
-                b_src = to_bytes(os.path.join(module.params['src'], ""), errors='surrogate_or_strict')
-                if not module.check_mode:
-                    shutil.copytree(b_src, b_dest, symlinks=not local_follow)
-                chown_recursive(dest, module)
-                changed = True
-
-            if not src.endswith(os.path.sep) and os.path.isdir(module.params['dest']):
-                b_basename = to_bytes(os.path.basename(src), errors='surrogate_or_strict')
-                b_dest = to_bytes(os.path.join(b_dest, b_basename), errors='surrogate_or_strict')
-                b_src = to_bytes(os.path.join(module.params['src'], ""), errors='surrogate_or_strict')
-                if not module.check_mode and not os.path.exists(b_dest):
-                    shutil.copytree(b_src, b_dest, symlinks=not local_follow)
-                    changed = True
-                    chown_recursive(dest, module)
-                if module.check_mode and not os.path.exists(b_dest):
-                    changed = True
-                if os.path.exists(b_dest):
-                    diff_files_changed = copy_diff_files(b_src, b_dest, module)
-                    left_only_changed = copy_left_only(b_src, b_dest, module)
-                    common_dirs_changed = copy_common_dirs(b_src, b_dest, module)
-                    owner_group_changed = chown_recursive(b_dest, module)
-                    if diff_files_changed or left_only_changed or common_dirs_changed or owner_group_changed:
-                        changed = True
-
-            if not src.endswith(os.path.sep) and not os.path.exists(module.params['dest']):
-                b_basename = to_bytes(os.path.basename(module.params['src']), errors='surrogate_or_strict')
-                b_dest = to_bytes(os.path.join(b_dest, b_basename), errors='surrogate_or_strict')
-                if not module.check_mode and not os.path.exists(b_dest):
-                    os.makedirs(b_dest)
-                    changed = True
-                    b_src = to_bytes(os.path.join(module.params['src'], ""), errors='surrogate_or_strict')
-                    diff_files_changed = copy_diff_files(b_src, b_dest, module)
-                    left_only_changed = copy_left_only(b_src, b_dest, module)
-                    common_dirs_changed = copy_common_dirs(b_src, b_dest, module)
-                    owner_group_changed = chown_recursive(b_dest, module)
-                if module.check_mode and not os.path.exists(b_dest):
-                    changed = True
+    checksums_none = checksum_src is None and checksum_dest is None
+    both_directories = os.path.isdir(module.params['src']) and (os.path.isdir(module.params['dest']) or not os.path.exists(module.params['dest']))
+    if checksums_none and remote_src and both_directories:
+        b_src = to_bytes(module.params['src'], errors='surrogate_or_strict')
+        b_dest = to_bytes(module.params['dest'], errors='surrogate_or_strict')
+
+        if not b_src.endswith(to_bytes(os.path.sep)):
+            b_basename = os.path.basename(b_src)
+            b_dest = os.path.join(b_dest, b_basename)
+            b_src = os.path.join(b_src, b'')
+
+        changed |= copy_directory(b_src, b_dest, module)
 
     res_args = dict(
         dest=dest, src=src, md5sum=md5sum_src, checksum=checksum_src, changed=changed

ansible/modules/cron.py

@@ -10,7 +10,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: cron
 short_description: Manage cron.d and crontab entries
@@ -72,33 +72,39 @@ options:
   minute:
     description:
       - Minute when the job should run (V(0-59), V(*), V(*/2), and so on).
+      - Cannot be combined with O(special_time).
     type: str
     default: "*"
   hour:
     description:
       - Hour when the job should run (V(0-23), V(*), V(*/2), and so on).
+      - Cannot be combined with O(special_time).
     type: str
     default: "*"
   day:
     description:
       - Day of the month the job should run (V(1-31), V(*), V(*/2), and so on).
+      - Cannot be combined with O(special_time).
     type: str
     default: "*"
     aliases: [ dom ]
   month:
     description:
-      - Month of the year the job should run (V(1-12), V(*), V(*/2), and so on).
+      - Month of the year the job should run (V(JAN-DEC) or V(1-12), V(*), V(*/2), and so on).
+      - Cannot be combined with O(special_time).
     type: str
     default: "*"
   weekday:
     description:
-      - Day of the week that the job should run (V(0-6) for Sunday-Saturday, V(*), and so on).
+      - Day of the week that the job should run (V(SUN-SAT) or V(0-6), V(*), and so on).
+      - Cannot be combined with O(special_time).
     type: str
     default: "*"
     aliases: [ dow ]
   special_time:
     description:
       - Special time specification nickname.
+      - Cannot be combined with O(minute), O(hour), O(day), O(month) or O(weekday).
     type: str
     choices: [ annually, daily, hourly, monthly, reboot, weekly, yearly ]
     version_added: "1.3"
@@ -150,9 +156,9 @@ attributes:
     platform:
         support: full
         platforms: posix
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null"
   ansible.builtin.cron:
     name: "check dirs"
@@ -205,9 +211,9 @@ EXAMPLES = r'''
     name: APP_HOME
     env: yes
     state: absent
-'''
+"""
 
-RETURN = r'''#'''
+RETURN = r"""#"""
 
 import os
 import platform
@@ -262,17 +268,16 @@ class CronTab(object):
         if self.cron_file:
             # read the cronfile
             try:
-                f = open(self.b_cron_file, 'rb')
-                self.n_existing = to_native(f.read(), errors='surrogate_or_strict')
-                self.lines = self.n_existing.splitlines()
-                f.close()
+                with open(self.b_cron_file, 'rb') as f:
+                    self.n_existing = to_native(f.read(), errors='surrogate_or_strict')
+                    self.lines = self.n_existing.splitlines()
             except IOError:
                 # cron file does not exist
                 return
             except Exception:
                 raise CronTabError("Unexpected error:", sys.exc_info()[0])
         else:
-            # using safely quoted shell for now, but this really should be two non-shell calls instead.  FIXME
+            # FIXME: using safely quoted shell for now, but this really should be two non-shell calls instead.
             (rc, out, err) = self.module.run_command(self._read_user_execute(), use_unsafe_shell=True)
 
             if rc != 0 and rc != 1:  # 1 can mean that there are no jobs.
@@ -323,12 +328,12 @@ class CronTab(object):
 
         # Add the entire crontab back to the user crontab
         if not self.cron_file:
-            # quoting shell args for now but really this should be two non-shell calls.  FIXME
+            # FIXME: quoting shell args for now but really this should be two non-shell calls.
             (rc, out, err) = self.module.run_command(self._write_execute(path), use_unsafe_shell=True)
             os.unlink(path)
 
             if rc != 0:
-                self.module.fail_json(msg=err)
+                self.module.fail_json(msg=f"Failed to install new cronfile: {path}", stderr=err, stdout=out, rc=rc)
 
         # set SELinux permissions
         if self.module.selinux_enabled() and self.cron_file:
@@ -646,7 +651,7 @@ def main():
 
     if special_time and \
        (True in [(x != '*') for x in [minute, hour, day, month, weekday]]):
-        module.fail_json(msg="You must specify time and date fields or special time.")
+        module.fail_json(msg="You cannot combine special_time with any of the time or day/date parameters.")
 
     # cannot support special_time on solaris
     if special_time and platform.system() == 'SunOS':

ansible/modules/deb822_repository.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 author: 'Ansible Core Team (@ansible)'
 short_description: 'Add and remove deb822 formatted repositories'
 description:
@@ -145,9 +145,9 @@ options:
 requirements:
     - python3-debian / python-debian
 version_added: '2.15'
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Add debian repo
   deb822_repository:
     name: debian
@@ -189,9 +189,9 @@ EXAMPLES = '''
     components: stable
     architectures: amd64
     signed_by: https://download.example.com/linux/ubuntu/gpg
-'''
+"""
 
-RETURN = '''
+RETURN = """
 repo:
   description: A source string for the repository
   returned: always
@@ -224,13 +224,12 @@ key_filename:
   returned: always
   type: str
   sample: /etc/apt/keyrings/debian.gpg
-'''
+"""
 
 import os
 import re
 import tempfile
 import textwrap
-import traceback
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.basic import missing_required_lib
@@ -248,9 +247,9 @@ HAS_DEBIAN = True
 DEBIAN_IMP_ERR = None
 try:
     from debian.deb822 import Deb822  # type: ignore[import]
-except ImportError:
+except ImportError as ex:
     HAS_DEBIAN = False
-    DEBIAN_IMP_ERR = traceback.format_exc()
+    DEBIAN_IMP_ERR = ex
 
 KEYRINGS_DIR = '/etc/apt/keyrings'
 

ansible/modules/debconf.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: debconf
 short_description: Configure a .deb package
@@ -86,9 +86,9 @@ options:
     default: false
 author:
 - Brian Coca (@bcoca)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Set default locale to fr_FR.UTF-8
   ansible.builtin.debconf:
     name: locales
@@ -121,9 +121,9 @@ EXAMPLES = r'''
     value: "{{ site_passphrase }}"
     vtype: password
   no_log: True
-'''
+"""
 
-RETURN = r'''#'''
+RETURN = r"""#"""
 
 from ansible.module_utils.common.text.converters import to_text, to_native
 from ansible.module_utils.basic import AnsibleModule

ansible/modules/debug.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: debug
 short_description: Print statements during execution
@@ -68,9 +68,9 @@ seealso:
 author:
 - Dag Wieers (@dagwieers)
 - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Print the gateway for each host when defined
   ansible.builtin.debug:
     msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}
@@ -95,4 +95,4 @@ EXAMPLES = r'''
     msg:
     - "Provisioning based on YOUR_KEY which is: {{ lookup('ansible.builtin.env', 'YOUR_KEY') }}"
     - "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
-'''
+"""