ansible-core 2.19.0b3__py3-none-any.whl → 2.19.0b5__py3-none-any.whl

ansible/cli/doc.py

@@ -9,12 +9,14 @@ from __future__ import annotations
 # ansible.cli needs to be imported first, to ensure the source bin/* scripts run that code first
 from ansible.cli import CLI
 
+import collections.abc
 import importlib
 import pkgutil
 import os
 import os.path
 import re
 import textwrap
+import typing as t
 
 import yaml
 
@@ -35,7 +37,7 @@ from ansible.parsing.plugin_docs import read_docstub
 from ansible.parsing.yaml.dumper import AnsibleDumper
 from ansible.parsing.yaml.loader import AnsibleLoader
 from ansible._internal._yaml._loader import AnsibleInstrumentedLoader
-from ansible.plugins.list import list_plugins
+from ansible.plugins.list import _list_plugins_with_info, _PluginDocMetadata
 from ansible.plugins.loader import action_loader, fragment_loader
 from ansible.utils.collection_loader import AnsibleCollectionConfig, AnsibleCollectionRef
 from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path
@@ -44,6 +46,7 @@ from ansible.utils.display import Display
 from ansible.utils.plugin_docs import get_plugin_docs, get_docstring, get_versioned_doclink
 from ansible.template import trust_as_template
 from ansible._internal import _json
+from ansible._internal._templating import _jinja_plugins
 
 display = Display()
 
@@ -788,35 +791,47 @@ class DocCLI(CLI, RoleMixin):
         return coll_filter
 
     def _list_plugins(self, plugin_type, content):
-
-        results = {}
-        self.plugins = {}
-        loader = DocCLI._prep_loader(plugin_type)
+        DocCLI._prep_loader(plugin_type)
 
         coll_filter = self._get_collection_filter()
-        self.plugins.update(list_plugins(plugin_type, coll_filter))
+        plugins = _list_plugins_with_info(plugin_type, coll_filter)
+
+        # Remove the internal ansible._protomatter plugins if getting all plugins
+        if not coll_filter:
+            plugins = {k: v for k, v in plugins.items() if not k.startswith('ansible._protomatter.')}
 
         # get appropriate content depending on option
         if content == 'dir':
-            results = self._get_plugin_list_descriptions(loader)
+            results = self._get_plugin_list_descriptions(plugins)
         elif content == 'files':
-            results = {k: self.plugins[k][0] for k in self.plugins.keys()}
+            results = {k: v.path for k, v in plugins.items()}
         else:
-            results = {k: {} for k in self.plugins.keys()}
+            results = {k: {} for k in plugins.keys()}
             self.plugin_list = set()  # reset for next iteration
 
         return results
 
-    def _get_plugins_docs(self, plugin_type, names, fail_ok=False, fail_on_errors=True):
-
+    def _get_plugins_docs(self, plugin_type: str, names: collections.abc.Iterable[str], fail_ok: bool = False, fail_on_errors: bool = True) -> dict[str, dict]:
         loader = DocCLI._prep_loader(plugin_type)
 
+        if plugin_type in ('filter', 'test'):
+            jinja2_builtins = _jinja_plugins.get_jinja_builtin_plugin_descriptions(plugin_type)
+            jinja2_builtins.update({name.split('.')[-1]: value for name, value in jinja2_builtins.items()})  # add short-named versions for lookup
+        else:
+            jinja2_builtins = {}
+
         # get the docs for plugins in the command line list
         plugin_docs = {}
         for plugin in names:
-            doc = {}
+            doc: dict[str, t.Any] = {}
             try:
-                doc, plainexamples, returndocs, metadata = get_plugin_docs(plugin, plugin_type, loader, fragment_loader, (context.CLIARGS['verbosity'] > 0))
+                doc, plainexamples, returndocs, metadata = self._get_plugin_docs_with_jinja2_builtins(
+                    plugin,
+                    plugin_type,
+                    loader,
+                    fragment_loader,
+                    jinja2_builtins,
+                )
             except AnsiblePluginNotFound as e:
                 display.warning(to_native(e))
                 continue
