ansible-core 2.15.4rc1__py3-none-any.whl → 2.16.0b2__py3-none-any.whl

ansible/plugins/inventory/script.py

@@ -28,6 +28,8 @@ DOCUMENTATION = '''
     notes:
         - Enabled in configuration by default.
         - The plugin does not cache results because external inventory scripts are responsible for their own caching.
+        - To write your own inventory script see (R(Developing dynamic inventory,developing_inventory) from the documentation site.
+        - To find the scripts that used to be part of the code release, go to U(https://github.com/ansible-community/contrib-scripts/).
 '''
 
 import os
@@ -37,7 +39,7 @@ from collections.abc import Mapping
 
 from ansible.errors import AnsibleError, AnsibleParserError
 from ansible.module_utils.basic import json_dict_bytes_to_unicode
-from ansible.module_utils._text import to_native, to_text
+from ansible.module_utils.common.text.converters import to_native, to_text
 from ansible.plugins.inventory import BaseInventoryPlugin
 from ansible.utils.display import Display
 
@@ -187,7 +189,11 @@ class InventoryModule(BaseInventoryPlugin):
             sp = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
         except OSError as e:
             raise AnsibleError("problem running %s (%s)" % (' '.join(cmd), e))
-        (out, err) = sp.communicate()
+        (out, stderr) = sp.communicate()
+
+        if sp.returncode != 0:
+            raise AnsibleError("Inventory script (%s) had an execution error: %s" % (path, to_native(stderr)))
+
         if out.strip() == '':
             return {}
         try:

ansible/plugins/inventory/toml.py

@@ -94,7 +94,7 @@ from collections.abc import MutableMapping, MutableSequence
 from functools import partial
 
 from ansible.errors import AnsibleFileNotFound, AnsibleParserError, AnsibleRuntimeError
-from ansible.module_utils._text import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.module_utils.six import string_types, text_type
 from ansible.parsing.yaml.objects import AnsibleSequence, AnsibleUnicode
 from ansible.plugins.inventory import BaseFileInventoryPlugin

ansible/plugins/inventory/yaml.py

@@ -72,7 +72,7 @@ from collections.abc import MutableMapping
 
 from ansible.errors import AnsibleError, AnsibleParserError
 from ansible.module_utils.six import string_types
-from ansible.module_utils._text import to_native, to_text
+from ansible.module_utils.common.text.converters import to_native, to_text
 from ansible.plugins.inventory import BaseFileInventoryPlugin
 
 NoneType = type(None)

ansible/plugins/list.py

@@ -11,7 +11,7 @@ from ansible import context
 from ansible import constants as C
 from ansible.collections.list import list_collections
 from ansible.errors import AnsibleError
-from ansible.module_utils._text import to_native, to_bytes
+from ansible.module_utils.common.text.converters import to_native, to_bytes
 from ansible.plugins import loader
 from ansible.utils.display import Display
 from ansible.utils.collection_loader._collection_finder import _get_collection_path
@@ -171,28 +171,32 @@ def list_collection_plugins(ptype, collections, search_paths=None):
     return plugins
 
 
-def list_plugins(ptype, collection=None, search_paths=None):
+def list_plugins(ptype, collections=None, search_paths=None):
+    if isinstance(collections, str):
+        collections = [collections]
 
     # {plugin_name: (filepath, class), ...}
     plugins = {}
-    collections = {}
-    if collection is None:
+    plugin_collections = {}
+    if collections is None:
         # list all collections, add synthetic ones
-        collections['ansible.builtin'] = b''
-        collections['ansible.legacy'] = b''
-        collections.update(list_collections(search_paths=search_paths, dedupe=True))
-    elif collection == 'ansible.legacy':
-        # add builtin, since legacy also resolves to these
-        collections[collection] = b''
-        collections['ansible.builtin'] = b''
+        plugin_collections['ansible.builtin'] = b''
+        plugin_collections['ansible.legacy'] = b''
+        plugin_collections.update(list_collections(search_paths=search_paths, dedupe=True))
     else:
-        try:
-            collections[collection] = to_bytes(_get_collection_path(collection))
-        except ValueError as e:
-            raise AnsibleError("Cannot use supplied collection {0}: {1}".format(collection, to_native(e)), orig_exc=e)
+        for collection in collections:
+            if collection == 'ansible.legacy':
+                # add builtin, since legacy also resolves to these
+                plugin_collections[collection] = b''
+                plugin_collections['ansible.builtin'] = b''
+            else:
+                try:
+                    plugin_collections[collection] = to_bytes(_get_collection_path(collection))
+                except ValueError as e:
+                    raise AnsibleError("Cannot use supplied collection {0}: {1}".format(collection, to_native(e)), orig_exc=e)
 
-    if collections:
-        plugins.update(list_collection_plugins(ptype, collections))
+    if plugin_collections:
+        plugins.update(list_collection_plugins(ptype, plugin_collections))
 
     return plugins
 

ansible/plugins/loader.py

@@ -18,10 +18,14 @@ from collections import defaultdict, namedtuple
 from traceback import format_exc
 
 import ansible.module_utils.compat.typing as t
+
+from .filter import AnsibleJinja2Filter
+from .test import AnsibleJinja2Test
+
 from ansible import __version__ as ansible_version
 from ansible import constants as C
 from ansible.errors import AnsibleError, AnsiblePluginCircularRedirect, AnsiblePluginRemovedError, AnsibleCollectionUnsupportedVersionError
-from ansible.module_utils._text import to_bytes, to_text, to_native
+from ansible.module_utils.common.text.converters import to_bytes, to_text, to_native
 from ansible.module_utils.compat.importlib import import_module
 from ansible.module_utils.six import string_types
 from ansible.parsing.utils.yaml import from_yaml
