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

ansible/modules/unarchive.py

@@ -10,7 +10,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: unarchive
 version_added: '1.4'
@@ -150,9 +150,9 @@ seealso:
 - module: community.general.iso_extract
 - module: community.windows.win_unzip
 author: Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Extract foo.tgz into /var/lib/foo
   ansible.builtin.unarchive:
     src: foo.tgz
@@ -177,9 +177,9 @@ EXAMPLES = r'''
     extra_opts:
     - --transform
     - s/^xxx/yyy/
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 dest:
   description: Path to the destination directory.
   returned: always
@@ -237,10 +237,11 @@ uid:
   returned: always
   type: int
   sample: 1000
-'''
+"""
 
 import binascii
 import codecs
+import ctypes
 import fnmatch
 import grp
 import os
@@ -249,7 +250,6 @@ import pwd
 import re
 import stat
 import time
-import traceback
 from functools import partial
 from zipfile import ZipFile
 
@@ -262,6 +262,13 @@ from ansible.module_utils.urls import fetch_file
 from shlex import quote
 from zipfile import BadZipFile
 
+try:
+    from functools import cache
+except ImportError:
+    # Python < 3.9
+    from functools import lru_cache
+    cache = lru_cache(maxsize=None)
+
 # String from tar that shows the tar contents are different from the
 # filesystem
 OWNER_DIFF_RE = re.compile(r': Uid differs$')
@@ -279,8 +286,20 @@ CONTENT_DIFF_RE = re.compile(r': Contents differ$')
 SIZE_DIFF_RE = re.compile(r': Size differs$')
 
 
+@cache
+def _y2038_impacted():
+    """Determine if the system has 64-bit time_t."""
+    if hasattr(ctypes, "c_time_t"):  # Python >= 3.12
+        return ctypes.sizeof(ctypes.c_time_t) < 8
+    try:
+        time.gmtime(2**31)
+    except OverflowError:
+        return True
+    return False
+
+
 def crc32(path, buffer_size):
-    ''' Return a CRC32 checksum of a file '''
+    """ Return a CRC32 checksum of a file """
 
     crc = binascii.crc32(b'')
     with open(path, 'rb') as f:
@@ -290,7 +309,7 @@ def crc32(path, buffer_size):
 
 
 def shell_escape(string):
-    ''' Quote meta-characters in the args for the unix shell '''
+    """ Quote meta-characters in the args for the unix shell """
     return re.sub(r'([^A-Za-z0-9_])', r'\\\1', string)
 
 
@@ -321,7 +340,7 @@ class ZipArchive(object):
         )
 
     def _permstr_to_octal(self, modestr, umask):
-        ''' Convert a Unix permission string (rw-r--r--) into a mode (0644) '''
+        """ Convert a Unix permission string (rw-r--r--) into a mode (0644) """
         revstr = modestr[::-1]
         mode = 0
         for j in range(0, 3):
@@ -414,6 +433,8 @@ class ZipArchive(object):
             try:
                 if int(match.groups()[0]) < 1980:
                     date_time = epoch_date_time
+                elif int(match.groups()[0]) >= 2038 and _y2038_impacted():
+                    date_time = (2038, 1, 1, 0, 0, 0, 0, 0, 0)
                 elif int(match.groups()[0]) > 2107:
                     date_time = (2107, 12, 31, 23, 59, 59, 0, 0, 0)
                 else:
@@ -676,7 +697,7 @@ class ZipArchive(object):
                             try:
                                 mode = AnsibleModule._symbolic_mode_to_octal(st, self.file_args['mode'])
                             except ValueError as e:
-                                self.module.fail_json(path=path, msg="%s" % to_native(e), exception=traceback.format_exc())
+                                self.module.fail_json(path=path, msg="%s" % to_native(e))
                 # Only special files require no umask-handling
                 elif ztype == '?':
                     mode = self._permstr_to_octal(permstr, 0)
@@ -1111,8 +1132,8 @@ def main():
             res_args['extract_results'] = handler.unarchive()
             if res_args['extract_results']['rc'] != 0:
                 module.fail_json(msg="failed to unpack %s to %s" % (src, dest), **res_args)
-        except IOError:
-            module.fail_json(msg="failed to unpack %s to %s" % (src, dest), **res_args)
+        except OSError as ex:
+            module.fail_json(f"Failed to unpack {src!r} to {dest!r}.", exception=ex, **res_args)
         else:
             res_args['changed'] = True
 
@@ -1129,8 +1150,8 @@ def main():
 
             try:
                 res_args['changed'] = module.set_fs_attributes_if_different(file_args, res_args['changed'], expand=False)
-            except (IOError, OSError) as e:
-                module.fail_json(msg="Unexpected error when accessing exploded file: %s" % to_native(e), **res_args)
+            except OSError as ex:
+                module.fail_json("Unexpected error when accessing exploded file.", exception=ex, **res_args)
 
             if '/' in filename:
                 top_folder_path = filename.split('/')[0]
@@ -1144,8 +1165,8 @@ def main():
                 file_args['path'] = "%s/%s" % (dest, f)
                 try:
                     res_args['changed'] = module.set_fs_attributes_if_different(file_args, res_args['changed'], expand=False)
-                except (IOError, OSError) as e:
-                    module.fail_json(msg="Unexpected error when accessing exploded file: %s" % to_native(e), **res_args)
+                except OSError as ex:
+                    module.fail_json("Unexpected error when accessing exploded file.", exception=ex, **res_args)
 
     if module.params['list_files']:
         res_args['files'] = handler.files_in_archive

ansible/modules/uri.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: uri
 short_description: Interacts with webservices
@@ -61,6 +61,7 @@ options:
         or list of tuples into an C(application/x-www-form-urlencoded) string. (Added in v2.7)
       - If O(body_format) is set to V(form-multipart) it will convert a dictionary
         into C(multipart/form-multipart) body. (Added in v2.10)
+      - If C(body_format) is set to V(form-multipart) the option 'multipart_encoding' allows to change multipart file encoding. (Added in v2.19)
     type: raw
   body_format:
     description:
@@ -105,18 +106,6 @@ options:
       - The webservice bans or rate-limits clients that cause any HTTP 401 errors.
     type: bool
     default: no
-  follow_redirects:
-    description:
-      - Whether or not the URI module should follow redirects.
-    type: str
-    default: safe
-    choices:
-      all: Will follow all redirects.
-      none: Will not follow any redirects.
-      safe: Only redirects doing GET or HEAD requests will be followed.
-      urllib2: Defer to urllib2 behavior (As of writing this follows HTTP redirects).
-      'no': (DEPRECATED, removed in 2.22) alias of V(none).
-      'yes': (DEPRECATED, removed in 2.22) alias of V(all).
   creates:
     description:
       - A filename, when it already exists, this step will not be run.
@@ -234,6 +223,7 @@ options:
 extends_documentation_fragment:
   - action_common_attributes
   - files
+  - url.url_redirect
 attributes:
     check_mode:
         support: none
@@ -250,9 +240,9 @@ seealso:
 - module: ansible.windows.win_uri
 author:
 - Romeo Theriault (@romeotheriault)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Check that you can connect (GET) to a page and it returns a status 200
   ansible.builtin.uri:
     url: http://www.example.com
@@ -262,7 +252,7 @@ EXAMPLES = r'''
     url: http://www.example.com
     return_content: true
   register: this
-  failed_when: this is failed or "'AWESOME' not in this.content"
+  failed_when: "this is failed or 'AWESOME' not in this.content"
 
 - name: Create a JIRA issue
   ansible.builtin.uri:
@@ -308,10 +298,12 @@ EXAMPLES = r'''
       file1:
         filename: /bin/true
         mime_type: application/octet-stream
+        multipart_encoding: base64
       file2:
         content: text based file content
         filename: fake.txt
         mime_type: text/plain
+        multipart_encoding: 7or8bit
       text_form_field: value
 
 - name: Connect to website using a previously stored cookie
@@ -387,9 +379,9 @@ EXAMPLES = r'''
   uri:
     url: https://example.org
     ciphers: '@SECLEVEL=2:ECDH+AESGCM:ECDH+CHACHA20:ECDH+AES:DHE+AES:!aNULL:!eNULL:!aDSS:!SHA1:!AESCCM'
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 # The return information includes all the HTTP headers in lower-case.
 content:
   description: The response body content.
@@ -438,21 +430,29 @@ url:
   returned: always
   type: str
   sample: https://www.ansible.com/
-'''
+"""
 
