ansible-core 2.17.5rc1__py3-none-any.whl → 2.18.0rc1__py3-none-any.whl

ansible/plugins/filter/unique.yml

@@ -10,6 +10,13 @@ DOCUMENTATION:
       description: A list.
       type: list
       required: true
+    case_sensitive:
+      description: Whether to consider case when comparing elements.
+      default: false
+      type: bool
+    attribute:
+      description: Filter objects with unique values for this attribute.
+      type: str
   seealso:
     - plugin_type: filter
       plugin: ansible.builtin.difference
@@ -24,6 +31,27 @@ EXAMPLES: |
   # list1: [1, 2, 5, 1, 3, 4, 10]
   {{ list1 | unique }}
   # => [1, 2, 5, 3, 4, 10]
+
+  # return case sensitive unique elements
+  {{ ['a', 'A', 'a'] | unique(case_sensitive='true') }}
+  # => ['a', 'A']
+
+  # return case insensitive unique elements
+  {{ ['b', 'B', 'b'] | unique() }}
+  # => ['b']
+
+  # return unique elements of list based on attribute
+  # => [{"age": 12, "name": "a" }, { "age": 14, "name": "b"}]
+  - debug:
+      msg: "{{ sample | unique(attribute='age') }}"
+    vars:
+      sample:
+        - name: a
+          age: 12
+        - name: b
+          age: 14
+        - name: c
+          age: 14
 RETURN:
   _value:
     description: A list with unique elements, also known as a set.

ansible/plugins/inventory/script.py

