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

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
@@ -76,6 +76,8 @@ options:
     description:
       - Can be used to match a string in either a file or a socket connection.
       - Defaults to a multiline regex.
+      - When inspecting a system log file and a static string, remember that Ansible by default logs its own actions there;
+        see the notes and examples for information.
     type: str
     version_added: "1.4"
   exclude_hosts:
@@ -105,13 +107,13 @@ attributes:
     platform:
         platforms: posix
 notes:
-  - The ability to use search_regex with a port connection was added in Ansible 1.7.
-  - Prior to Ansible 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
-  - Prior to Ansible 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
   - Under some circumstances when using mandatory access control, a path may always be treated as being absent even if it exists, but
     can't be modified or created by the remote user either.
   - When waiting for a path, symbolic links will be followed.  Many other modules that manipulate files do not follow symbolic links,
     so operations on the path using other modules may not work exactly as expected.
+  - When searching a static string within a system log file, it is important to account for potential self-matching against log entries
+    generated by the Ansible modules.  To prevent this, add a regular expression construct into the search string. For example, to match
+    a literal string 'this thing', one could use a regular expression like 'this t[h]ing'.
 seealso:
 - module: ansible.builtin.wait_for_connection
 - module: ansible.windows.win_wait_for
@@ -120,9 +122,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
@@ -156,6 +158,11 @@ EXAMPLES = r'''
     path: /tmp/foo
     search_regex: completed
 
+- name: Wait until the string "tomcat up" is in syslog, use regex character set to avoid self match
+  ansible.builtin.wait_for:
+    path: /var/log/syslog
+    search_regex: 'tomcat [u]p'
+
 - name: Wait until regex pattern matches in the file /tmp/foo and print the matched group
   ansible.builtin.wait_for:
     path: /tmp/foo
@@ -200,9 +207,9 @@ EXAMPLES = r'''
     delay: 10
     timeout: 300
   delegate_to: localhost
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 elapsed:
   description: The number of seconds that elapsed while waiting
   returned: always
@@ -222,11 +229,10 @@ match_groupdict:
     {
       'group': 'match'
     }
-'''
+"""
 
 import binascii
 import contextlib
-import datetime
 import errno
 import math
 import mmap
@@ -235,12 +241,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
@@ -249,8 +255,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):
@@ -381,31 +387,29 @@ class LinuxTCPConnectionInfo(TCPConnectionInfo):
             if not os.path.isfile(self.source_file[family]):
                 continue
             try:
-                f = open(self.source_file[family])
-                for tcp_connection in f.readlines():
-                    tcp_connection = tcp_connection.strip().split()
-                    if tcp_connection[self.local_address_field] == 'local_address':
-                        continue
-                    if (tcp_connection[self.connection_state_field] not in
-                            [get_connection_state_id(_connection_state) for _connection_state in self.module.params['active_connection_states']]):
-                        continue
-                    (local_ip, local_port) = tcp_connection[self.local_address_field].split(':')
-                    if self.port != local_port:
-                        continue
-                    (remote_ip, remote_port) = tcp_connection[self.remote_address_field].split(':')
-                    if (family, remote_ip) in self.exclude_ips:
-                        continue
-                    if any((
-                        (family, local_ip) in self.ips,
-                        (family, self.match_all_ips[family]) in self.ips,
-                        local_ip.startswith(self.ipv4_mapped_ipv6_address['prefix']) and
-                            (family, self.ipv4_mapped_ipv6_address['match_all']) in self.ips,
-                    )):
-                        active_connections += 1
-            except IOError as e:
+                with open(self.source_file[family]) as f:
+                    for tcp_connection in f.readlines():
+                        tcp_connection = tcp_connection.strip().split()
+                        if tcp_connection[self.local_address_field] == 'local_address':
+                            continue
+                        if (tcp_connection[self.connection_state_field] not in
+                                [get_connection_state_id(_connection_state) for _connection_state in self.module.params['active_connection_states']]):
+                            continue
+                        (local_ip, local_port) = tcp_connection[self.local_address_field].split(':')
+                        if self.port != local_port:
+                            continue
+                        (remote_ip, remote_port) = tcp_connection[self.remote_address_field].split(':')
+                        if (family, remote_ip) in self.exclude_ips:
+                            continue
+                        if any((
+                            (family, local_ip) in self.ips,
+                            (family, self.match_all_ips[family]) in self.ips,
+                            local_ip.startswith(self.ipv4_mapped_ipv6_address['prefix']) and
+                                (family, self.ipv4_mapped_ipv6_address['match_all']) in self.ips,
+                        )):
+                            active_connections += 1
+            except OSError:
                 pass
-            finally:
-                f.close()
 
         return active_connections
 
@@ -534,7 +538,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)
@@ -543,14 +547,14 @@ 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):
                         break
-                except IOError:
+                except OSError:
                     break
             elif port:
                 try:
@@ -562,7 +566,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:
@@ -570,15 +574,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:
@@ -610,12 +614,14 @@ def main():
                                     break
                             except Exception as e:
                                 module.warn('wait_for failed on "%s", unexpected exception(%s): %s.).' % (path, to_native(e.__class__), to_native(e)))
-                    except IOError:
+                    except OSError:
                         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
@@ -624,8 +630,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
@@ -643,8 +653,8 @@ def main():
                         # Shutdown the client socket
                         try:
                             s.shutdown(socket.SHUT_RDWR)
-                        except socket.error as e:
-                            if e.errno != errno.ENOTCONN:
+                        except OSError as ex:
+                            if ex.errno != errno.ENOTCONN:
                                 raise
                         # else, the server broke the connection on its end, assume it's not ready
                         else:
@@ -656,8 +666,8 @@ def main():
                         # Connection established, success!
                         try:
                             s.shutdown(socket.SHUT_RDWR)
-                        except socket.error as e:
-                            if e.errno != errno.ENOTCONN:
+                        except OSError as ex:
+                            if ex.errno != errno.ENOTCONN:
                                 raise
                         # else, the server broke the connection on its end, assume it's not ready
                         else:
@@ -669,7 +679,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)
@@ -683,19 +693,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)
 

ansible/modules/wait_for_connection.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: wait_for_connection
 short_description: Waits until remote system is reachable/usable
@@ -62,9 +62,9 @@ seealso:
 - module: community.windows.win_wait_for_process
 author:
 - Dag Wieers (@dagwieers)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Wait 600 seconds for target connection to become reachable/usable
   ansible.builtin.wait_for_connection:
 
@@ -110,12 +110,12 @@ EXAMPLES = r'''
 
   - name: Gather facts for first time
     ansible.builtin.setup:
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 elapsed:
   description: The number of seconds that elapsed waiting for the connection to appear.
   returned: always
   type: float
   sample: 23.1