+import http
 import json
 import os
 import re
 import shutil
 import tempfile
+from datetime import datetime, timezone
 
 from ansible.module_utils.basic import AnsibleModule, sanitize_keys
 from ansible.module_utils.six import binary_type, iteritems, string_types
 from ansible.module_utils.six.moves.urllib.parse import urlencode, urljoin
 from ansible.module_utils.common.text.converters import to_native, to_text
-from ansible.module_utils.compat.datetime import utcnow, utcfromtimestamp
 from ansible.module_utils.six.moves.collections_abc import Mapping, Sequence
-from ansible.module_utils.urls import fetch_url, get_response_filename, parse_content_type, prepare_multipart, url_argument_spec
+from ansible.module_utils.urls import (
+    fetch_url,
+    get_response_filename,
+    parse_content_type,
+    prepare_multipart,
+    url_argument_spec,
+    url_redirect_argument_spec,
+)
 
 JSON_CANDIDATES = {'json', 'javascript'}
 
@@ -506,7 +506,7 @@ def write_file(module, dest, content, resp):
 
 
 def kv_list(data):
-    ''' Convert data into a list of key-value tuples '''
+    """ Convert data into a list of key-value tuples """
     if data is None:
         return None
 
@@ -520,7 +520,7 @@ def kv_list(data):
 
 
 def form_urlencoded(body):