@@ -1067,28 +1071,17 @@ class Jinja2Loader(PluginLoader):
     We need to do a few things differently in the base class because of file == plugin
     assumptions and dedupe logic.
     """
-    def __init__(self, class_name, package, config, subdir, aliases=None, required_base_class=None):
-
+    def __init__(self, class_name, package, config, subdir, plugin_wrapper_type, aliases=None, required_base_class=None):
         super(Jinja2Loader, self).__init__(class_name, package, config, subdir, aliases=aliases, required_base_class=required_base_class)
-        self._loaded_j2_file_maps = []
+        self._plugin_wrapper_type = plugin_wrapper_type
+        self._cached_non_collection_wrappers = {}
 
     def _clear_caches(self):
         super(Jinja2Loader, self)._clear_caches()
-        self._loaded_j2_file_maps = []
+        self._cached_non_collection_wrappers = {}
 
     def find_plugin(self, name, mod_type='', ignore_deprecated=False, check_aliases=False, collection_list=None):
-
-        # TODO: handle collection plugin find, see 'get_with_context'
-        # this can really 'find plugin file'
-        plugin = super(Jinja2Loader, self).find_plugin(name, mod_type=mod_type, ignore_deprecated=ignore_deprecated, check_aliases=check_aliases,
-                                                       collection_list=collection_list)
-
-        # if not found, try loading all non collection plugins and see if this in there
-        if not plugin:
-            all_plugins = self.all()
-            plugin = all_plugins.get(name, None)
-
-        return plugin
+        raise NotImplementedError('find_plugin is not supported on Jinja2Loader')
 
     @property
     def method_map_name(self):
@@ -1122,8 +1115,7 @@ class Jinja2Loader(PluginLoader):
         for func_name, func in plugin_map:
             fq_name = '.'.join((collection, func_name))
             full = '.'.join((full_name, func_name))
-            pclass = self._load_jinja2_class()
-            plugin = pclass(func)
+            plugin = self._plugin_wrapper_type(func)
             if plugin in plugins:
                 continue
             self._update_object(plugin, full, plugin_path, resolved=fq_name)
@@ -1131,27 +1123,28 @@ class Jinja2Loader(PluginLoader):
 
         return plugins
 
+    # FUTURE: now that the resulting plugins are closer, refactor base class method with some extra
+    # hooks so we can avoid all the duplicated plugin metadata logic, and also cache the collection results properly here
     def get_with_context(self, name, *args, **kwargs):
-
-        # found_in_cache = True
-        class_only = kwargs.pop('class_only', False)  # just pop it, dont want to pass through
-        collection_list = kwargs.pop('collection_list', None)
+        # pop N/A kwargs to avoid passthrough to parent methods
+        kwargs.pop('class_only', False)
+        kwargs.pop('collection_list', None)
 
         context = PluginLoadContext()
 
         # avoid collection path for legacy
         name = name.removeprefix('ansible.legacy.')
 
-        if '.' not in name:
-            # Filter/tests must always be FQCN except builtin and legacy
-            for known_plugin in self.all(*args, **kwargs):
-                if known_plugin.matches_name([name]):
-                    context.resolved = True
-                    context.plugin_resolved_name = name
-                    context.plugin_resolved_path = known_plugin._original_path
-                    context.plugin_resolved_collection = 'ansible.builtin' if known_plugin.ansible_name.startswith('ansible.builtin.') else ''
-                    context._resolved_fqcn = known_plugin.ansible_name
-                    return get_with_context_result(known_plugin, context)
+        self._ensure_non_collection_wrappers(*args, **kwargs)
+
+        # check for stuff loaded via legacy/builtin paths first
+        if known_plugin := self._cached_non_collection_wrappers.get(name):
+            context.resolved = True
+            context.plugin_resolved_name = name
+            context.plugin_resolved_path = known_plugin._original_path
+            context.plugin_resolved_collection = 'ansible.builtin' if known_plugin.ansible_name.startswith('ansible.builtin.') else ''
+            context._resolved_fqcn = known_plugin.ansible_name
+            return get_with_context_result(known_plugin, context)
 
         plugin = None
         key, leaf_key = get_fqcr_and_name(name)
@@ -1237,14 +1230,10 @@ class Jinja2Loader(PluginLoader):
                     # use 'parent' loader class to find files, but cannot return this as it can contain
                     # multiple plugins per file
                     plugin_impl = super(Jinja2Loader, self).get_with_context(module_name, *args, **kwargs)
-                except Exception as e:
-                    raise KeyError(to_native(e))
-
-                try:
                     method_map = getattr(plugin_impl.object, self.method_map_name)
                     plugin_map = method_map().items()
                 except Exception as e:
-                    display.warning("Skipping %s plugins in '%s' as it seems to be invalid: %r" % (self.type, to_text(plugin_impl.object._original_path), e))
+                    display.warning(f"Skipping {self.type} plugins in {module_name}'; an error occurred while loading: {e}")
                     continue
 
                 for func_name, func in plugin_map:
@@ -1253,11 +1242,11 @@ class Jinja2Loader(PluginLoader):
                     # TODO: load  anyways into CACHE so we only match each at end of loop
                     #       the files themseves should already be cached by base class caching of modules(python)
                     if key in (func_name, fq_name):
-                        pclass = self._load_jinja2_class()
-                        plugin = pclass(func)
+                        plugin = self._plugin_wrapper_type(func)
                         if plugin:
                             context = plugin_impl.plugin_load_context
                             self._update_object(plugin, src_name, plugin_impl.object._original_path, resolved=fq_name)
+                            # FIXME: once we start caching these results, we'll be missing functions that would have loaded later
                             break  # go to next file as it can override if dupe (dont break both loops)
 
         except AnsiblePluginRemovedError as apre:
@@ -1272,8 +1261,7 @@ class Jinja2Loader(PluginLoader):
         return get_with_context_result(plugin, context)
 
     def all(self, *args, **kwargs):
-
-        # inputs, we ignore 'dedupe' we always do, used in base class to find files for this one
+        kwargs.pop('_dedupe', None)
         path_only = kwargs.pop('path_only', False)
         class_only = kwargs.pop('class_only', False)  # basically ignored for test/filters since they are functions
 
@@ -1281,9 +1269,19 @@ class Jinja2Loader(PluginLoader):
         if path_only and class_only:
             raise AnsibleError('Do not set both path_only and class_only when calling PluginLoader.all()')
 
-        found = set()
+        self._ensure_non_collection_wrappers(*args, **kwargs)
+        if path_only:
+            yield from (w._original_path for w in self._cached_non_collection_wrappers.values())
+        else:
+            yield from (w for w in self._cached_non_collection_wrappers.values())
+
+    def _ensure_non_collection_wrappers(self, *args, **kwargs):
+        if self._cached_non_collection_wrappers:
+            return
+
         # get plugins from files in configured paths (multiple in each)
-        for p_map in self._j2_all_file_maps(*args, **kwargs):
+        for p_map in super(Jinja2Loader, self).all(*args, **kwargs):
+            is_builtin = p_map.ansible_name.startswith('ansible.builtin.')
 
             # p_map is really object from file with class that holds multiple plugins
             plugins_list = getattr(p_map, self.method_map_name)
@@ -1294,57 +1292,35 @@ class Jinja2Loader(PluginLoader):
                 continue
 
             for plugin_name in plugins.keys():
-                if plugin_name in _PLUGIN_FILTERS[self.package]:
-                    display.debug("%s skipped due to a defined plugin filter" % plugin_name)
+                if '.' in plugin_name:
+                    display.debug(f'{plugin_name} skipped in {p_map._original_path}; Jinja plugin short names may not contain "."')
                     continue
 
-                if plugin_name in found:
-                    display.debug("%s skipped as duplicate" % plugin_name)
+                if plugin_name in _PLUGIN_FILTERS[self.package]:
+                    display.debug("%s skipped due to a defined plugin filter" % plugin_name)
                     continue
 
-                if path_only:
-                    result = p_map._original_path
-                else:
-                    # loader class is for the file with multiple plugins, but each plugin now has it's own class
-                    pclass = self._load_jinja2_class()
-                    result = pclass(plugins[plugin_name])  # if bad plugin, let exception rise
-                    found.add(plugin_name)
-                    fqcn = plugin_name
-                    collection = '.'.join(p_map.ansible_name.split('.')[:2]) if p_map.ansible_name.count('.') >= 2 else ''
-                    if not plugin_name.startswith(collection):
-                        fqcn = f"{collection}.{plugin_name}"
-
-                    self._update_object(result, plugin_name, p_map._original_path, resolved=fqcn)
-                yield result
-
-    def _load_jinja2_class(self):
-        """ override the normal method of plugin classname as these are used in the generic funciton
-            to access the 'multimap' of filter/tests to function, this is a 'singular' plugin for
-            each entry.
-        """
-        class_name = 'AnsibleJinja2%s' % get_plugin_class(self.class_name).capitalize()
-        module = __import__(self.package, fromlist=[class_name])
-
-        return getattr(module, class_name)
+                # the plugin class returned by the loader may host multiple Jinja plugins, but we wrap each plugin in
+                # its own surrogate wrapper instance here to ease the bookkeeping...
+                wrapper = self._plugin_wrapper_type(plugins[plugin_name])
+                fqcn = plugin_name
+                collection = '.'.join(p_map.ansible_name.split('.')[:2]) if p_map.ansible_name.count('.') >= 2 else ''
+                if not plugin_name.startswith(collection):
+                    fqcn = f"{collection}.{plugin_name}"
 
-    def _j2_all_file_maps(self, *args, **kwargs):
-        """
-        * Unlike other plugin types, file != plugin, a file can contain multiple plugins (of same type).
-          This is why we do not deduplicate ansible file names at this point, we mostly care about
-          the names of the actual jinja2 plugins which are inside of our files.
-        * This method will NOT fetch collection plugin files, only those that would be expected under 'ansible.builtin/legacy'.
-        """
-        # populate cache if needed
-        if not self._loaded_j2_file_maps:
+                self._update_object(wrapper, plugin_name, p_map._original_path, resolved=fqcn)
 
-            # We don't deduplicate ansible file names.
-            # Instead, calling code deduplicates jinja2 plugin names when loading each file.
-            kwargs['_dedupe'] = False
+                target_names = {plugin_name, fqcn}
+                if is_builtin:
+                    target_names.add(f'ansible.builtin.{plugin_name}')
 
-            # To match correct precedence, call base class' all() to get a list of files,
-            self._loaded_j2_file_maps = list(super(Jinja2Loader, self).all(*args, **kwargs))
+                for target_name in target_names:
+                    if existing_plugin := self._cached_non_collection_wrappers.get(target_name):
+                        display.debug(f'Jinja plugin {target_name} from {p_map._original_path} skipped; '
+                                      f'shadowed by plugin from {existing_plugin._original_path})')
+                        continue
 
-        return self._loaded_j2_file_maps
+                    self._cached_non_collection_wrappers[target_name] = wrapper
 
 
 def get_fqcr_and_name(resource, collection='ansible.builtin'):
@@ -1572,13 +1548,15 @@ filter_loader = Jinja2Loader(
     'ansible.plugins.filter',
     C.DEFAULT_FILTER_PLUGIN_PATH,
     'filter_plugins',
+    AnsibleJinja2Filter
 )
 
 test_loader = Jinja2Loader(
     'TestModule',
     'ansible.plugins.test',
     C.DEFAULT_TEST_PLUGIN_PATH,
-    'test_plugins'
+    'test_plugins',
+    AnsibleJinja2Test
 )
 
 strategy_loader = PluginLoader(

ansible/plugins/lookup/__init__.py

@@ -100,7 +100,7 @@ class LookupBase(AnsiblePlugin):
         must be converted into python's unicode type as the strings will be run
         through jinja2 which has this requirement.  You can use::
 
-            from ansible.module_utils._text import to_text
+            from ansible.module_utils.common.text.converters import to_text
             result_string = to_text(result_string)
         """
         pass