@@ -130,7 +130,7 @@ EXAMPLES = r'''# fmt: code
         mandatory_options = arg_parser.add_mutually_exclusive_group()
         mandatory_options.add_argument('--list', action='store', nargs="*", help="Get inventory JSON from our API")
         mandatory_options.add_argument('--host', action='store',
-                                       help="Get variables for specific host, not used but kept for compatability")
+                                       help="Get variables for specific host, not used but kept for compatibility")
 
         try:
             config = load_config()

ansible/plugins/list.py

@@ -84,7 +84,7 @@ def _list_plugins_from_paths(ptype, dirs, collection, depth=0):
                                 to_native(b_ext) in C.REJECT_EXTS,       # general extensions to ignore
                                 b_ext in (b'.yml', b'.yaml', b'.json'),  # ignore docs files TODO: constant!
                                 plugin in IGNORE.get(bkey, ()),          # plugin in reject list
-                                os.path.islink(full_path),               # skip aliases, author should document in 'aliaes' field
+                                os.path.islink(full_path),               # skip aliases, author should document in 'aliases' field
                         ]):
                             continue
 

ansible/plugins/loader.py

@@ -1110,10 +1110,6 @@ class PluginLoader:
                 needs_enabled = False
                 if hasattr(obj, 'REQUIRES_ENABLED'):
                     needs_enabled = obj.REQUIRES_ENABLED
-                elif hasattr(obj, 'REQUIRES_WHITELIST'):
-                    needs_enabled = obj.REQUIRES_WHITELIST
-                    display.deprecated("The VarsModule class variable 'REQUIRES_WHITELIST' is deprecated. "
-                                       "Use 'REQUIRES_ENABLED' instead.", version=2.18)
                 if not needs_enabled:
                     # Use get_with_context to cache the plugin the first time we see it.
                     self.get_with_context(fqcn)[0]
@@ -1424,13 +1420,6 @@ def _load_plugin_filter():
         # Modules and action plugins share the same reject list since the difference between the
         # two isn't visible to the users
         if version == u'1.0':
-
-            if 'module_blacklist' in filter_data:
-                display.deprecated("'module_blacklist' is being removed in favor of 'module_rejectlist'", version='2.18')
-                if 'module_rejectlist' not in filter_data:
-                    filter_data['module_rejectlist'] = filter_data['module_blacklist']
-                del filter_data['module_blacklist']
-
             try:
                 filters['ansible.modules'] = frozenset(filter_data['module_rejectlist'])
             except TypeError:

ansible/plugins/lookup/config.py

@@ -8,7 +8,7 @@ DOCUMENTATION = """
     version_added: "2.5"
     short_description: Display the 'resolved' Ansible option values.
     description:
-      - Retrieves the value of an Ansible configuration setting, resolving all sources, from defaults, ansible.cfg, envirionmnet,
+      - Retrieves the value of an Ansible configuration setting, resolving all sources, from defaults, ansible.cfg, environment,
         CLI, and variables, but not keywords.
       - The values returned assume the context of the current host or C(inventory_hostname).
       - You can use C(ansible-config list) to see the global available settings, add C(-t all) to also show plugin options.

ansible/plugins/lookup/csvfile.py

@@ -52,18 +52,30 @@ EXAMPLES = """
 - name: msg="Match 'Li' on the first column, but return the 3rd column (columns start counting after the match)"
   ansible.builtin.debug: msg="The atomic mass of Lithium is {{ lookup('ansible.builtin.csvfile', 'Li file=elements.csv delimiter=, col=2') }}"
 
-- name: Define Values From CSV File, this reads file in one go, but you could also use col= to read each in it's own lookup.
+# Contents of bgp_neighbors.csv
+# 127.0.0.1,10.0.0.1,24,nones,lola,pepe,127.0.0.2
+# 128.0.0.1,10.1.0.1,20,notes,lolita,pepito,128.0.0.2
+# 129.0.0.1,10.2.0.1,23,nines,aayush,pepete,129.0.0.2
+
+- name: Define values from CSV file, this reads file in one go, but you could also use col= to read each in it's own lookup.
   ansible.builtin.set_fact:
-    loop_ip: "{{ csvline[0] }}"
-    int_ip: "{{ csvline[1] }}"
-    int_mask: "{{ csvline[2] }}"
-    int_name: "{{ csvline[3] }}"
-    local_as: "{{ csvline[4] }}"
-    neighbor_as: "{{ csvline[5] }}"
-    neigh_int_ip: "{{ csvline[6] }}"
+    '{{ columns[item|int] }}': "{{ csvline }}"
   vars:
-    csvline: "{{ lookup('ansible.builtin.csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
+    csvline: "{{ lookup('csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',', col=item) }}"
+    columns: ['loop_ip', 'int_ip', 'int_mask', 'int_name', 'local_as', 'neighbour_as', 'neight_int_ip']
+    bgp_neighbor_ip: '127.0.0.1'
+  loop: '{{ range(columns|length|int) }}'
   delegate_to: localhost
+  delegate_facts: true
+
+# Contents of people.csv
+# # Last,First,Email,Extension
+# Smith,Jane,jsmith@example.com,1234
+
+- name: Specify the column (by keycol) in which the string should be searched
+  assert:
+    that:
+    - lookup('ansible.builtin.csvfile', 'Jane', file='people.csv', delimiter=',', col=0, keycol=1) == "Smith"
 
 # Contents of debug.csv
 # test1 ret1.1 ret2.1

ansible/plugins/lookup/env.py

@@ -30,22 +30,21 @@ EXAMPLES = """
   ansible.builtin.debug:
     msg: "'{{ lookup('ansible.builtin.env', 'HOME') }}' is the HOME environment variable."
 
-- name: Before 2.13, how to set default value if the variable is not defined.
-        This cannot distinguish between USR undefined and USR=''.
+- name: Before 2.13, how to set default value if the variable is not defined
   ansible.builtin.debug:
-    msg: "{{ lookup('ansible.builtin.env', 'USR')|default('nobody', True) }} is the user."
+    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE') | default('World', True) }}"
 
-- name: Example how to set default value if the variable is not defined, ignores USR=''
+- name: Example how to set default value if the variable is not defined
   ansible.builtin.debug:
-    msg: "{{ lookup('ansible.builtin.env', 'USR', default='nobody') }} is the user."
+    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default='World') }}"
 
-- name: Set default value to Undefined, if the variable is not defined
+- name: Fail if the variable is not defined by setting default value to 'Undefined'
   ansible.builtin.debug:
-    msg: "{{ lookup('ansible.builtin.env', 'USR', default=Undefined) }} is the user."
+    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default=Undefined) }}"
 
-- name: Set default value to undef(), if the variable is not defined
+- name: Fail if the variable is not defined by setting default value to 'undef()'
   ansible.builtin.debug:
-    msg: "{{ lookup('ansible.builtin.env', 'USR', default=undef()) }} is the user."
+    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default=undef()) }}"
 """
 
 RETURN = """

ansible/plugins/lookup/ini.py

@@ -49,6 +49,12 @@ DOCUMENTATION = """
         default: False
         aliases: ['allow_none']
         version_added: '2.12'
+      interpolation:
+        description:
+          Allows for interpolation of values, see https://docs.python.org/3/library/configparser.html#configparser.BasicInterpolation
+        type: bool
+        default: True
+        version_added: '2.18'
     seealso:
       - ref: playbook_task_paths
         description: Search paths used for relative files.
@@ -140,7 +146,10 @@ class LookupModule(LookupBase):
         self.set_options(var_options=variables, direct=kwargs)
         paramvals = self.get_options()
 
-        self.cp = configparser.ConfigParser(allow_no_value=paramvals.get('allow_no_value', paramvals.get('allow_none')))
+        self.cp = configparser.ConfigParser(
+            allow_no_value=paramvals.get('allow_no_value', paramvals.get('allow_none')),
+            interpolation=configparser.BasicInterpolation() if paramvals.get('interpolation') else None,
+        )
         if paramvals['case_sensitive']:
             self.cp.optionxform = to_native
 

ansible/plugins/lookup/random_choice.py

@@ -31,7 +31,7 @@ RETURN = """
       - random item
     type: raw
 """
-import random
+import secrets
 
 from ansible.errors import AnsibleError
 from ansible.module_utils.common.text.converters import to_native
@@ -45,7 +45,7 @@ class LookupModule(LookupBase):
         ret = terms
         if terms:
             try:
-                ret = [random.choice(terms)]
+                ret = [secrets.choice(terms)]
             except Exception as e:
                 raise AnsibleError("Unable to choose random term: %s" % to_native(e))
 

ansible/plugins/lookup/url.py

@@ -103,8 +103,8 @@ options:
       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, will be removed in the future version) alias of V(none).
-      'yes': (DEPRECATED, will be removed in the future version) alias of V(all).
+      'no': (DEPRECATED, removed in 2.22) alias of V(none).
+      'yes': (DEPRECATED, removed in 2.22) alias of V(all).
   use_gssapi:
     description:
     - Use GSSAPI handler of requests
@@ -234,6 +234,11 @@ class LookupModule(LookupBase):
         ret = []
         for term in terms:
             display.vvvv("url lookup connecting to %s" % term)
+            if self.get_option('follow_redirects') in ('yes', 'no'):
+                display.deprecated(
+                    "Using 'yes' or 'no' for 'follow_redirects' parameter is deprecated.",
+                    version='2.22'
+                )
             try:
                 response = open_url(
                     term, validate_certs=self.get_option('validate_certs'),

ansible/plugins/shell/__init__.py

@@ -18,8 +18,8 @@ from __future__ import annotations
 
 import os
 import os.path
-import random
 import re
+import secrets
 import shlex
 import time
 
@@ -38,6 +38,9 @@ class ShellBase(AnsiblePlugin):
 
         super(ShellBase, self).__init__()
 
+        # Not used but here for backwards compatibility.
+        # ansible.posix.fish uses (but does not actually use) this value.
+        # https://github.com/ansible-collections/ansible.posix/blob/f41f08e9e3d3129e709e122540b5ae6bc19932be/plugins/shell/fish.py#L38-L39
         self.env = {}
         self.tmpdir = None
         self.executable = None
@@ -60,18 +63,6 @@ class ShellBase(AnsiblePlugin):
 
         super(ShellBase, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
 
-        # set env if needed, deal with environment's 'dual nature' list of dicts or dict
-        # TODO: config system should already resolve this so we should be able to just iterate over dicts
-        env = self.get_option('environment')
-        if isinstance(env, string_types):
-            raise AnsibleError('The "environment" keyword takes a list of dictionaries or a dictionary, not a string')
-        if not isinstance(env, Sequence):
-            env = [env]
-        for env_dict in env:
-            if not isinstance(env_dict, Mapping):
-                raise AnsibleError('The "environment" keyword takes a list of dictionaries (or single dictionary), but got a "%s" instead' % type(env_dict))
-            self.env.update(env_dict)
-
         # We can remove the try: except in the future when we make ShellBase a proper subset of
         # *all* shells.  Right now powershell and third party shells which do not use the
         # shell_common documentation fragment (and so do not have system_tmpdirs) will fail
@@ -82,7 +73,7 @@ class ShellBase(AnsiblePlugin):
 
     @staticmethod
     def _generate_temp_dir_name():
-        return 'ansible-tmp-%s-%s-%s' % (time.time(), os.getpid(), random.randint(0, 2**48))
+        return 'ansible-tmp-%s-%s-%s' % (time.time(), os.getpid(), secrets.randbelow(2**48))
 
     def env_prefix(self, **kwargs):
         return ' '.join(['%s=%s' % (k, self.quote(text_type(v))) for k, v in kwargs.items()])
@@ -101,23 +92,23 @@ class ShellBase(AnsiblePlugin):
     def chmod(self, paths, mode):
         cmd = ['chmod', mode]
         cmd.extend(paths)
-        return shlex.join(cmd)
+        return self.join(cmd)
 
     def chown(self, paths, user):
         cmd = ['chown', user]
         cmd.extend(paths)
-        return shlex.join(cmd)
+        return self.join(cmd)
 
     def chgrp(self, paths, group):
         cmd = ['chgrp', group]
         cmd.extend(paths)
-        return shlex.join(cmd)
+        return self.join(cmd)
 
     def set_user_facl(self, paths, user, mode):
         """Only sets acls for users as that's really all we need"""
         cmd = ['setfacl', '-m', 'u:%s:%s' % (user, mode)]
         cmd.extend(paths)
-        return shlex.join(cmd)
+        return self.join(cmd)
 
     def remove(self, path, recurse=False):
         path = self.quote(path)
@@ -138,7 +129,7 @@ class ShellBase(AnsiblePlugin):
         # other users can read and access the tmp directory.
         # This is because we use system to create tmp dirs for unprivileged users who are
         # sudo'ing to a second unprivileged user.
-        # The 'system_tmpdirs' setting defines dirctories we can use for this purpose
+        # The 'system_tmpdirs' setting defines directories we can use for this purpose
         # the default are, /tmp and /var/tmp.
         # So we only allow one of those locations if system=True, using the
         # passed in tmpdir if it is valid or the first one from the setting if not.
@@ -211,7 +202,7 @@ class ShellBase(AnsiblePlugin):
             arg_path,
         ]
 
-        cleaned_up_cmd = shlex.join(
+        cleaned_up_cmd = self.join(
             stripped_cmd_part for raw_cmd_part in cmd_parts
             if raw_cmd_part and (stripped_cmd_part := raw_cmd_part.strip())
         )
@@ -232,3 +223,7 @@ class ShellBase(AnsiblePlugin):
     def quote(self, cmd):
         """Returns a shell-escaped string that can be safely used as one token in a shell command line"""
         return shlex.quote(cmd)
+
+    def join(self, cmd_parts):
+        """Returns a shell-escaped string from a list that can be safely used in a shell command line"""
+        return shlex.join(cmd_parts)

ansible/plugins/shell/powershell.py

@@ -100,6 +100,8 @@ class ShellModule(ShellBase):
     # Family of shells this has.  Must match the filename without extension
     SHELL_FAMILY = 'powershell'
 
+    # We try catch as some connection plugins don't have a console (PSRP).
+    _CONSOLE_ENCODING = "try { [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding } catch {}"
     _SHELL_REDIRECT_ALLNULL = '> $null'
     _SHELL_AND = ';'
 
@@ -157,13 +159,14 @@ class ShellModule(ShellBase):
         if not basefile:
             basefile = self.__class__._generate_temp_dir_name()
         basefile = self._escape(self._unquote(basefile))
-        basetmpdir = tmpdir if tmpdir else self.get_option('remote_tmp')
+        basetmpdir = self._escape(tmpdir if tmpdir else self.get_option('remote_tmp'))
 
-        script = '''
-        $tmp_path = [System.Environment]::ExpandEnvironmentVariables('%s')
-        $tmp = New-Item -Type Directory -Path $tmp_path -Name '%s'
+        script = f'''
+        {self._CONSOLE_ENCODING}
+        $tmp_path = [System.Environment]::ExpandEnvironmentVariables('{basetmpdir}')
+        $tmp = New-Item -Type Directory -Path $tmp_path -Name '{basefile}'
         Write-Output -InputObject $tmp.FullName
-        ''' % (basetmpdir, basefile)
+        '''
         return self._encode_script(script.strip())
 
     def expand_user(self, user_home_path, username=''):
@@ -177,7 +180,7 @@ class ShellModule(ShellBase):
             script = "Write-Output ((Get-Location).Path + '%s')" % self._escape(user_home_path[1:])
         else:
             script = "Write-Output '%s'" % self._escape(user_home_path)
-        return self._encode_script(script)
+        return self._encode_script(f"{self._CONSOLE_ENCODING}; {script}")
 
     def exists(self, path):
         path = self._escape(self._unquote(path))

ansible/plugins/strategy/__init__.py

@@ -646,7 +646,7 @@ class StrategyBase:
                 for result_item in result_items:
                     if '_ansible_notify' in result_item and task_result.is_changed():
                         # only ensure that notified handlers exist, if so save the notifications for when
-                        # handlers are actually flushed so the last defined handlers are exexcuted,
+                        # handlers are actually flushed so the last defined handlers are executed,
                         # otherwise depending on the setting either error or warn
                         host_state = iterator.get_state_for_host(original_host.name)
                         for notification in result_item['_ansible_notify']:
@@ -926,6 +926,8 @@ class StrategyBase:
         meta_action = task.args.get('_raw_params')
 
         def _evaluate_conditional(h):
+            if not task.when:
+                return True
             all_vars = self._variable_manager.get_vars(play=iterator._play, host=h, task=task,
                                                        _hosts=self._hosts_cache, _hosts_all=self._hosts_cache_all)
             templar = Templar(loader=self._loader, variables=all_vars)
@@ -993,7 +995,7 @@ class StrategyBase:
             if _evaluate_conditional(target_host):
                 for host in self._inventory.get_hosts(iterator._play.hosts):
                     if host.name not in self._tqm._unreachable_hosts:
-                        iterator.set_run_state_for_host(host.name, IteratingStates.COMPLETE)
+                        iterator.end_host(host.name)
                 msg = "ending batch"
             else:
                 skipped = True
@@ -1002,7 +1004,7 @@ class StrategyBase:
             if _evaluate_conditional(target_host):
                 for host in self._inventory.get_hosts(iterator._play.hosts):
                     if host.name not in self._tqm._unreachable_hosts:
-                        iterator.set_run_state_for_host(host.name, IteratingStates.COMPLETE)
+                        iterator.end_host(host.name)
                         # end_play is used in PlaybookExecutor/TQM to indicate that
                         # the whole play is supposed to be ended as opposed to just a batch
                         iterator.end_play = True
@@ -1012,8 +1014,7 @@ class StrategyBase:
                 skip_reason += ', continuing play'
         elif meta_action == 'end_host':
             if _evaluate_conditional(target_host):
-                iterator.set_run_state_for_host(target_host.name, IteratingStates.COMPLETE)
-                iterator._play._removed_hosts.append(target_host.name)
+                iterator.end_host(target_host.name)
                 msg = "ending play for %s" % target_host.name
             else:
                 skipped = True
@@ -1021,13 +1022,23 @@ class StrategyBase:
                 # TODO: Nix msg here? Left for historical reasons, but skip_reason exists now.
                 msg = "end_host conditional evaluated to false, continuing execution for %s" % target_host.name
         elif meta_action == 'role_complete':
-            # Allow users to use this in a play as reported in https://github.com/ansible/ansible/issues/22286?
-            # How would this work with allow_duplicates??
             if task.implicit:
                 role_obj = self._get_cached_role(task, iterator._play)
                 if target_host.name in role_obj._had_task_run:
                     role_obj._completed[target_host.name] = True
                     msg = 'role_complete for %s' % target_host.name
+        elif meta_action == 'end_role':
+            if _evaluate_conditional(target_host):
+                while True:
+                    state, task = iterator.get_next_task_for_host(target_host, peek=True)
+                    if task.action in C._ACTION_META and task.args.get("_raw_params") == "role_complete":
+                        break
+                    iterator.set_state_for_host(target_host.name, state)
+                    display.debug("'%s' skipped because role has been ended via 'end_role'" % task)
+                msg = 'ending role %s for %s' % (task._role.get_name(), target_host.name)
+            else:
+                skipped = True
+                skip_reason += 'continuing role %s for %s' % (task._role.get_name(), target_host.name)
         elif meta_action == 'reset_connection':
             all_vars = self._variable_manager.get_vars(play=iterator._play, host=target_host, task=task,
                                                        _hosts=self._hosts_cache, _hosts_all=self._hosts_cache_all)

ansible/plugins/strategy/linear.py

@@ -34,7 +34,6 @@ from ansible.errors import AnsibleError, AnsibleAssertionError, AnsibleParserErr
 from ansible.module_utils.common.text.converters import to_text
 from ansible.playbook.handler import Handler
 from ansible.playbook.included_file import IncludedFile
-from ansible.playbook.task import Task
 from ansible.plugins.loader import action_loader
 from ansible.plugins.strategy import StrategyBase
 from ansible.template import Templar
@@ -51,12 +50,6 @@ class StrategyModule(StrategyBase):
         be a noop task to keep the iterator in lock step across
         all hosts.
         '''
