ansible-core 2.16.6__py3-none-any.whl → 2.17.0rc1__py3-none-any.whl

ansible/modules/expect.py

@@ -3,8 +3,7 @@
 # (c) 2015, Matt Martz <matt@sivel.net>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -38,9 +37,11 @@ options:
   responses:
     type: dict
     description:
-      - Mapping of expected string/regex and string to respond with. If the
-        response is a list, successive matches return successive
-        responses. List functionality is new in 2.1.
+      - Mapping of prompt regular expressions and corresponding answer(s).
+      - Each key in O(responses) is a Python regex U(https://docs.python.org/3/library/re.html#regular-expression-syntax).
+      - The value of each key is a string or list of strings.
+        If the value is a string and the prompt is encountered multiple times, the answer will be repeated.
+        Provide the value as a list to give different answers for successive matches.
     required: true
   timeout:
     type: raw
@@ -69,15 +70,10 @@ notes:
   - If you want to run a command through the shell (say you are using C(<),
     C(>), C(|), and so on), you must specify a shell in the command such as
     C(/bin/bash -c "/path/to/something | grep else").
-  - The question, or key, under O(responses) is a python regex match. Case
-    insensitive searches are indicated with a prefix of C(?i).
+  - Case insensitive searches are indicated with a prefix of C(?i).
   - The C(pexpect) library used by this module operates with a search window
     of 2000 bytes, and does not use a multiline regex match. To perform a
     start of line bound match, use a pattern like ``(?m)^pattern``
-  - By default, if a question is encountered multiple times, its string
-    response will be repeated. If you need different responses for successive
-    question matches, instead of a string response, use a list of strings as
-    the response. The list functionality is new in 2.1.
   - The M(ansible.builtin.expect) module is designed for simple scenarios.
     For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
     or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).
@@ -98,14 +94,28 @@ EXAMPLES = r'''
   # you don't want to show passwords in your logs
   no_log: true
 
-- name: Generic question with multiple different responses
+- name: Match multiple regular expressions and demonstrate individual and repeated responses
   ansible.builtin.expect:
     command: /path/to/custom/command
     responses:
       Question:
+        # give a unique response for each of the 3 hypothetical prompts matched
         - response1
         - response2
         - response3
+      # give the same response for every matching prompt
+      "^Match another prompt$": "response"
+
+- name: Multiple questions with responses
+  ansible.builtin.expect:
+    command: /path/to/custom/command
+    responses:
+        "Please provide your name":
+            - "Anna"
+        "Database user":
+            - "{{ db_username }}"
+        "Database password":
+            - "{{ db_password }}"
 '''
 
 import datetime
@@ -167,9 +177,7 @@ def main():
         try:
             timeout = check_type_int(timeout)
         except TypeError as te:
-            module.fail_json(
-                msg="argument 'timeout' is of type {timeout_type} and we were unable to convert to int: {te}".format(timeout_type=type(timeout), te=te)
-            )
+            module.fail_json(msg=f"argument 'timeout' is of type {type(timeout)} and we were unable to convert to int: {te}")
     echo = module.params['echo']
 
     events = dict()

ansible/modules/fail.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/fetch.py

@@ -5,8 +5,7 @@
 
 # This is a virtual module that is entirely implemented as an action plugin and runs on the controller
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/file.py

@@ -4,8 +4,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -66,7 +65,7 @@ options:
     - >
       Force the creation of the symlinks in two cases: the source file does
       not exist (but will appear later); the destination exists and is a file (so, we need to unlink the
-      O(path) file and create symlink to the O(src) file in place of it).
+      O(path) file and create a symlink to the O(src) file in place of it).
     type: bool
     default: no
   follow:
@@ -74,6 +73,8 @@ options:
     - This flag indicates that filesystem links, if they exist, should be followed.
     - O(follow=yes) and O(state=link) can modify O(src) when combined with parameters such as O(mode).
     - Previous to Ansible 2.5, this was V(false) by default.
+    - While creating a symlink with a non-existent destination, set O(follow) to V(false) to avoid a warning message related to permission issues.
+      The warning message is added to notify the user that we can not set permissions to the non-existent destination.
     type: bool
     default: yes
     version_added: '1.8'

ansible/modules/find.py

@@ -6,8 +6,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -150,6 +149,11 @@ options:
             - Default is unlimited depth.
         type: int
         version_added: "2.6"