ansible/plugins/lookup/config.py

@@ -33,6 +33,10 @@ DOCUMENTATION = """
         description: name of the plugin for which you want to retrieve configuration settings.
         type: string
         version_added: '2.12'
+      show_origin:
+        description: toggle the display of what configuration subsystem the value came from
+        type: bool
+        version_added: '2.16'
 """
 
 EXAMPLES = """
@@ -67,7 +71,8 @@ EXAMPLES = """
 RETURN = """
 _raw:
   description:
-    - value(s) of the key(s) in the config
+    - A list of value(s) of the key(s) in the config if show_origin is false (default)
+    - Optionally, a list of 2 element lists (value, origin) if show_origin is true
   type: raw
 """
 
@@ -75,7 +80,7 @@ import ansible.plugins.loader as plugin_loader
 
 from ansible import constants as C
 from ansible.errors import AnsibleError, AnsibleLookupError, AnsibleOptionsError
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.six import string_types
 from ansible.plugins.lookup import LookupBase
 from ansible.utils.sentinel import Sentinel
@@ -92,7 +97,7 @@ def _get_plugin_config(pname, ptype, config, variables):
         p = loader.get(pname, class_only=True)
         if p is None:
             raise AnsibleLookupError('Unable to load %s plugin "%s"' % (ptype, pname))
