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

ansible/plugins/inventory/__init__.py

@@ -17,24 +17,30 @@
 
 from __future__ import annotations
 
+import functools
 import hashlib
 import os
 import string
+import typing as t
 
 from collections.abc import Mapping
 
-from ansible.errors import AnsibleError, AnsibleParserError
+from ansible import template as _template
+from ansible.errors import AnsibleError, AnsibleParserError, AnsibleValueOmittedError
 from ansible.inventory.group import to_safe_group_name as original_safe
+from ansible.module_utils._internal import _plugin_info
 from ansible.parsing.utils.addresses import parse_address
-from ansible.plugins import AnsiblePlugin
-from ansible.plugins.cache import CachePluginAdjudicator as CacheObject
+from ansible.parsing.dataloader import DataLoader
+from ansible.plugins import AnsiblePlugin, _ConfigurablePlugin
+from ansible.plugins.cache import CachePluginAdjudicator
 from ansible.module_utils.common.text.converters import to_bytes, to_native
-from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.module_utils.six import string_types
-from ansible.template import Templar
 from ansible.utils.display import Display
 from ansible.utils.vars import combine_vars, load_extra_vars
 
+if t.TYPE_CHECKING:
+    from ansible.inventory.data import InventoryData
+
 display = Display()
 
 
@@ -45,17 +51,17 @@ def to_safe_group_name(name):
 
 
 def detect_range(line=None):
-    '''
+    """
     A helper function that checks a given host line to see if it contains
     a range pattern described in the docstring above.
 
     Returns True if the given line contains a pattern, else False.
-    '''
+    """
     return '[' in line
 
 
 def expand_hostname_range(line=None):
-    '''
+    """
     A helper function that expands a given line that contains a pattern
     specified in top docstring, and returns a list that consists of the
     expanded version.
@@ -65,7 +71,7 @@ def expand_hostname_range(line=None):
     string splitting.
 
     References: https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#hosts-and-groups
-    '''
+    """
     all_hosts = []
     if line:
         # A hostname such as db[1:6]-node is considered to consists
@@ -127,8 +133,11 @@ def expand_hostname_range(line=None):
 
 
 def get_cache_plugin(plugin_name, **kwargs):
+    if not plugin_name:
+        raise AnsibleError("A cache plugin must be configured to use inventory caching.")
+
     try:
-        cache = CacheObject(plugin_name, **kwargs)
+        cache = CachePluginAdjudicator(plugin_name, **kwargs)
     except AnsibleError as e:
         if 'fact_caching_connection' in to_native(e):
             raise AnsibleError("error, '%s' inventory cache plugin requires the one of the following to be set "
@@ -136,17 +145,22 @@ def get_cache_plugin(plugin_name, **kwargs):
                                "[inventory]: cache_connection;\nEnvironment:\nANSIBLE_INVENTORY_CACHE_CONNECTION,\n"
                                "ANSIBLE_CACHE_PLUGIN_CONNECTION." % plugin_name)
         else:
-            raise e
+            raise
 
-    if plugin_name != 'memory' and kwargs and not getattr(cache._plugin, '_options', None):
+    if cache._plugin.ansible_name != 'ansible.builtin.memory' and kwargs and not getattr(cache._plugin, '_options', None):
         raise AnsibleError('Unable to use cache plugin {0} for inventory. Cache options were provided but may not reconcile '
                            'correctly unless set via set_options. Refer to the porting guide if the plugin derives user settings '
                            'from ansible.constants.'.format(plugin_name))
     return cache
 
 
-class BaseInventoryPlugin(AnsiblePlugin):
-    """ Parses an Inventory Source"""
+class _BaseInventoryPlugin(AnsiblePlugin):
+    """
+    Internal base implementation for inventory plugins.
+
+    Do not inherit from this directly, use one of its public subclasses instead.
+    Used to introduce an extra layer in the class hierarchy to allow Constructed to subclass this while remaining a mixin for existing inventory plugins.
+    """
 
     TYPE = 'generator'
 
@@ -156,17 +170,27 @@ class BaseInventoryPlugin(AnsiblePlugin):
     # it by default.
     _sanitize_group_name = staticmethod(to_safe_group_name)
 
-    def __init__(self):
+    def __init__(self) -> None:
 
-        super(BaseInventoryPlugin, self).__init__()
+        super().__init__()
 
         self._options = {}
-        self.inventory = None
         self.display = display
-        self._vars = {}
 
-    def parse(self, inventory, loader, path, cache=True):
-        ''' Populates inventory from the given data. Raises an error on any parse failure
+        # These attributes are set by the parse() method on this (base) class.
+        self.loader: DataLoader | None = None
+        self.inventory: InventoryData | None = None
+        self._vars: dict[str, t.Any] | None = None
+
+    trusted_by_default: bool = False
+    """Inventory plugins that only source templates from trusted sources can set this True to have trust automatically applied to all templates."""
+
+    @functools.cached_property
+    def templar(self) -> _template.Templar:
+        return _template.Templar(loader=self.loader)
+
+    def parse(self, inventory: InventoryData, loader: DataLoader, path: str, cache: bool = True) -> None:
+        """ Populates inventory from the given data. Raises an error on any parse failure
             :arg inventory: a copy of the previously accumulated inventory data,
                  to be updated with any new data this plugin provides.
                  The inventory can be empty if no other source/plugin ran successfully.
@@ -177,20 +201,18 @@ class BaseInventoryPlugin(AnsiblePlugin):
                  but it can also be a raw string for this plugin to consume
             :arg cache: a boolean that indicates if the plugin should use the cache or not
                  you can ignore if this plugin does not implement caching.
-        '''
-
+        """
         self.loader = loader
         self.inventory = inventory