-        noop_task = Task()
-        noop_task.action = 'meta'
-        noop_task.args['_raw_params'] = 'noop'
-        noop_task.implicit = True
-        noop_task.set_loader(iterator._play._loader)
-
         state_task_per_host = {}
         for host in hosts:
             state, task = iterator.get_next_task_for_host(host, peek=True)
@@ -64,7 +57,7 @@ class StrategyModule(StrategyBase):
                 state_task_per_host[host] = state, task
 
         if not state_task_per_host:
-            return [(h, None) for h in hosts]
+            return []
 
         task_uuids = {t._uuid for s, t in state_task_per_host.values()}
         _loop_cnt = 0
@@ -90,8 +83,6 @@ class StrategyModule(StrategyBase):
             if cur_task._uuid == task._uuid:
                 iterator.set_state_for_host(host.name, state)
                 host_tasks.append((host, task))
-            else:
-                host_tasks.append((host, noop_task))
 
         if cur_task.action in C._ACTION_META and cur_task.args.get('_raw_params') == 'flush_handlers':
             iterator.all_tasks[iterator.cur_task:iterator.cur_task] = [h for b in iterator._play.handlers for h in b.block]
@@ -133,9 +124,6 @@ class StrategyModule(StrategyBase):
 
                 results = []
                 for (host, task) in host_tasks:
-                    if not task:
-                        continue
-
                     if self._tqm._terminated:
                         break
 

ansible/plugins/test/core.py

@@ -25,8 +25,9 @@ from collections.abc import MutableMapping, MutableSequence
 from ansible.module_utils.compat.version import LooseVersion, StrictVersion
 
 from ansible import errors
-from ansible.module_utils.common.text.converters import to_native, to_text
+from ansible.module_utils.common.text.converters import to_native, to_text, to_bytes
 from ansible.module_utils.parsing.convert_bool import boolean
+from ansible.parsing.vault import is_encrypted_file
 from ansible.utils.display import Display
 from ansible.utils.version import SemanticVersion
 
@@ -39,6 +40,13 @@ except ImportError:
 display = Display()
 
 
+def timedout(result):
+    ''' Test if task result yields a time out'''
+    if not isinstance(result, MutableMapping):
+        raise errors.AnsibleFilterError("The 'timedout' test expects a dictionary")
+    return result.get('timedout', False) and result['timedout'].get('period', False)
+
+
 def failed(result):
     ''' Test if task result yields failed '''
     if not isinstance(result, MutableMapping):
@@ -143,6 +151,18 @@ def vault_encrypted(value):
     return getattr(value, '__ENCRYPTED__', False) and value.is_encrypted()
 
 