-        result = C.config.get_config_value(config, plugin_type=ptype, plugin_name=p._load_name, variables=variables)
+        result, origin = C.config.get_config_value_and_origin(config, plugin_type=ptype, plugin_name=p._load_name, variables=variables)
     except AnsibleLookupError:
         raise
     except AnsibleError as e:
@@ -101,7 +106,7 @@ def _get_plugin_config(pname, ptype, config, variables):
             raise MissingSetting(msg, orig_exc=e)
         raise e
 
-    return result
+    return result, origin
 
 
 def _get_global_config(config):
@@ -124,6 +129,7 @@ class LookupModule(LookupBase):
         missing = self.get_option('on_missing')
         ptype = self.get_option('plugin_type')
         pname = self.get_option('plugin_name')
+        show_origin = self.get_option('show_origin')
 
         if (ptype or pname) and not (ptype and pname):
             raise AnsibleOptionsError('Both plugin_type and plugin_name are required, cannot use one without the other')
@@ -138,9 +144,10 @@ class LookupModule(LookupBase):
                 raise AnsibleOptionsError('Invalid setting identifier, "%s" is not a string, its a %s' % (term, type(term)))
 
             result = Sentinel
+            origin = None
             try:
                 if pname:
-                    result = _get_plugin_config(pname, ptype, term, variables)
+                    result, origin = _get_plugin_config(pname, ptype, term, variables)
                 else:
                     result = _get_global_config(term)
             except MissingSetting as e:
@@ -152,5 +159,8 @@ class LookupModule(LookupBase):
                     pass  # this is not needed, but added to have all 3 options stated
 
             if result is not Sentinel:
-                ret.append(result)
+                if show_origin:
+                    ret.append((result, origin))
+                else:
+                    ret.append(result)
         return ret