-        self.templar = Templar(loader=loader)
         self._vars = load_extra_vars(loader)
 
     def verify_file(self, path):
-        ''' Verify if file is usable by this plugin, base does minimal accessibility check
+        """ Verify if file is usable by this plugin, base does minimal accessibility check
             :arg path: a string that was passed as an inventory source,
                  it normally is a path to a config file, but this is not a requirement,
                  it can also be parsed itself as the inventory data to process.
                  So only call this base class if you expect it to be a file.
-        '''
+        """
 
         valid = False
         b_path = to_bytes(path, errors='surrogate_or_strict')
@@ -210,15 +232,14 @@ class BaseInventoryPlugin(AnsiblePlugin):
                 self.inventory.set_variable(host, k, variables[k])
 
     def _read_config_data(self, path):
-        ''' validate config and set options as appropriate
+        """ validate config and set options as appropriate
             :arg path: path to common yaml format config file for this plugin
-        '''
+        """
 
-        config = {}
         try:
             # avoid loader cache so meta: refresh_inventory can pick up config changes
             # if we read more than once, fs cache should be good enough
-            config = self.loader.load_from_file(path, cache='none')
+            config = self.loader.load_from_file(path, cache='none', trusted_as_template=True)
         except Exception as e:
             raise AnsibleParserError(to_native(e))
 
@@ -244,20 +265,20 @@ class BaseInventoryPlugin(AnsiblePlugin):
         return config
 
     def _consume_options(self, data):
-        ''' update existing options from alternate configuration sources not normally used by Ansible.
+        """ update existing options from alternate configuration sources not normally used by Ansible.
             Many API libraries already have existing configuration sources, this allows plugin author to leverage them.
             :arg data: key/value pairs that correspond to configuration options for this plugin
-        '''
+        """
 
         for k in self._options:
             if k in data:
                 self._options[k] = data.pop(k)
 
     def _expand_hostpattern(self, hostpattern):