+def vaulted_file(value):
+    """Evaluate whether a file is a vault
+
+    .. versionadded:: 2.18
+    """
+    try:
+        with open(to_bytes(value), 'rb') as f:
+            return is_encrypted_file(f)
+    except (OSError, IOError) as e:
+        raise errors.AnsibleFilterError(f"Cannot test if the file {value} is a vault", orig_exc=e)
+
+
 def match(value, pattern='', ignorecase=False, multiline=False):
     ''' Perform a `re.match` returning a boolean '''
     return regex(value, pattern, ignorecase, multiline, 'match')
@@ -250,6 +270,7 @@ class TestModule(object):
             'successful': success,
             'reachable': reachable,
             'unreachable': unreachable,
+            'timedout': timedout,
 
             # changed testing
             'changed': changed,
@@ -282,4 +303,5 @@ class TestModule(object):
 
             # vault
             'vault_encrypted': vault_encrypted,
+            'vaulted_file': vaulted_file,
         }

ansible/plugins/test/issubset.yml

@@ -19,7 +19,7 @@ DOCUMENTATION:
       required: True
 EXAMPLES: |
   big: [1,2,3,4,5]
-  sml: [3,4]
+  small: [3,4]
   issmallinbig: '{{ small is subset(big) }}'
 RETURN:
   _value:

ansible/plugins/test/subset.yml

@@ -19,7 +19,7 @@ DOCUMENTATION:
       required: True
 EXAMPLES: |
   big: [1,2,3,4,5]
-  sml: [3,4]
+  small: [3,4]
   issmallinbig: '{{ small is subset(big) }}'
 RETURN:
   _value:

ansible/plugins/test/timedout.yml

@@ -0,0 +1,20 @@
+DOCUMENTATION:
+  name: timedout
+  author: Ansible Core
+  version_added: "2.18"
+  short_description: did the task time out
+  description:
+    - Tests if task finished ended due to a time out
+  options:
+    _input:
+      description: registered result from an Ansible task
+      type: dictionary
+      required: True
+EXAMPLES: |
+  # test 'status' to know how to respond
+  {{ taskresults is timedout }}
+
+RETURN:
+  _value:
+    description: A dictionary with 2 keys 'frame' showing the 'frame of code' in which the timeout occurred and 'period' with the time limit that was enforced.
+    type: dict

ansible/plugins/test/vault_encrypted.yml

@@ -1,18 +1,18 @@
 DOCUMENTATION:
-  name: truthy
+  name: vault_encrypted
   author: Ansible Core
   version_added: "2.10"
-  short_description: Is this an encrypted vault
+  short_description: Is this an encrypted vault string
   description:
-    - Verifies if the input is an Ansible vault.
+    - Verifies if the input string is an Ansible vault or not
   options:
     _input:
-      description: The possible vault.
+      description: The possible vault string
       type: string
       required: True
 EXAMPLES: |
-    thisisfalse: '{{ "any string" is ansible_vault }}'
-    thisistrue: '{{ "$ANSIBLE_VAULT;1.2;AES256;dev...." is ansible_vault }}'
+    thisisfalse: '{{ "any string" is vault_encryped}}'
+    thisistrue: '{{ "$ANSIBLE_VAULT;1.2;AES256;dev...." is vault_encrypted}}'
 RETURN:
   _value:
     description: Returns V(True) if the input is a valid ansible vault, V(False) otherwise.

ansible/plugins/test/vaulted_file.yml

@@ -0,0 +1,19 @@
+DOCUMENTATION:
+  name: vaulted_file
+  author: Ansible Core
+  version_added: "2.18"
+  short_description: Is this file an encrypted vault
+  description:
+    - Verifies if the input path is an Ansible vault file.
+  options:
+    _input:
+      description: The path to the possible vault.
+      type: path
+      required: True
+EXAMPLES: |
+    thisisfalse: '{{ "/etc/hosts" is vaulted_file}}'
+    thisistrue: '{{ "/path/to/vaulted/file" is vaulted_file}}'
+RETURN:
+  _value:
+    description: Returns V(True) if the path is a valid ansible vault, V(False) otherwise.
+    type: boolean

ansible/release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.17.5rc1'
+__version__ = '2.18.0rc1'
 __author__ = 'Ansible, Inc.'
-__codename__ = "Gallows Pole"
+__codename__ = "Fool in the Rain"