ansible/plugins/lookup/csvfile.py

@@ -12,7 +12,7 @@ DOCUMENTATION = r"""
     description:
       - The csvfile lookup reads the contents of a file in CSV (comma-separated value) format.
         The lookup looks for the row where the first column matches keyname (which can be multiple words)
-        and returns the value in the C(col) column (default 1, which indexed from 0 means the second column in the file).
+        and returns the value in the O(col) column (default 1, which indexed from 0 means the second column in the file).
     options:
       col:
         description:  column to return (0 indexed).
@@ -20,7 +20,7 @@ DOCUMENTATION = r"""
       default:
         description: what to return if the value is not found in the file.
       delimiter:
-        description: field separator in the file, for a tab you can specify C(TAB) or C(\t).
+        description: field separator in the file, for a tab you can specify V(TAB) or V(\\t).
         default: TAB
       file:
         description: name of the CSV/TSV file to open.
@@ -35,6 +35,9 @@ DOCUMENTATION = r"""
       - For historical reasons, in the search keyname, quotes are treated
         literally and cannot be used around the string unless they appear
         (escaped as required) in the first column of the file you are parsing.
+    seealso:
+      - ref: playbook_task_paths
+        description: Search paths used for relative files.
 """
 
 EXAMPLES = """
@@ -54,7 +57,7 @@ EXAMPLES = """
     neighbor_as: "{{ csvline[5] }}"
     neigh_int_ip: "{{ csvline[6] }}"
   vars:
-    csvline = "{{ lookup('ansible.builtin.csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
+    csvline: "{{ lookup('ansible.builtin.csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
   delegate_to: localhost
 """
 
@@ -75,7 +78,7 @@ from ansible.errors import AnsibleError, AnsibleAssertionError
 from ansible.parsing.splitter import parse_kv
 from ansible.plugins.lookup import LookupBase
 from ansible.module_utils.six import PY2
-from ansible.module_utils._text import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 
 
 class CSVRecoder:

ansible/plugins/lookup/env.py

@@ -23,7 +23,7 @@ DOCUMENTATION = """
         default: ''
         version_added: '2.13'
     notes:
-        - You can pass the C(Undefined) object as C(default) to force an undefined error
+        - You can pass the C(Undefined) object as O(default) to force an undefined error
 """
 
 EXAMPLES = """

ansible/plugins/lookup/file.py

@@ -28,11 +28,14 @@ DOCUMENTATION = """
     notes:
       - if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
       - this lookup does not understand 'globbing', use the fileglob lookup instead.
+    seealso:
+      - ref: playbook_task_paths
+        description: Search paths used for relative files.
 """
 
 EXAMPLES = """
 - ansible.builtin.debug:
-    msg: "the value of foo.txt is {{lookup('ansible.builtin.file', '/etc/foo.txt') }}"
+    msg: "the value of foo.txt is {{ lookup('ansible.builtin.file', '/etc/foo.txt') }}"
 
 - name: display multiple file contents
   ansible.builtin.debug: var=item
@@ -52,7 +55,7 @@ RETURN = """
 
 from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleLookupError
 from ansible.plugins.lookup import LookupBase
-from ansible.module_utils._text import to_text
+from ansible.module_utils.common.text.converters import to_text
 from ansible.utils.display import Display
 
 display = Display()

ansible/plugins/lookup/fileglob.py

@@ -21,7 +21,10 @@ DOCUMENTATION = """
       - See R(Ansible task paths,playbook_task_paths) to understand how file lookup occurs with paths.
       - Matching is against local system files on the Ansible controller.
         To iterate a list of files on a remote node, use the M(ansible.builtin.find) module.
-      - Returns a string list of paths joined by commas, or an empty list if no files match. For a 'true list' pass C(wantlist=True) to the lookup.
+      - Returns a string list of paths joined by commas, or an empty list if no files match. For a 'true list' pass O(ignore:wantlist=True) to the lookup.
+    seealso:
+      - ref: playbook_task_paths
+        description: Search paths used for relative files.
 """
 
 EXAMPLES = """
@@ -50,7 +53,7 @@ import os
 import glob
 
 from ansible.plugins.lookup import LookupBase
-from ansible.module_utils._text import to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
 
 
 class LookupModule(LookupBase):

ansible/plugins/lookup/first_found.py

@@ -15,9 +15,9 @@ DOCUMENTATION = """
         to the containing locations of role / play / include and so on.
       - The list of files has precedence over the paths searched.
         For example, A task in a role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not.