+    encoding:
+        description:
+            - When doing a C(contains) search, determine the encoding of the files to be searched.
+        type: str
+        version_added: "2.17"
 extends_documentation_fragment: action_common_attributes
 attributes:
     check_mode:
@@ -339,11 +343,12 @@ def sizefilter(st, size):
     return False
 
 
-def contentfilter(fsname, pattern, read_whole_file=False):
+def contentfilter(fsname, pattern, encoding, read_whole_file=False):
     """
     Filter files which contain the given expression
     :arg fsname: Filename to scan for lines matching a pattern
     :arg pattern: Pattern to look for inside of line
+    :arg encoding: Encoding of the file to be scanned
     :arg read_whole_file: If true, the whole file is read into memory before the regex is applied against it. Otherwise, the regex is applied line-by-line.
     :rtype: bool
     :returns: True if one of the lines in fsname matches the pattern. Otherwise False
@@ -354,7 +359,7 @@ def contentfilter(fsname, pattern, read_whole_file=False):
     prog = re.compile(pattern)
 
     try:
-        with open(fsname) as f:
+        with open(fsname, encoding=encoding) as f:
             if read_whole_file:
                 return bool(prog.search(f.read()))
 
@@ -362,6 +367,13 @@ def contentfilter(fsname, pattern, read_whole_file=False):
                 if prog.match(line):
                     return True
 
+    except LookupError as e:
+        raise e
+    except UnicodeDecodeError as e:
+        if encoding is None:
+            encoding = 'None (default determined by the Python built-in function "open")'
+        msg = f'Failed to read the file {fsname} due to an encoding error. current encoding: {encoding}'
+        raise Exception(msg) from e
     except Exception:
         pass
 
@@ -455,6 +467,7 @@ def main():
             depth=dict(type='int'),
             mode=dict(type='raw'),
             exact_mode=dict(type='bool', default=True),
+            encoding=dict(type='str')
         ),
         supports_check_mode=True,
     )
@@ -567,7 +580,7 @@ def main():
                         if (pfilter(fsobj, params['patterns'], params['excludes'], params['use_regex']) and
                                 agefilter(st, now, age, params['age_stamp']) and
                                 sizefilter(st, size) and
-                                contentfilter(fsname, params['contains'], params['read_whole_file']) and
+                                contentfilter(fsname, params['contains'], params['encoding'], params['read_whole_file']) and
                                 mode_filter(st, params['mode'], params['exact_mode'], module)):
 
                             r.update(statinfo(st))

ansible/modules/gather_facts.py

@@ -2,8 +2,7 @@
 # Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''

ansible/modules/get_url.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -261,7 +260,7 @@ EXAMPLES = r'''
 
 - name: Download file from a file path
   ansible.builtin.get_url:
-    url: file:///tmp/afile.txt
+    url: file:///tmp/a_file.txt
     dest: /tmp/afilecopy.txt
 
 - name: < Fetch file that requires authentication.

ansible/modules/getent.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2014, Brian Coca <brian.coca+dev@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -110,7 +109,7 @@ ansible_facts:
       description:
         - A list of results or a single result as a list of the fields the db provides
         - The list elements depend on the database queried, see getent man page for the structure
-        - Starting at 2.11 it now returns multiple duplicate entries, previouslly it only returned the last one
+        - Starting at 2.11 it now returns multiple duplicate entries, previously it only returned the last one
       returned: always
       type: list
 '''

ansible/modules/git.py

@@ -3,8 +3,7 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -208,15 +207,18 @@ options:
         type: path
         version_added: "2.7"
 
-    gpg_whitelist:
+    gpg_allowlist:
         description:
            - A list of trusted GPG fingerprints to compare to the fingerprint of the
              GPG-signed commit.
            - Only used when O(verify_commit=yes).
            - Use of this feature requires Git 2.6+ due to its reliance on git's C(--raw) flag to C(verify-commit) and C(verify-tag).
+           - Alias O(gpg_allowlist) is added in version 2.17.
+           - Alias O(gpg_whitelist) is deprecated and will be removed in version 2.21.
         type: list
         elements: str
         default: []
+        aliases: [ gpg_whitelist ]
         version_added: "2.9"
 
 requirements:
@@ -568,7 +570,7 @@ def get_submodule_versions(git_path, module, dest, version='HEAD'):
 
 
 def clone(git_path, module, repo, dest, remote, depth, version, bare,
-          reference, refspec, git_version_used, verify_commit, separate_git_dir, result, gpg_whitelist, single_branch):
+          reference, refspec, git_version_used, verify_commit, separate_git_dir, result, gpg_allowlist, single_branch):
     ''' makes a new git repo if it does not already exist '''
     dest_dirname = os.path.dirname(dest)
     try:
@@ -635,7 +637,7 @@ def clone(git_path, module, repo, dest, remote, depth, version, bare,
         module.run_command(cmd, check_rc=True, cwd=dest)
 
     if verify_commit:
-        verify_commit_sign(git_path, module, dest, version, gpg_whitelist)
+        verify_commit_sign(git_path, module, dest, version, gpg_allowlist)
 
 
 def has_local_mods(module, git_path, dest, bare):
@@ -1016,7 +1018,7 @@ def set_remote_branch(git_path, module, dest, remote, version, depth):
         module.fail_json(msg="Failed to fetch branch from remote: %s" % version, stdout=out, stderr=err, rc=rc)
 
 
-def switch_version(git_path, module, dest, remote, version, verify_commit, depth, gpg_whitelist):
+def switch_version(git_path, module, dest, remote, version, verify_commit, depth, gpg_allowlist):
     cmd = ''
     if version == 'HEAD':
         branch = get_head_branch(git_path, module, dest, remote)
@@ -1052,26 +1054,26 @@ def switch_version(git_path, module, dest, remote, version, verify_commit, depth
                              stdout=out1, stderr=err1, rc=rc, cmd=cmd)
 
     if verify_commit:
-        verify_commit_sign(git_path, module, dest, version, gpg_whitelist)
+        verify_commit_sign(git_path, module, dest, version, gpg_allowlist)
 
     return (rc, out1, err1)
 
 
-def verify_commit_sign(git_path, module, dest, version, gpg_whitelist):
+def verify_commit_sign(git_path, module, dest, version, gpg_allowlist):
     if version in get_annotated_tags(git_path, module, dest):
         git_sub = "verify-tag"
     else:
         git_sub = "verify-commit"
     cmd = "%s %s %s" % (git_path, git_sub, version)
-    if gpg_whitelist:
+    if gpg_allowlist:
         cmd += " --raw"
     (rc, out, err) = module.run_command(cmd, cwd=dest)
     if rc != 0:
         module.fail_json(msg='Failed to verify GPG signature of commit/tag "%s"' % version, stdout=out, stderr=err, rc=rc)
-    if gpg_whitelist:
+    if gpg_allowlist:
         fingerprint = get_gpg_fingerprint(err)
-        if fingerprint not in gpg_whitelist:
-            module.fail_json(msg='The gpg_whitelist does not include the public key "%s" for this commit' % fingerprint, stdout=out, stderr=err, rc=rc)
+        if fingerprint not in gpg_allowlist:
+            module.fail_json(msg='The gpg_allowlist does not include the public key "%s" for this commit' % fingerprint, stdout=out, stderr=err, rc=rc)
     return (rc, out, err)
 
 
@@ -1184,7 +1186,16 @@ def main():
             clone=dict(default='yes', type='bool'),
             update=dict(default='yes', type='bool'),
             verify_commit=dict(default='no', type='bool'),
-            gpg_whitelist=dict(default=[], type='list', elements='str'),
+            gpg_allowlist=dict(
+                default=[], type='list', aliases=['gpg_whitelist'], elements='str',
+                deprecated_aliases=[
+                    dict(
+                        name='gpg_whitelist',
+                        version='2.21',
+                        collection_name='ansible.builtin',
+                    )
+                ],
+            ),
             accept_hostkey=dict(default='no', type='bool'),
             accept_newhostkey=dict(default='no', type='bool'),
             key_file=dict(default=None, type='path', required=False),
@@ -1215,7 +1226,7 @@ def main():
     allow_clone = module.params['clone']
     bare = module.params['bare']
     verify_commit = module.params['verify_commit']
-    gpg_whitelist = module.params['gpg_whitelist']
+    gpg_allowlist = module.params['gpg_allowlist']
     reference = module.params['reference']
     single_branch = module.params['single_branch']
     git_path = module.params['executable'] or module.get_bin_path('git', True)
@@ -1264,7 +1275,7 @@ def main():
     # We screenscrape a huge amount of git commands so use C locale anytime we
     # call run_command()
     locale = get_best_parsable_locale(module)
-    module.run_command_environ_update = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale)
+    module.run_command_environ_update = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale, LANGUAGE=locale)
 
     if separate_git_dir:
         separate_git_dir = os.path.realpath(separate_git_dir)
@@ -1322,7 +1333,7 @@ def main():
             module.exit_json(**result)
         # there's no git config, so clone
         clone(git_path, module, repo, dest, remote, depth, version, bare, reference,
-              refspec, git_version_used, verify_commit, separate_git_dir, result, gpg_whitelist, single_branch)
+              refspec, git_version_used, verify_commit, separate_git_dir, result, gpg_allowlist, single_branch)
     elif not update:
         # Just return having found a repo already in the dest path
         # this does no checking that the repo is the actual repo
@@ -1377,7 +1388,7 @@ def main():
     # switch to version specified regardless of whether
     # we got new revisions from the repository
     if not bare:
-        switch_version(git_path, module, dest, remote, version, verify_commit, depth, gpg_whitelist)
+        switch_version(git_path, module, dest, remote, version, verify_commit, depth, gpg_allowlist)
 
     # Deal with submodules
     submodules_updated = False

ansible/modules/group.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Stephen Fromm <sfromm@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''

ansible/modules/group_by.py

@@ -4,8 +4,7 @@
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/hostname.py

@@ -4,8 +4,7 @@
 # Copyright: (c) 2013, Hiroaki Nakamura <hnakamur@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -82,7 +81,6 @@ from ansible.module_utils.common.sys_info import get_platform_subclass
 from ansible.module_utils.facts.system.service_mgr import ServiceMgrFactCollector
 from ansible.module_utils.facts.utils import get_file_lines, get_file_content
 from ansible.module_utils.common.text.converters import to_native, to_text
-from ansible.module_utils.six import PY3, text_type
 
 STRATS = {
     'alpine': 'Alpine',
@@ -533,21 +531,6 @@ class DarwinStrategy(BaseStrategy):
         self.name_types = ('HostName', 'ComputerName', 'LocalHostName')
         self.scrubbed_name = self._scrub_hostname(self.module.params['name'])
 
-    def _make_translation(self, replace_chars, replacement_chars, delete_chars):
-        if PY3:
-            return str.maketrans(replace_chars, replacement_chars, delete_chars)
-
-        if not isinstance(replace_chars, text_type) or not isinstance(replacement_chars, text_type):
-            raise ValueError('replace_chars and replacement_chars must both be strings')
-        if len(replace_chars) != len(replacement_chars):
-            raise ValueError('replacement_chars must be the same length as replace_chars')
-
-        table = dict(zip((ord(c) for c in replace_chars), replacement_chars))
-        for char in delete_chars:
-            table[ord(char)] = None
-
-        return table
-
     def _scrub_hostname(self, name):
         """
         LocalHostName only accepts valid DNS characters while HostName and ComputerName