@@ -853,6 +868,39 @@ class DocCLI(CLI, RoleMixin):
 
         return plugin_docs
 
+    def _get_plugin_docs_with_jinja2_builtins(
+        self,
+        plugin_name: str,
+        plugin_type: str,
+        loader: t.Any,
+        fragment_loader: t.Any,
+        jinja_builtins: dict[str, str],
+    ) -> tuple[dict, str | None, dict | None, dict | None]:
+        try:
+            return get_plugin_docs(plugin_name, plugin_type, loader, fragment_loader, (context.CLIARGS['verbosity'] > 0))
+        except Exception:
+            if (desc := jinja_builtins.get(plugin_name, ...)) is not ...:
+                short_name = plugin_name.split('.')[-1]
+                long_name = f'ansible.builtin.{short_name}'
+                # Dynamically build a doc stub for any Jinja2 builtin plugin we haven't
+                # explicitly documented.
+                doc = dict(
+                    collection='ansible.builtin',
+                    plugin_name=long_name,
+                    filename='',
+                    short_description=desc,
+                    description=[
+                        desc,
+                        '',
+                        f"This is the Jinja builtin {plugin_type} plugin {short_name!r}.",
+                        f"See: U(https://jinja.palletsprojects.com/en/stable/templates/#jinja-{plugin_type}s.{short_name})",
+                    ],
+                )
+
+                return doc, None, None, None
+
+            raise
+
     def _get_roles_path(self):
         """
          Add any 'roles' subdir in playbook dir to the roles search path.
@@ -1001,10 +1049,10 @@ class DocCLI(CLI, RoleMixin):
     def get_all_plugins_of_type(plugin_type):
         loader = getattr(plugin_loader, '%s_loader' % plugin_type)
         paths = loader._get_paths_with_context()
-        plugins = {}
+        plugins = []
         for path_context in paths:
-            plugins.update(list_plugins(plugin_type))
-        return sorted(plugins.keys())
+            plugins += _list_plugins_with_info(plugin_type).keys()
+        return sorted(plugins)
 
     @staticmethod
     def get_plugin_metadata(plugin_type, plugin_name):
@@ -1101,18 +1149,20 @@ class DocCLI(CLI, RoleMixin):
 
         return text
 
-    def _get_plugin_list_descriptions(self, loader):
+    def _get_plugin_list_descriptions(self, plugins: dict[str, _PluginDocMetadata]) -> dict[str, str]:
 
         descs = {}
-        for plugin in self.plugins.keys():
+        for plugin, plugin_info in plugins.items():
             # TODO: move to plugin itself i.e: plugin.get_desc()
             doc = None
-            filename = Path(to_native(self.plugins[plugin][0]))
+
             docerror = None
-            try:
-                doc = read_docstub(filename)
-            except Exception as e:
-                docerror = e
+            if plugin_info.path:
+                filename = Path(to_native(plugin_info.path))
+                try:
+                    doc = read_docstub(filename)
+                except Exception as e:
+                    docerror = e
 
             # plugin file was empty or had error, lets try other options
             if doc is None:
@@ -1127,9 +1177,15 @@ class DocCLI(CLI, RoleMixin):
                     except Exception as e:
                         docerror = e
 
-            if docerror:
-                display.warning("%s has a documentation formatting error: %s" % (plugin, docerror))
-                continue
+                # Do a final fallback to see if the plugin is a shadowed Jinja2 plugin
+                # without any explicit documentation.
+                if doc is None and plugin_info.jinja_builtin_short_description:
+                    descs[plugin] = plugin_info.jinja_builtin_short_description
+                    continue
+
+                if docerror:
+                    display.error_as_warning(f"{plugin} has a documentation formatting error.", exception=docerror)
+                    continue
 
             if not doc or not isinstance(doc, dict):
                 desc = 'UNDOCUMENTED'
@@ -1368,7 +1424,7 @@ class DocCLI(CLI, RoleMixin):
                     try:
                         text.append(yaml_dump(doc.pop('examples'), indent=2, default_flow_style=False))
                     except Exception as e:
-                        raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
+                        raise AnsibleParserError("Unable to parse examples section.") from e
 
         return text
 
@@ -1406,7 +1462,7 @@ class DocCLI(CLI, RoleMixin):
                 try:
                     text.append('\t' + C.config.get_deprecated_msg_from_config(doc['deprecated'], True, collection_name=collection_name))
                 except KeyError as e:
-                    raise AnsibleError("Invalid deprecation documentation structure", orig_exc=e)
+                    raise AnsibleError("Invalid deprecation documentation structure.") from e
             else:
                 text.append("%s" % doc['deprecated'])
             del doc['deprecated']

ansible/cli/inventory.py

@@ -164,7 +164,7 @@ class InventoryCLI(CLI):
             import yaml
             from ansible.parsing.yaml.dumper import AnsibleDumper
 
-            # DTFIX-RELEASE: need shared infra to smuggle custom kwargs to dumpers, since yaml.dump cannot (as of PyYAML 6.0.1)
+            # DTFIX0: need shared infra to smuggle custom kwargs to dumpers, since yaml.dump cannot (as of PyYAML 6.0.1)
             dumper = functools.partial(AnsibleDumper, dump_vault_tags=True)
             results = to_text(yaml.dump(stuff, Dumper=dumper, default_flow_style=False, allow_unicode=True))
         elif context.CLIARGS['toml']:

ansible/compat/importlib_resources.py

@@ -3,17 +3,14 @@
 
 from __future__ import annotations
 
-import sys
+from ansible.utils.display import Display as _Display
 
-HAS_IMPORTLIB_RESOURCES = False
+from importlib.resources import files  # pylint: disable=unused-import
 
-if sys.version_info < (3, 10):
-    try:
-        from importlib_resources import files  # type: ignore[import]  # pylint: disable=unused-import
-    except ImportError:
-        files = None  # type: ignore[assignment]
-    else:
-        HAS_IMPORTLIB_RESOURCES = True
-else:
-    from importlib.resources import files
-    HAS_IMPORTLIB_RESOURCES = True
+HAS_IMPORTLIB_RESOURCES = True
+
+_Display().deprecated(
+    msg="The `ansible.compat.importlib_resources` module is deprecated.",
+    help_text="Use `importlib.resources` from the Python standard library instead.",
+    version="2.23",
+)

ansible/config/base.yml

@@ -757,7 +757,7 @@ DEFAULT_HASH_BEHAVIOUR:
   - {key: hash_behaviour, section: defaults}
 DEFAULT_HOST_LIST:
   name: Inventory Source
-  default: /etc/ansible/hosts
+  default: [/etc/ansible/hosts]
   description: Comma-separated list of Ansible inventory sources
   env:
     - name: ANSIBLE_INVENTORY
@@ -1054,7 +1054,7 @@ DEFAULT_ROLES_PATH:
   yaml: {key: defaults.roles_path}
 DEFAULT_SELINUX_SPECIAL_FS:
   name: Problematic file systems
-  default: fuse, nfs, vboxsf, ramfs, 9p, vfat
+  default: [fuse, nfs, vboxsf, ramfs, 9p, vfat]
   description:
     - "Some filesystems do not support safe operations and/or return inconsistent errors,
        this setting makes Ansible 'tolerate' those in the list without causing fatal errors."
@@ -1199,15 +1199,6 @@ DEFAULT_VARS_PLUGIN_PATH:
   ini:
   - {key: vars_plugins, section: defaults}
   type: pathspec
-# TODO: unused?
-#DEFAULT_VAR_COMPRESSION_LEVEL:
-#  default: 0
-#  description: 'TODO: write it'
-#  env: [{name: ANSIBLE_VAR_COMPRESSION_LEVEL}]
-#  ini:
-#  - {key: var_compression_level, section: defaults}
-#  type: integer
-#  yaml: {key: defaults.var_compression_level}
 DEFAULT_VAULT_ID_MATCH:
   name: Force vault id match
   default: False
@@ -1333,7 +1324,7 @@ DISPLAY_SKIPPED_HOSTS:
   type: boolean
 DISPLAY_TRACEBACK:
   name: Control traceback display
-  default: never
+  default: [never]
   description: When to include tracebacks in extended error messages
   env:
     - name: ANSIBLE_DISPLAY_TRACEBACK
@@ -1344,6 +1335,7 @@ DISPLAY_TRACEBACK:
     - error
     - warning
     - deprecated
+    - deprecated_value
     - always
     - never
   version_added: "2.19"
@@ -1480,15 +1472,6 @@ GALAXY_COLLECTIONS_PATH_WARNING:
   ini:
     - {key: collections_path_warning, section: galaxy}
   version_added: "2.16"
-# TODO: unused?
-#GALAXY_SCMS:
-#  name: Galaxy SCMS
-#  default: git, hg
-#  description: Available galaxy source control management systems.
-#  env: [{name: ANSIBLE_GALAXY_SCMS}]
-#  ini:
-#  - {key: scms, section: galaxy}
-#  type: list
 GALAXY_SERVER:
   default: https://galaxy.ansible.com
   description: "URL to prepend when roles don't specify the full URI, assume they are referencing this server as the source."
@@ -1731,7 +1714,7 @@ INVENTORY_EXPORT:
   type: bool
 INVENTORY_IGNORE_EXTS:
   name: Inventory ignore extensions
-  default: "{{(REJECT_EXTS + ('.orig', '.cfg', '.retry'))}}"
+  default: "{{ REJECT_EXTS + ['.orig', '.cfg', '.retry'] }}"
   description: List of extensions to ignore when using a directory as an inventory source.
   env: [{name: ANSIBLE_INVENTORY_IGNORE}]
   ini:
@@ -1788,7 +1771,7 @@ INJECT_FACTS_AS_VARS:
   version_added: "2.5"
 MODULE_IGNORE_EXTS:
   name: Module ignore extensions
-  default: "{{(REJECT_EXTS + ('.yaml', '.yml', '.ini'))}}"
+  default: "{{ REJECT_EXTS + ['.yaml', '.yml', '.ini'] }}"
   description:
     - List of extensions to ignore when looking for modules to load.
     - This is for rejecting script and binary module fallback extensions.
@@ -1979,6 +1962,14 @@ SSH_AGENT:
   env: [{name: ANSIBLE_SSH_AGENT}]
   ini: [{key: ssh_agent, section: connection}]
   version_added: '2.19'
+SSH_AGENT_EXECUTABLE:
+  name: Executable to start for the ansible-managed SSH agent
+  description: When ``SSH_AGENT`` is ``auto``, the path or name of the ssh agent executable to start.
+  default: ssh-agent
+  type: str
+  env: [ { name: ANSIBLE_SSH_AGENT_EXECUTABLE } ]
+  ini: [ { key: ssh_agent_executable, section: connection } ]
+  version_added: '2.19'
 SSH_AGENT_KEY_LIFETIME:
   name: Set a maximum lifetime when adding identities to an agent
   description: For keys inserted into an agent defined by ``SSH_AGENT``, define a lifetime, in seconds, that the key may remain
@@ -2053,6 +2044,19 @@ TASK_TIMEOUT:
   - {key: task_timeout, section: defaults}
   type: integer
   version_added: '2.10'
+_TEMPLAR_SANDBOX_MODE:
+  name: Control Jinja template sandbox behavior
+  default: default
+  description:
+    - The default Jinja sandbox behavior blocks template access to all `_` prefixed object attributes and known collection mutation methods (e.g., `dict.clear()`, `list.append()`).
+  type: choices
+  choices:
+    - default
+    - allow_unsafe_attributes
+  env: [{name: _ANSIBLE_TEMPLAR_SANDBOX_MODE}]
+  deprecated:
+    why: controlling sandbox behavior is a temporary workaround
+    version: '2.23'
 _TEMPLAR_UNKNOWN_TYPE_CONVERSION:
   name: Templar unknown type conversion behavior
   default: warning