-      - Either a list of files C(_terms) or a key C(files) with a list of files is required for this plugin to operate.
+      - Either a list of files O(_terms) or a key O(files) with a list of files is required for this plugin to operate.
     notes:
-      - This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has C(files) and C(paths).
+      - This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has O(files) and O(paths).
     options:
       _terms:
         description: A list of file names.
@@ -35,16 +35,19 @@ DOCUMENTATION = """
         type: boolean
         default: False
         description:
-          - When C(True), return an empty list when no files are matched.
+          - When V(True), return an empty list when no files are matched.
           - This is useful when used with C(with_first_found), as an empty list return to C(with_) calls
             causes the calling task to be skipped.
-          - When used as a template via C(lookup) or C(query), setting I(skip=True) will *not* cause the task to skip.
+          - When used as a template via C(lookup) or C(query), setting O(skip=True) will *not* cause the task to skip.
             Tasks must handle the empty list return from the template.
-          - When C(False) and C(lookup) or C(query) specifies  I(errors='ignore') all errors (including no file found,
+          - When V(False) and C(lookup) or C(query) specifies O(ignore:errors='ignore') all errors (including no file found,
             but potentially others) return an empty string or an empty list respectively.
-          - When C(True) and C(lookup) or C(query) specifies I(errors='ignore'), no file found will return an empty
+          - When V(True) and C(lookup) or C(query) specifies O(ignore:errors='ignore'), no file found will return an empty
             list and other potential errors return an empty string or empty list depending on the template call
-            (in other words return values of C(lookup) v C(query)).
+            (in other words return values of C(lookup) vs C(query)).
+    seealso:
+      - ref: playbook_task_paths
+        description: Search paths used for relative paths/files.
 """
 
 EXAMPLES = """
@@ -165,15 +168,13 @@ class LookupModule(LookupBase):
         total_search = []
         skip = False
 
-        if not terms and kwargs:
-            terms = ['']
-
         # can use a dict instead of list item to pass inline config
         for term in terms:
             if isinstance(term, Mapping):
                 self.set_options(var_options=variables, direct=term)
+                files = self.get_option('files')
             elif isinstance(term, string_types):
-                self.set_options(var_options=variables, direct=kwargs)
+                files = [term]
             elif isinstance(term, Sequence):
                 partial, skip = self._process_terms(term, variables, kwargs)
                 total_search.extend(partial)
@@ -181,7 +182,6 @@ class LookupModule(LookupBase):
             else:
                 raise AnsibleLookupError("Invalid term supplied, can handle string, mapping or list of strings but got: %s for %s" % (type(term), term))
 
-            files = self.get_option('files')
             paths = self.get_option('paths')
 
             # NOTE: this is used as 'global' but  can be set many times?!?!?
@@ -198,8 +198,8 @@ class LookupModule(LookupBase):
                         f = os.path.join(path, fn)
                         total_search.append(f)
             elif filelist:
-                # NOTE: this seems wrong, should be 'extend' as any option/entry can clobber all
-                total_search = filelist
+                # NOTE: this is now 'extend', previouslly it would clobber all options, but we deemed that a bug
+                total_search.extend(filelist)
             else:
                 total_search.append(term)
 
@@ -207,6 +207,10 @@ class LookupModule(LookupBase):
 
     def run(self, terms, variables, **kwargs):
 
+        if not terms:
+            self.set_options(var_options=variables, direct=kwargs)
+            terms = self.get_option('files')
+
         total_search, skip = self._process_terms(terms, variables, kwargs)
 
         # NOTE: during refactor noticed that the 'using a dict' as term
@@ -222,6 +226,8 @@ class LookupModule(LookupBase):
             try:
                 fn = self._templar.template(fn)
             except (AnsibleUndefinedVariable, UndefinedError):
+                # NOTE: backwards compat ff behaviour is to ignore errors when vars are undefined.
+                #       moved here from task_executor.
                 continue
 
             # get subdir if set by task executor, default to files otherwise