-        '''
+        """
         Takes a single host pattern and returns a list of hostnames and an
         optional port number that applies to all of them.
-        '''
+        """
         # Can the given hostpattern be parsed as a host with an optional port
         # specification?
 
@@ -279,7 +300,11 @@ class BaseInventoryPlugin(AnsiblePlugin):
         return (hostnames, port)
 
 
-class BaseFileInventoryPlugin(BaseInventoryPlugin):
+class BaseInventoryPlugin(_BaseInventoryPlugin):
+    """ Parses an Inventory Source """
+
+
+class BaseFileInventoryPlugin(_BaseInventoryPlugin):
     """ Parses a File based Inventory Source"""
 
     TYPE = 'storage'
@@ -289,51 +314,43 @@ class BaseFileInventoryPlugin(BaseInventoryPlugin):
         super(BaseFileInventoryPlugin, self).__init__()
 
 
-class Cacheable(object):
+class Cacheable(_plugin_info.HasPluginInfo, _ConfigurablePlugin):
+    """Mixin for inventory plugins which support caching."""
 
-    _cache = CacheObject()
+    _cache: CachePluginAdjudicator
 
     @property
-    def cache(self):
+    def cache(self) -> CachePluginAdjudicator:
         return self._cache
 
-    def load_cache_plugin(self):
+    def load_cache_plugin(self) -> None:
         plugin_name = self.get_option('cache_plugin')
         cache_option_keys = [('_uri', 'cache_connection'), ('_timeout', 'cache_timeout'), ('_prefix', 'cache_prefix')]
         cache_options = dict((opt[0], self.get_option(opt[1])) for opt in cache_option_keys if self.get_option(opt[1]) is not None)
         self._cache = get_cache_plugin(plugin_name, **cache_options)
 
-    def get_cache_key(self, path):
-        return "{0}_{1}".format(self.NAME, self._get_cache_prefix(path))
+    def get_cache_key(self, path: str) -> str:
+        return f'{self.ansible_name}_{self._get_cache_prefix(path)}'
 
-    def _get_cache_prefix(self, path):
-        ''' create predictable unique prefix for plugin/inventory '''
+    def _get_cache_prefix(self, path: str) -> str:
+        """Return a predictable unique key based on the given path."""
+        return 'k' + hashlib.sha256(f'{self.ansible_name}{path}'.encode(), usedforsecurity=False).hexdigest()[:6]
 
-        m = hashlib.sha1()
-        m.update(to_bytes(self.NAME, errors='surrogate_or_strict'))
-        d1 = m.hexdigest()
+    def clear_cache(self) -> None:
+        self._cache.clear()
 
-        n = hashlib.sha1()
-        n.update(to_bytes(path, errors='surrogate_or_strict'))
-        d2 = n.hexdigest()
-
-        return 's_'.join([d1[:5], d2[:5]])
-
-    def clear_cache(self):
-        self._cache.flush()
-
-    def update_cache_if_changed(self):
+    def update_cache_if_changed(self) -> None:
         self._cache.update_cache_if_changed()
 
-    def set_cache_plugin(self):
+    def set_cache_plugin(self) -> None:
         self._cache.set_cache()
 
 
-class Constructable(object):
-
-    def _compose(self, template, variables, disable_lookups=True):
-        ''' helper method for plugins to compose variables for Ansible based on jinja2 expression and inventory vars'''
-        t = self.templar
+class Constructable(_BaseInventoryPlugin):
+    def _compose(self, template, variables, disable_lookups=...):
+        """ helper method for plugins to compose variables for Ansible based on jinja2 expression and inventory vars"""
+        if disable_lookups is not ...:
+            self.display.deprecated("The disable_lookups arg has no effect.", version="2.23")
 
         try:
             use_extra = self.get_option('use_extra_vars')
@@ -341,15 +358,14 @@ class Constructable(object):
             use_extra = False
 
         if use_extra:
-            t.available_variables = combine_vars(variables, self._vars)
+            self.templar.available_variables = combine_vars(variables, self._vars)
         else:
-            t.available_variables = variables
+            self.templar.available_variables = variables
 
-        return t.template('%s%s%s' % (t.environment.variable_start_string, template, t.environment.variable_end_string),
-                          disable_lookups=disable_lookups)
+        return self.templar.evaluate_expression(template)
 
     def _set_composite_vars(self, compose, variables, host, strict=False):
-        ''' loops over compose entries to create vars for hosts '''
+        """ loops over compose entries to create vars for hosts """
         if compose and isinstance(compose, dict):
             for varname in compose:
                 try:
@@ -361,17 +377,17 @@ class Constructable(object):
                 self.inventory.set_variable(host, varname, composite)
 
     def _add_host_to_composed_groups(self, groups, variables, host, strict=False, fetch_hostvars=True):
-        ''' helper to create complex groups for plugins based on jinja2 conditionals, hosts that meet the conditional are added to group'''
+        """ helper to create complex groups for plugins based on jinja2 conditionals, hosts that meet the conditional are added to group"""
         # process each 'group entry'
         if groups and isinstance(groups, dict):
             if fetch_hostvars:
                 variables = combine_vars(variables, self.inventory.get_host(host).get_vars())
             self.templar.available_variables = variables
             for group_name in groups:
-                conditional = "{%% if %s %%} True {%% else %%} False {%% endif %%}" % groups[group_name]
+                conditional = groups[group_name]
                 group_name = self._sanitize_group_name(group_name)
                 try:
-                    result = boolean(self.templar.template(conditional))
+                    result = self.templar.evaluate_conditional(conditional)
                 except Exception as e:
                     if strict:
                         raise AnsibleParserError("Could not add host %s to group %s: %s" % (host, group_name, to_native(e)))
@@ -384,7 +400,9 @@ class Constructable(object):
                     self.inventory.add_child(group_name, host)
 
     def _add_host_to_keyed_groups(self, keys, variables, host, strict=False, fetch_hostvars=True):
-        ''' helper to create groups for plugins based on variable values and add the corresponding hosts to it'''
+        """ helper to create groups for plugins based on variable values and add the corresponding hosts to it"""
+        should_default_value = (None, '')
+
         if keys and isinstance(keys, list):
             for keyed in keys:
                 if keyed and isinstance(keyed, dict):
@@ -401,36 +419,39 @@ class Constructable(object):
                     trailing_separator = keyed.get('trailing_separator')
                     if trailing_separator is not None and default_value_name is not None:
                         raise AnsibleParserError("parameters are mutually exclusive for keyed groups: default_value|trailing_separator")
-                    if key or (key == '' and default_value_name is not None):
+
+                    use_default = key in should_default_value and default_value_name is not None
+                    if key or use_default:
                         prefix = keyed.get('prefix', '')
                         sep = keyed.get('separator', '_')
                         raw_parent_name = keyed.get('parent_group', None)
-                        if raw_parent_name:
-                            try:
-                                raw_parent_name = self.templar.template(raw_parent_name)
-                            except AnsibleError as e:
-                                if strict:
-                                    raise AnsibleParserError("Could not generate parent group %s for group %s: %s" % (raw_parent_name, key, to_native(e)))
-                                continue
+
+                        try:
+                            raw_parent_name = self.templar.template(raw_parent_name)
+                        except AnsibleValueOmittedError:
+                            raw_parent_name = None
+                        except Exception as ex:
+                            if strict:
+                                raise AnsibleParserError(f'Could not generate parent group {raw_parent_name!r} for group {key!r}: {ex}') from ex
+
+                            continue
 
                         new_raw_group_names = []
-                        if isinstance(key, string_types):
-                            # if key is empty, 'default_value' will be used as group name
-                            if key == '' and default_value_name is not None:
-                                new_raw_group_names.append(default_value_name)
-                            else:
-                                new_raw_group_names.append(key)
+                        if use_default:
+                            new_raw_group_names.append(default_value_name)
+                        elif isinstance(key, string_types):
+                            new_raw_group_names.append(key)
                         elif isinstance(key, list):
                             for name in key:
                                 # if list item is empty, 'default_value' will be used as group name
-                                if name == '' and default_value_name is not None:
+                                if name in should_default_value and default_value_name is not None:
                                     new_raw_group_names.append(default_value_name)
                                 else:
                                     new_raw_group_names.append(name)
                         elif isinstance(key, Mapping):
                             for (gname, gval) in key.items():
                                 bare_name = '%s%s%s' % (gname, sep, gval)
-                                if gval == '':
+                                if gval in should_default_value:
                                     # key's value is empty
                                     if default_value_name is not None:
                                         bare_name = '%s%s%s' % (gname, sep, default_value_name)

ansible/plugins/inventory/advanced_host_list.py

@@ -3,22 +3,22 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: advanced_host_list
     version_added: "2.4"
     short_description: Parses a 'host list' with ranges
     description:
         - Parses a host list string as a comma separated values of hosts and supports host ranges.
         - This plugin only applies to inventory sources that are not paths and contain at least one comma.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
     # simple range
     # ansible -i 'host[1:10],' -m ping
 
     # still supports w/o ranges also
     # ansible-playbook -i 'localhost,' play.yml
-'''
+"""
 
 import os
 