-'''
+"""

ansible/modules/yum_repository.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: yum_repository
 author: Jiri Tyr (@jtyr)
@@ -385,9 +385,9 @@ notes:
     on disk until you run C(yum clean all). Use a notification handler for this.
   - "The O(ignore:params) parameter was removed in Ansible 2.5 due to circumventing Ansible's parameter
     handling"
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Add repository
   ansible.builtin.yum_repository:
     name: epel
@@ -427,9 +427,9 @@ EXAMPLES = '''
     name: epel
     file: external_repos
     state: absent
-'''
+"""
 
-RETURN = '''
+RETURN = """
 repo:
     description: repository name
     returned: success
@@ -440,7 +440,7 @@ state:
     returned: success
     type: str
     sample: "present"
-'''
+"""
 
 import configparser
 import os
@@ -502,10 +502,11 @@ class YumRepo:
             try:
                 with open(self.dest, 'w') as fd:
                     self.repofile.write(fd)
-            except IOError as e:
+            except OSError as ex:
                 self.module.fail_json(
-                    msg=f"Problems handling file {self.dest}.",
-                    details=to_native(e),
+                    msg=f"Problems handling file {self.dest!r}.",
+                    details=str(ex),
+                    exception=ex,
                 )
         else:
             try:

ansible/parsing/ajson.py

@@ -1,40 +1,20 @@
 # Copyright: (c) 2018, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import annotations
-
-import json
-
-# Imported for backwards compat
-from ansible.module_utils.common.json import AnsibleJSONEncoder  # pylint: disable=unused-import
-
-from ansible.parsing.vault import VaultLib
-from ansible.parsing.yaml.objects import AnsibleVaultEncryptedUnicode
-from ansible.utils.unsafe_proxy import wrap_var
-
-
-class AnsibleJSONDecoder(json.JSONDecoder):
-
-    _vaults = {}  # type: dict[str, VaultLib]
-
-    def __init__(self, *args, **kwargs):
-        kwargs['object_hook'] = self.object_hook
-        super(AnsibleJSONDecoder, self).__init__(*args, **kwargs)
-
-    @classmethod
-    def set_secrets(cls, secrets):
-        cls._vaults['default'] = VaultLib(secrets=secrets)
-
-    def object_hook(self, pairs):
-        for key in pairs:
-            value = pairs[key]
-
-            if key == '__ansible_vault':
-                value = AnsibleVaultEncryptedUnicode(value)
-                if self._vaults:
-                    value.vault = self._vaults['default']
-                return value
-            elif key == '__ansible_unsafe':
-                return wrap_var(value)
-
-        return pairs
+from __future__ import annotations as _annotations
+
+# from ansible.utils.display import Display as _Display
+#
+#
+# deprecated: description='deprecate ajson' core_version='2.23'
+# _Display().deprecated(
+#     msg='The `ansible.parsing.ajson` module is deprecated.',
+#     version='2.27',
+#     help_text="",  # DTFIX-FUTURE: complete this help text
+# )
+
+# Imported for backward compat
+from ansible.module_utils.common.json import (  # pylint: disable=unused-import
+    _AnsibleJSONEncoder as AnsibleJSONEncoder,
+    _AnsibleJSONDecoder as AnsibleJSONDecoder,
+)