@@ -559,7 +542,7 @@ class DarwinStrategy(BaseStrategy):
         name = to_text(name)
         replace_chars = u'\'"~`!@#$%^&*(){}[]/=?+\\|-_ '
         delete_chars = u".'"
-        table = self._make_translation(replace_chars, u'-' * len(replace_chars), delete_chars)
+        table = str.maketrans(replace_chars, '-' * len(replace_chars), delete_chars)
         name = name.translate(table)
 
         # Replace multiple dashes with a single dash

ansible/modules/import_playbook.py

@@ -3,8 +3,7 @@
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/import_role.py

@@ -2,8 +2,7 @@
 # Copyright: Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -56,6 +55,14 @@ options:
     type: bool
     default: yes
     version_added: '2.11'
+  public:
+    description:
+      - This option dictates whether the role's C(vars) and C(defaults) are exposed to the play.
+      - Variables are exposed to the play at playbook parsing time, and available to earlier roles and tasks as well unlike C(include_role).
+      - The default depends on the configuration option :ref:`default_private_role_vars`.
+    type: bool
+    default: yes
+    version_added: '2.17'
 extends_documentation_fragment:
     - action_common_attributes
     - action_common_attributes.conn

ansible/modules/import_tasks.py

@@ -3,8 +3,7 @@
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/include_role.py

@@ -3,8 +3,7 @@
 # Copyright: Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/include_tasks.py

@@ -3,8 +3,7 @@
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/include_vars.py

@@ -2,8 +2,7 @@
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''