@@ -31,6 +31,8 @@ class InventoryModule(BaseInventoryPlugin):
 
     NAME = 'advanced_host_list'
 
+    # advanced_host_list does not set vars, so needs no special trust assistance from the inventory API
+
     def verify_file(self, host_list):
 
         valid = False
@@ -40,7 +42,7 @@ class InventoryModule(BaseInventoryPlugin):
         return valid
 
     def parse(self, inventory, loader, host_list, cache=True):
-        ''' parses the inventory file '''
+        """ parses the inventory file """
 
         super(InventoryModule, self).parse(inventory, loader, host_list)
 

ansible/plugins/inventory/auto.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: auto
     author:
       - Matt Davis (@nitzmahone)
@@ -14,12 +14,12 @@ DOCUMENTATION = '''
           C(plugin) key at its root will automatically cause the named plugin to be loaded and executed with that
           config. This effectively provides automatic enabling of all installed/accessible inventory plugins.
         - To disable this behavior, remove C(auto) from the C(INVENTORY_ENABLED) config element.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 # This plugin is not intended for direct use; it is a fallback mechanism for automatic enabling of
 # all installed inventory plugins.
-'''
+"""
 
 from ansible.errors import AnsibleParserError
 from ansible.plugins.inventory import BaseInventoryPlugin
@@ -30,6 +30,8 @@ class InventoryModule(BaseInventoryPlugin):
 
     NAME = 'auto'
 
+    # no need to set trusted_by_default, since the consumers of this value will always consult the real plugin substituted during our parse()
+
     def verify_file(self, path):
         if not path.endswith('.yml') and not path.endswith('.yaml'):
             return False
@@ -55,6 +57,11 @@ class InventoryModule(BaseInventoryPlugin):
             raise AnsibleParserError("inventory source '{0}' could not be verified by inventory plugin '{1}'".format(path, plugin_name))
 
         self.display.v("Using inventory plugin '{0}' to process inventory source '{1}'".format(plugin._load_name, path))
+
+        # unfortunate magic to swap the real plugin type we're proxying here into the inventory data API wrapper, so the wrapper can make the right compat
+        # decisions based on the metadata the real plugin provides instead of our metadata
+        inventory._target_plugin = plugin
+
         plugin.parse(inventory, loader, path, cache=cache)
         try:
             plugin.update_cache_if_changed()

ansible/plugins/inventory/constructed.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: constructed
     version_added: "2.4"
     short_description: Uses Jinja2 to construct vars and groups based on existing inventory.
@@ -33,9 +33,9 @@ DOCUMENTATION = '''
             version_added: '2.11'
     extends_documentation_fragment:
       - constructed
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
     # inventory.config file in YAML format
     plugin: ansible.builtin.constructed
     strict: False
@@ -77,17 +77,16 @@ EXAMPLES = r'''
         # this creates a common parent group for all ec2 availability zones
         - key: placement.availability_zone
           parent_group: all_ec2_zones
-'''
+"""
 
 import os
 
 from ansible import constants as C
