ansible-core 2.18.4rc1__py3-none-any.whl → 2.19.0b1__py3-none-any.whl

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, urlsplit
+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'}
 
@@ -505,29 +505,8 @@ def write_file(module, dest, content, resp):
         os.remove(tmpsrc)
 
 
-def absolute_location(url, location):
-    """Attempts to create an absolute URL based on initial URL, and
-    next URL, specifically in the case of a ``Location`` header.
-    """
-
-    if '://' in location:
-        return location
-
-    elif location.startswith('/'):
-        parts = urlsplit(url)
-        base = url.replace(parts[2], '')
-        return '%s%s' % (base, location)
-
-    elif not location.startswith('/'):
-        base = os.path.dirname(url)
-        return '%s/%s' % (base, location)
-
-    else:
-        return location
-
-
 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
 
@@ -541,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
 
@@ -579,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(
@@ -605,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']),
@@ -691,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'
@@ -732,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:
@@ -766,7 +752,7 @@ def main():
         uresp[ukey] = value
 
     if 'location' in uresp:
-        uresp['location'] = absolute_location(url, uresp['location'])
+        uresp['location'] = urljoin(url, uresp['location'])
 
     # Default content_encoding to try
     if isinstance(content, binary_type):

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,10 +486,11 @@ uid:
   returned: When O(uid) is passed to the module
   type: int
   sample: 1044
-'''
+"""
 
 
 import ctypes.util
+from datetime import datetime
 import grp
 import calendar
 import os
@@ -502,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):
@@ -1091,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():
@@ -1279,11 +1280,16 @@ class User(object):
                                      env=env)
                 out_buffer = b''
                 err_buffer = b''
+                first_prompt = b'Enter passphrase'
+                second_prompt = b'Enter same passphrase again'
+                prompt = first_prompt
+                start = datetime.now()
+                timeout = 900
                 while p.poll() is None:
                     r_list = select.select([master_out_fd, master_err_fd], [], [], 1)[0]
-                    first_prompt = b'Enter passphrase (empty for no passphrase):'
-                    second_prompt = b'Enter same passphrase again'
-                    prompt = first_prompt
+                    now = datetime.now()
+                    if (now - start).seconds > timeout:
+                        return (1, '', f'Timeout after {timeout} while reading passphrase for SSH key')
                     for fd in r_list:
                         if fd == master_out_fd:
                             chunk = os.read(master_out_fd, 10240)
@@ -1370,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:
@@ -2436,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)
@@ -2456,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)
@@ -2485,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/
@@ -2507,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:
@@ -2518,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:
@@ -2532,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 = ''
@@ -2564,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'
 
@@ -2605,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()
@@ -3243,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
-'''
+"""

ansible/modules/wait_for.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: wait_for
 short_description: Waits for a condition before continuing
@@ -120,9 +120,9 @@ author:
     - Jeroen Hoekx (@jhoekx)
     - John Jarvis (@jarv)
     - Andrii Radyk (@AnderEnder)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Sleep for 300 seconds and continue with play
   ansible.builtin.wait_for:
     timeout: 300
@@ -187,20 +187,22 @@ EXAMPLES = r'''
     host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
     search_regex: OpenSSH
     delay: 10
-  connection: local
+    timeout: 300
+  delegate_to: localhost
 
-# Same as above but you normally have ansible_connection set in inventory, which overrides 'connection'
+# Same as above but using config lookup for the target,
+# most plugins use 'remote_addr', but ssh uses 'host'
 - name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
   ansible.builtin.wait_for:
     port: 22
-    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
+    host: "{{ lookup('config', 'host', plugin_name='ssh', plugin_type='connection') }}"
     search_regex: OpenSSH
     delay: 10
-  vars:
-    ansible_connection: local
-'''
+    timeout: 300
+  delegate_to: localhost
+"""
 
-RETURN = r'''
+RETURN = r"""
 elapsed:
   description: The number of seconds that elapsed while waiting
   returned: always
@@ -220,11 +222,10 @@ match_groupdict:
     {
       'group': 'match'
     }
-'''
+"""
 
 import binascii
 import contextlib
-import datetime
 import errno
 import math
 import mmap
@@ -233,12 +234,12 @@ import re
 import select
 import socket
 import time
-import traceback
+
+from datetime import datetime, timedelta, timezone
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.sys_info import get_platform_subclass
 from ansible.module_utils.common.text.converters import to_bytes, to_native
-from ansible.module_utils.compat.datetime import utcnow
 
 
 HAS_PSUTIL = False
@@ -247,8 +248,8 @@ try:
     import psutil
     HAS_PSUTIL = True
     # just because we can import it on Linux doesn't mean we will use it
-except ImportError:
-    PSUTIL_IMP_ERR = traceback.format_exc()
+except ImportError as ex:
+    PSUTIL_IMP_ERR = ex
 
 
 class TCPConnectionInfo(object):
@@ -532,7 +533,7 @@ def main():
         except Exception:
             module.fail_json(msg="unknown active_connection_state (%s) defined" % _connection_state, elapsed=0)
 
-    start = utcnow()
+    start = datetime.now(timezone.utc)
 
     if delay:
         time.sleep(delay)
@@ -541,9 +542,9 @@ def main():
         time.sleep(timeout)
     elif state in ['absent', 'stopped']:
         # first wait for the stop condition
-        end = start + datetime.timedelta(seconds=timeout)
+        end = start + timedelta(seconds=timeout)
 
-        while utcnow() < end:
+        while datetime.now(timezone.utc) < end:
             if path:
                 try:
                     if not os.access(b_path, os.F_OK):
@@ -560,7 +561,7 @@ def main():
             # Conditions not yet met, wait and try again
             time.sleep(module.params['sleep'])
         else:
-            elapsed = utcnow() - start
+            elapsed = datetime.now(timezone.utc) - start
             if port:
                 module.fail_json(msg=msg or "Timeout when waiting for %s:%s to stop." % (host, port), elapsed=elapsed.seconds)
             elif path:
@@ -568,15 +569,15 @@ def main():
 
     elif state in ['started', 'present']:
         # wait for start condition
-        end = start + datetime.timedelta(seconds=timeout)
-        while utcnow() < end:
+        end = start + timedelta(seconds=timeout)
+        while datetime.now(timezone.utc) < end:
             if path:
                 try:
                     os.stat(b_path)
                 except OSError as e:
                     # If anything except file not present, throw an error
                     if e.errno != 2:
-                        elapsed = utcnow() - start
+                        elapsed = datetime.now(timezone.utc) - start
                         module.fail_json(msg=msg or "Failed to stat %s, %s" % (path, e.strerror), elapsed=elapsed.seconds)
                     # file doesn't exist yet, so continue
                 else:
@@ -611,9 +612,11 @@ def main():
                     except IOError:
                         pass
             elif port:
-                alt_connect_timeout = math.ceil(_timedelta_total_seconds(end - utcnow()))
+                alt_connect_timeout = math.ceil(
+                    _timedelta_total_seconds(end - datetime.now(timezone.utc)),
+                )
                 try:
-                    s = socket.create_connection((host, port), min(connect_timeout, alt_connect_timeout))
+                    s = socket.create_connection((host, int(port)), min(connect_timeout, alt_connect_timeout))
                 except Exception:
                     # Failed to connect by connect_timeout. wait and try again
                     pass
@@ -622,8 +625,12 @@ def main():
                     if b_compiled_search_re:
                         b_data = b''
                         matched = False
-                        while utcnow() < end:
-                            max_timeout = math.ceil(_timedelta_total_seconds(end - utcnow()))
+                        while datetime.now(timezone.utc) < end:
+                            max_timeout = math.ceil(
+                                _timedelta_total_seconds(
+                                    end - datetime.now(timezone.utc),
+                                ),
+                            )
                             readable = select.select([s], [], [], max_timeout)[0]
                             if not readable:
                                 # No new data.  Probably means our timeout
@@ -667,7 +674,7 @@ def main():
 
         else:   # while-else
             # Timeout expired
-            elapsed = utcnow() - start
+            elapsed = datetime.now(timezone.utc) - start
             if port:
                 if search_regex:
                     module.fail_json(msg=msg or "Timeout when waiting for search string %s in %s:%s" % (search_regex, host, port), elapsed=elapsed.seconds)
@@ -681,19 +688,19 @@ def main():
 
     elif state == 'drained':
         # wait until all active connections are gone
-        end = start + datetime.timedelta(seconds=timeout)
+        end = start + timedelta(seconds=timeout)
         tcpconns = TCPConnectionInfo(module)
-        while utcnow() < end:
+        while datetime.now(timezone.utc) < end:
             if tcpconns.get_active_connections_count() == 0:
                 break
 
             # Conditions not yet met, wait and try again
             time.sleep(module.params['sleep'])
         else:
-            elapsed = utcnow() - start
+            elapsed = datetime.now(timezone.utc) - start
             module.fail_json(msg=msg or "Timeout when waiting for %s:%s to drain" % (host, port), elapsed=elapsed.seconds)
 
-    elapsed = utcnow() - start
+    elapsed = datetime.now(timezone.utc) - start
     module.exit_json(state=state, port=port, search_regex=search_regex, match_groups=match_groups, match_groupdict=match_groupdict, path=path,
                      elapsed=elapsed.seconds)