-    ''' Convert data into a form-urlencoded string '''
+    """ Convert data into a form-urlencoded string """
     if isinstance(body, string_types):
         return body
 
@@ -558,7 +558,10 @@ def uri(module, url, dest, body, body_format, method, headers, socket_timeout, c
     kwargs = {}
     if dest is not None and os.path.isfile(dest):
         # if destination file already exist, only download if file newer
-        kwargs['last_mod_time'] = utcfromtimestamp(os.path.getmtime(dest))
+        kwargs['last_mod_time'] = datetime.fromtimestamp(
+            os.path.getmtime(dest),
+            tz=timezone.utc,
+        )
 
     if module.params.get('follow_redirects') in ('no', 'yes'):
         module.deprecate(
@@ -584,6 +587,8 @@ def uri(module, url, dest, body, body_format, method, headers, socket_timeout, c
 
 def main():
     argument_spec = url_argument_spec()
+    argument_spec['url']['required'] = True
+    argument_spec.update(url_redirect_argument_spec())
     argument_spec.update(
         dest=dict(type='path'),
         url_username=dict(type='str', aliases=['user']),
@@ -670,12 +675,12 @@ def main():
             module.exit_json(stdout="skipped, since '%s' does not exist" % removes, changed=False)
 
     # Make the request
-    start = utcnow()
+    start = datetime.now(timezone.utc)
     r, info = uri(module, url, dest, body, body_format, method,
                   dict_headers, socket_timeout, ca_path, unredirected_headers,
                   decompress, ciphers, use_netrc)
 
-    elapsed = (utcnow() - start).seconds
+    elapsed = (datetime.now(timezone.utc) - start).seconds
 
     if r and dest is not None and os.path.isdir(dest):
         filename = get_response_filename(r) or 'index.html'
@@ -711,6 +716,8 @@ def main():
             # there was no content, but the error read()
             # may have been stored in the info as 'body'
             content = info.pop('body', b'')
+        except http.client.HTTPException as http_err:
+            module.fail_json(msg=f"HTTP Error while fetching {url}: {to_native(http_err)}")
     elif r:
         content = r
     else:

ansible/modules/user.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 module: user
 version_added: "0.2"
 short_description: Manage user accounts
@@ -319,9 +319,9 @@ seealso:
 - module: ansible.windows.win_user
 author:
 - Stephen Fromm (@sfromm)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Add the user 'johnd' with a specific uid and a primary group of 'admin'
   ansible.builtin.user:
     name: johnd
@@ -385,9 +385,9 @@ EXAMPLES = r'''
   ansible.builtin.user:
     name: jimholden2016
     password_expire_account_disable: 15
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 append:
   description: Whether or not to append the user to groups.
   returned: When O(state) is V(present) and the user exists
@@ -486,7 +486,7 @@ uid:
   returned: When O(uid) is passed to the module
   type: int
   sample: 1044
-'''
+"""
 
 
 import ctypes.util
@@ -503,13 +503,13 @@ import socket
 import subprocess
 import time
 import math
+import typing as t
 
 from ansible.module_utils import distro
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.locale import get_best_parsable_locale
 from ansible.module_utils.common.sys_info import get_platform_subclass
-import ansible.module_utils.compat.typing as t
 
 
 class StructSpwdType(ctypes.Structure):
@@ -1092,7 +1092,7 @@ class User(object):
         return groups
 
     def user_group_membership(self, exclude_primary=True):
-        ''' Return a list of groups the user belongs to '''
+        """ Return a list of groups the user belongs to """
         groups = []
         info = self.get_pwd_info()
         for group in grp.getgrall():
@@ -1341,7 +1341,7 @@ class User(object):
         try:
             with open(ssh_public_key_file, 'r') as f:
                 ssh_public_key = f.read().strip()
-        except IOError:
+        except OSError:
             return None
         return ssh_public_key
 
@@ -1376,16 +1376,24 @@ class User(object):
                     self.module.exit_json(failed=True, msg="%s" % to_native(e))
             # get umask from /etc/login.defs and set correct home mode
             if os.path.exists(self.LOGIN_DEFS):
-                with open(self.LOGIN_DEFS, 'r') as f:
-                    for line in f:
-                        m = re.match(r'^UMASK\s+(\d+)$', line)
-                        if m:
-                            umask = int(m.group(1), 8)
+                # fallback if neither HOME_MODE nor UMASK are set;
+                # follow behaviour of useradd initializing UMASK = 022
+                mode = 0o755
+                with open(self.LOGIN_DEFS, 'r') as fh:
+                    for line in fh:
+                        # HOME_MODE has higher precedence as UMASK
+                        match = re.match(r'^HOME_MODE\s+(\d+)$', line)
+                        if match:
+                            mode = int(match.group(1), 8)
+                            break  # higher precedence
+                        match = re.match(r'^UMASK\s+(\d+)$', line)
+                        if match:
+                            umask = int(match.group(1), 8)
                             mode = 0o777 & ~umask
-                            try:
-                                os.chmod(path, mode)
-                            except OSError as e:
-                                self.module.exit_json(failed=True, msg="%s" % to_native(e))
+                try:
+                    os.chmod(path, mode)
+                except OSError as e:
+                    self.module.exit_json(failed=True, msg=to_native(e))
 
     def chown_homedir(self, uid, gid, path):
         try:
@@ -2442,7 +2450,7 @@ class DarwinUser(User):
         return groups
 
     def _get_user_property(self, property):
-        '''Return user PROPERTY as given my dscl(1) read or None if not found.'''
+        """Return user PROPERTY as given my dscl(1) read or None if not found."""
         cmd = self._get_dscl()
         cmd += ['-read', '/Users/%s' % self.name, property]
         (rc, out, err) = self.execute_command(cmd, obey_checkmode=False)
@@ -2462,10 +2470,10 @@ class DarwinUser(User):
         return None
 
     def _get_next_uid(self, system=None):
-        '''
+        """
         Return the next available uid. If system=True, then
         uid should be below of 500, if possible.
-        '''
+        """
         cmd = self._get_dscl()
         cmd += ['-list', '/Users', 'UniqueID']
         (rc, out, err) = self.execute_command(cmd, obey_checkmode=False)
@@ -2491,10 +2499,10 @@ class DarwinUser(User):
         return max_uid + 1
 
     def _change_user_password(self):
-        '''Change password for SELF.NAME against SELF.PASSWORD.
+        """Change password for SELF.NAME against SELF.PASSWORD.
 
         Please note that password must be cleartext.
-        '''
+        """
         # some documentation on how is stored passwords on OSX:
         # http://blog.lostpassword.com/2012/07/cracking-mac-os-x-lion-accounts-passwords/
         # http://null-byte.wonderhowto.com/how-to/hack-mac-os-x-lion-passwords-0130036/
@@ -2513,7 +2521,7 @@ class DarwinUser(User):
         return (rc, out, err)
 
     def _make_group_numerical(self):
-        '''Convert SELF.GROUP to is stringed numerical value suitable for dscl.'''
+        """Convert SELF.GROUP to is stringed numerical value suitable for dscl."""
         if self.group is None:
             self.group = 'nogroup'
         try:
@@ -2524,8 +2532,8 @@ class DarwinUser(User):
         self.group = str(self.group)
 
     def __modify_group(self, group, action):
-        '''Add or remove SELF.NAME to or from GROUP depending on ACTION.
-        ACTION can be 'add' or 'remove' otherwise 'remove' is assumed. '''
+        """Add or remove SELF.NAME to or from GROUP depending on ACTION.
+        ACTION can be 'add' or 'remove' otherwise 'remove' is assumed. """
         if action == 'add':
             option = '-a'
         else:
@@ -2538,8 +2546,8 @@ class DarwinUser(User):
         return (rc, out, err)
 
     def _modify_group(self):
-        '''Add or remove SELF.NAME to or from GROUP depending on ACTION.
-        ACTION can be 'add' or 'remove' otherwise 'remove' is assumed. '''
+        """Add or remove SELF.NAME to or from GROUP depending on ACTION.
+        ACTION can be 'add' or 'remove' otherwise 'remove' is assumed. """
 
         rc = 0
         out = ''
@@ -2570,9 +2578,9 @@ class DarwinUser(User):
         return (rc, out, err, changed)
 
     def _update_system_user(self):
-        '''Hide or show user on login window according SELF.SYSTEM.
+        """Hide or show user on login window according SELF.SYSTEM.
 
-        Returns 0 if a change has been made, None otherwise.'''
+        Returns 0 if a change has been made, None otherwise."""
 
         plist_file = '/Library/Preferences/com.apple.loginwindow.plist'
 
@@ -2611,14 +2619,14 @@ class DarwinUser(User):
                 return 0
 
     def user_exists(self):
-        '''Check is SELF.NAME is a known user on the system.'''
+        """Check is SELF.NAME is a known user on the system."""
         cmd = self._get_dscl()
         cmd += ['-read', '/Users/%s' % self.name, 'UniqueID']
         (rc, out, err) = self.execute_command(cmd, obey_checkmode=False)
         return rc == 0
 
     def remove_user(self):
-        '''Delete SELF.NAME. If SELF.FORCE is true, remove its home directory.'''
+        """Delete SELF.NAME. If SELF.FORCE is true, remove its home directory."""
         info = self.user_info()
 
         cmd = self._get_dscl()
@@ -3249,6 +3257,11 @@ class Alpine(BusyBox):
     distribution = 'Alpine'
 
 
+class Buildroot(BusyBox):
+    platform = 'Linux'
+    distribution = 'Buildroot'
+
+
 def main():
     ssh_defaults = dict(
         bits=0,

ansible/modules/validate_argument_spec.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: validate_argument_spec
 short_description: Validate role argument specs.
@@ -16,7 +16,8 @@ version_added: "2.11"
 options:
   argument_spec:
     description:
-        - A dictionary like AnsibleModule argument_spec. See R(argument spec definition,argument_spec).
+        - A dictionary like AnsibleModule argument_spec.
+        - See the C(options) parameter for the R(specification format,role_argument_spec).
     required: true
   provided_arguments:
     description:
@@ -46,9 +47,11 @@ attributes:
         support: none
     platform:
         platforms: all
-'''
+notes:
+    - It is unnecessary to call this module explicitly if the role contains an R(argument spec,role_argument_spec).
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: verify vars needed for this task file are present when included
   ansible.builtin.validate_argument_spec:
     argument_spec: '{{ required_data }}'
@@ -82,9 +85,9 @@ EXAMPLES = r'''
       vars:
         stuff: knows
         but: nobuts!
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 argument_errors:
   description: A list of arg validation errors.
   returned: failure
@@ -114,4 +117,4 @@ validate_args_context:
     type: role
     path: /home/user/roles/my_role/
     argument_spec_name: main
-'''
+"""