-from ansible.errors import AnsibleParserError, AnsibleOptionsError
+from ansible.errors import AnsibleParserError
 from ansible.inventory.helpers import get_group_vars
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
-from ansible.module_utils.common.text.converters import to_native
+from ansible.plugins.loader import cache_loader
 from ansible.utils.vars import combine_vars
-from ansible.vars.fact_cache import FactCache
 from ansible.vars.plugins import get_vars_from_inventory_sources
 
 
@@ -96,11 +95,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
 
     NAME = 'constructed'
 
-    def __init__(self):
-
-        super(InventoryModule, self).__init__()
-
-        self._cache = FactCache()
+    # implicit trust behavior is already added by the YAML parser invoked by the loader
 
     def verify_file(self, path):
 
@@ -114,11 +109,11 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         return valid
 
     def get_all_host_vars(self, host, loader, sources):
-        ''' requires host object '''
+        """ requires host object """
         return combine_vars(self.host_groupvars(host, loader, sources), self.host_vars(host, loader, sources))
 
     def host_groupvars(self, host, loader, sources):
-        ''' requires host object '''
+        """ requires host object """
         gvars = get_group_vars(host.get_groups())
 
         if self.get_option('use_vars_plugins'):
@@ -127,7 +122,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         return gvars
 
     def host_vars(self, host, loader, sources):
-        ''' requires host object '''
+        """ requires host object """
         hvars = host.get_vars()
 
         if self.get_option('use_vars_plugins'):
@@ -136,7 +131,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         return hvars
 
     def parse(self, inventory, loader, path, cache=False):
-        ''' parses the inventory file '''
+        """ parses the inventory file """
 
         super(InventoryModule, self).parse(inventory, loader, path, cache=cache)
 
@@ -147,26 +142,28 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
             sources = inventory.processed_sources
         except AttributeError:
             if self.get_option('use_vars_plugins'):
-                raise AnsibleOptionsError("The option use_vars_plugins requires ansible >= 2.11.")
+                raise
 
         strict = self.get_option('strict')
-        fact_cache = FactCache()
+
+        cache = cache_loader.get(C.CACHE_PLUGIN)
+
         try:
             # Go over hosts (less var copies)
             for host in inventory.hosts:
 
                 # get available variables to templar
                 hostvars = self.get_all_host_vars(inventory.hosts[host], loader, sources)
-                if host in fact_cache:  # adds facts if cache is active
-                    hostvars = combine_vars(hostvars, fact_cache[host])
+                if cache.contains(host):  # adds facts if cache is active
+                    hostvars = combine_vars(hostvars, cache.get(host))
 
                 # create composite vars
                 self._set_composite_vars(self.get_option('compose'), hostvars, host, strict=strict)
 
                 # refetch host vars in case new ones have been created above
                 hostvars = self.get_all_host_vars(inventory.hosts[host], loader, sources)
-                if host in self._cache:  # adds facts if cache is active
-                    hostvars = combine_vars(hostvars, self._cache[host])
+                if cache.contains(host):  # adds facts if cache is active
+                    hostvars = combine_vars(hostvars, cache.get(host))
 
                 # constructed groups based on conditionals
                 self._add_host_to_composed_groups(self.get_option('groups'), hostvars, host, strict=strict, fetch_hostvars=False)
@@ -174,5 +171,5 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
                 # constructed groups based variable values
                 self._add_host_to_keyed_groups(self.get_option('keyed_groups'), hostvars, host, strict=strict, fetch_hostvars=False)
 
-        except Exception as e:
-            raise AnsibleParserError("failed to parse %s: %s " % (to_native(path), to_native(e)), orig_exc=e)
+        except Exception as ex:
+            raise AnsibleParserError(f"Failed to parse {path!r}.") from ex