ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/python_literal_eval.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import ast
+
+from ansible.errors import AnsibleTypeError
+
+
+def python_literal_eval(value: object, ignore_errors=False) -> object:
+    try:
+        if isinstance(value, str):
+            return ast.literal_eval(value)
+
+        raise AnsibleTypeError("The `value` to eval must be a string.", obj=value)
+    except Exception:
+        if ignore_errors:
+            return value
+
+        raise
+
+
+class FilterModule(object):
+    @staticmethod
+    def filters():
+        return dict(python_literal_eval=python_literal_eval)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/python_literal_eval.yml

@@ -0,0 +1,33 @@
+DOCUMENTATION:
+  name: python_literal_eval
+  version_added: "2.19"
+  short_description: evaluate a Python literal expression string
+  description:
+    - Evaluates the input string as a Python literal expression, returning the resulting data structure.
+    - Previous versions of Ansible applied this behavior to all template results in non-native Jinja mode.
+    - This filter provides a way to emulate the previous behavior.
+  notes:
+    - Directly calls Python's C(ast.literal_eval).
+  positional: _input
+  options:
+    _input:
+      description: Python literal string expression.
+      type: str
+      required: true
+    ignore_errors:
+      description: Whether to silently ignore all errors resulting from the literal_eval operation. If true, the input is silently returned unmodified when an error occurs.
+      type: bool
+      default: false
+
+EXAMPLES: |
+  - name: evaluate an expression comprised only of Python literals
+    assert:
+      that: (another_var | ansible._protomatter.python_literal_eval)[1] == 2  # in 2.19 and later, the explicit python_literal_eval emulates the old templating behavior
+    vars:
+      another_var: "{{ some_var }}"  # in 2.18 and earlier, indirection through templating caused implicit literal_eval, converting the value to a list 
+      some_var: "[1, 2]"  # a value that looks like a Python list literal embedded in a string
+
+RETURN:
+  _value:
+    description: Resulting data structure.
+    type: raw

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/tag_names.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils._internal._datatag import AnsibleTagHelper
+
+
+def tag_names(value: object) -> list[str]:
+    """Return a list of tag type names (if any) present on the given object."""
+    return sorted(tag_type.__name__ for tag_type in AnsibleTagHelper.tag_types(value))
+
+
+class FilterModule:
+    @staticmethod
+    def filters() -> dict[str, t.Callable]:
+        return dict(tag_names=tag_names)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/true_type.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import typing as t
+
+from ansible.plugins import accept_args_markers
+
+
+@accept_args_markers
+def true_type(obj: object) -> str:
+    """Internal filter to show the true type name of the given object, not just the base type name like the `debug` filter."""
+    return obj.__class__.__name__
+
+
+class FilterModule(object):
+    @staticmethod
+    def filters() -> dict[str, t.Callable]:
+        return dict(true_type=true_type)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/unmask.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import copy
+import dataclasses
+import typing as t
+
+from ansible._internal._templating._jinja_common import validate_arg_type
+from ansible._internal._templating._lazy_containers import _AnsibleLazyTemplateMixin
+from ansible._internal._templating._transform import _type_transform_mapping
+from ansible.errors import AnsibleError
+
+
+def unmask(value: object, type_names: str | list[str]) -> object:
+    """
+    Internal filter to suppress automatic type transformation in Jinja (e.g., WarningMessageDetail, DeprecationMessageDetail, ErrorDetail).
+    Lazy collection caching is in play - the first attempt to access a value in a given lazy container must be with unmasking in place, or the transformed value
+    will already be cached.
+    """
+    validate_arg_type("type_names", type_names, (str, list))
+
+    if isinstance(type_names, str):
+        check_type_names = [type_names]
+    else:
+        check_type_names = type_names
+
+    valid_type_names = {key.__name__ for key in _type_transform_mapping}
+    invalid_type_names = [type_name for type_name in check_type_names if type_name not in valid_type_names]
+
+    if invalid_type_names:
+        raise AnsibleError(f'Unknown type name(s): {", ".join(invalid_type_names)}', obj=type_names)
+
+    result: object
+
+    if isinstance(value, _AnsibleLazyTemplateMixin):
+        result = copy.copy(value)
+        result._lazy_options = dataclasses.replace(
+            result._lazy_options,
+            unmask_type_names=result._lazy_options.unmask_type_names | frozenset(check_type_names),
+        )
+    else:
+        result = value
+
+    return result
+
+
+class FilterModule(object):
+    @staticmethod
+    def filters() -> dict[str, t.Callable]:
+        return dict(unmask=unmask)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/lookup/config.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ansible.plugins.lookup import LookupBase
+
+
+class LookupModule(LookupBase):
+    """Specialized config lookup that applies data transformations on values that config cannot."""
+
+    def run(self, terms, variables=None, **kwargs):
+        if not terms or not (config_name := terms[0]):
+            raise ValueError("config name is required")
+
+        match config_name:
+            case 'DISPLAY_TRACEBACK':
+                # since config can't expand this yet, we need the post-processed version
+                from ansible.module_utils._internal._traceback import traceback_for
+
+                return traceback_for()
+            # DTFIX-FUTURE: plumb through normal config fallback
+            case _:
+                raise ValueError(f"Unknown config name {config_name!r}.")

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/lookup/config.yml

@@ -0,0 +1,2 @@
+DOCUMENTATION:
+  name: config

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/test/tagged.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils._internal import _datatag
+
+
+def tagged(value: t.Any) -> bool:
+    return bool(_datatag.AnsibleTagHelper.tag_types(value))
+
+
+class TestModule:
+    @staticmethod
+    def tests() -> dict[str, t.Callable]:
+        return dict(tagged=tagged)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/test/tagged.yml

@@ -0,0 +1,19 @@
+DOCUMENTATION:
+  name: tagged
+  author: Ansible Core
+  version_added: "2.19"
+  short_description: does the value have a data tag
+  description:
+    - Check if the provided value has a data tag.
+  options:
+    _input:
+      description: A value.
+      type: raw
+
+EXAMPLES: |
+    is_data_tagged: "{{ my_variable is ansible._protomatter.tagged }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the value has one or more data tags, otherwise C(False).
+    type: boolean

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/test/tagged_with.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils._internal import _datatag
+
+
+def tagged_with(value: t.Any, tag_name: str) -> bool:
+    if tag_type := _datatag._known_tag_type_map.get(tag_name):
+        return tag_type.is_tagged_on(value)
+
+    raise ValueError(f"Unknown tag name {tag_name!r}.")
+
+
+class TestModule:
+    @staticmethod
+    def tests() -> dict[str, t.Callable]:
+        return dict(tagged_with=tagged_with)

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/test/tagged_with.yml

@@ -0,0 +1,19 @@
+DOCUMENTATION:
+  name: tagged_with
+  author: Ansible Core
+  version_added: "2.19"
+  short_description: does the value have the specified data tag
+  description:
+    - Check if the provided value has the specified data tag.
+  options:
+    _input:
+      description: A value.
+      type: raw
+
+EXAMPLES: |
+    is_data_tagged: "{{ my_variable is ansible._protomatter.tagged_with('Origin') }}"
+
+RETURN:
+  _value:
+    description: Returns C(True) if the value has the specified data tag, otherwise C(False).
+    type: boolean

ansible/cli/__init__.py

@@ -7,8 +7,22 @@ from __future__ import annotations
 
 import locale
 import os
+import signal
 import sys
 
+
+# We overload the ``ansible`` adhoc command to provide the functionality for
+# ``SSH_ASKPASS``. This code is here, and not in ``adhoc.py`` to bypass
+# unnecessary code. The program provided to ``SSH_ASKPASS`` can only be invoked
+# as a singular command, ``python -m`` doesn't work for that use case, and we
+# aren't adding a new entrypoint at this time. Assume that if we are executing
+# and there is only a single item in argv plus the executable, and the env var
+# is set we are in ``SSH_ASKPASS`` mode
+if 1 <= len(sys.argv) <= 2 and os.path.basename(sys.argv[0]) == "ansible" and os.getenv('_ANSIBLE_SSH_ASKPASS_SHM'):
+    from ansible.cli import _ssh_askpass
+    _ssh_askpass.main()
+
+
 # Used for determining if the system is running a new enough python version
 # and should only restrict on our documented minimum versions
 if sys.version_info < (3, 11):
@@ -63,18 +77,7 @@ def initialize_locale():
 initialize_locale()
 
 
-from importlib.metadata import version
-from ansible.module_utils.compat.version import LooseVersion
-
-# Used for determining if the system is running a new enough Jinja2 version
-# and should only restrict on our documented minimum versions
-jinja2_version = version('jinja2')
-if jinja2_version < LooseVersion('3.0'):
-    raise SystemExit(
-        'ERROR: Ansible requires Jinja2 3.0 or newer on the controller. '
-        'Current version: %s' % jinja2_version
-    )
-
+import atexit
 import errno
 import getpass
 import subprocess
@@ -82,30 +85,42 @@ import traceback
 from abc import ABC, abstractmethod
 from pathlib import Path
 
+from ansible import _internal  # do not remove or defer; ensures controller-specific state is set early
+
+_internal.setup()
+
+from ansible.errors import AnsibleError, ExitCode
+
 try:
     from ansible import constants as C
     from ansible.utils.display import Display
     display = Display()
-except Exception as e:
-    print('ERROR: %s' % e, file=sys.stderr)
+except Exception as ex:
+    if isinstance(ex, AnsibleError):
+        ex_msg = ' '.join((ex.message, ex._help_text)).strip()
+    else:
+        ex_msg = str(ex)
+
+    print(f'ERROR: {ex_msg}\n\n{"".join(traceback.format_exception(ex))}', file=sys.stderr)
     sys.exit(5)
 
+
 from ansible import context
 from ansible.cli.arguments import option_helpers as opt_help
-from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleParserError
 from ansible.inventory.manager import InventoryManager
 from ansible.module_utils.six import string_types
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils.common.file import is_executable
+from ansible.module_utils.common.process import get_bin_path
 from ansible.parsing.dataloader import DataLoader
-from ansible.parsing.vault import PromptVaultSecret, get_file_vault_secret
+from ansible.parsing.vault import PromptVaultSecret, get_file_vault_secret, VaultSecretsContext
 from ansible.plugins.loader import add_all_plugin_dirs, init_plugin_loader
 from ansible.release import __version__
+from ansible.utils._ssh_agent import SshAgentClient
 from ansible.utils.collection_loader import AnsibleCollectionConfig
 from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path
 from ansible.utils.path import unfrackpath
-from ansible.utils.unsafe_proxy import to_unsafe_text
 from ansible.vars.manager import VariableManager
 
 try:
@@ -115,8 +130,79 @@ except ImportError:
     HAS_ARGCOMPLETE = False
 
 
+_SSH_AGENT_STDOUT_READ_TIMEOUT = 5  # seconds
+
+
+def _ssh_agent_timeout_handler(signum, frame):
+    raise TimeoutError
+
+
+def _launch_ssh_agent() -> None:
+    ssh_agent_cfg = C.config.get_config_value('SSH_AGENT')
+    match ssh_agent_cfg:
+        case 'none':
+            display.debug('SSH_AGENT set to none')
+            return
+        case 'auto':
+            try:
+                ssh_agent_bin = get_bin_path('ssh-agent')
+            except ValueError as e:
+                raise AnsibleError('SSH_AGENT set to auto, but cannot find ssh-agent binary') from e
+            ssh_agent_dir = os.path.join(C.DEFAULT_LOCAL_TMP, 'ssh_agent')
+            os.mkdir(ssh_agent_dir, 0o700)
+            sock = os.path.join(ssh_agent_dir, 'agent.sock')
+            display.vvv('SSH_AGENT: starting...')
+            try:
+                p = subprocess.Popen(
+                    [ssh_agent_bin, '-D', '-s', '-a', sock],
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                )
+            except OSError as e:
+                raise AnsibleError(
+                    f'Could not start ssh-agent: {e}'
+                ) from e
+
+            if p.poll() is not None:
+                raise AnsibleError(
+                    f'Could not start ssh-agent: rc={p.returncode} stderr="{p.stderr.read().decode()}"'
+                )
+
+            old_sigalrm_handler = signal.signal(signal.SIGALRM, _ssh_agent_timeout_handler)
+            signal.alarm(_SSH_AGENT_STDOUT_READ_TIMEOUT)
+            try:
+                stdout = p.stdout.read(13)
+            except TimeoutError:
+                stdout = b''
+            finally:
+                signal.alarm(0)
+                signal.signal(signal.SIGALRM, old_sigalrm_handler)
+
+            if stdout != b'SSH_AUTH_SOCK':
+                display.warning(
+                    f'The first 13 characters of stdout did not match the '
+                    f'expected SSH_AUTH_SOCK. This may not be the right binary, '
+                    f'or an incompatible agent: {stdout.decode()}'
+                )
+            display.vvv(f'SSH_AGENT: ssh-agent[{p.pid}] started and bound to {sock}')
+            atexit.register(p.terminate)
+        case _:
+            sock = ssh_agent_cfg
+
+    try:
+        with SshAgentClient(sock) as client:
+            client.list()
+    except Exception as e:
+        raise AnsibleError(
+            f'Could not communicate with ssh-agent using auth sock {sock}: {e}'
+        ) from e
+
+    os.environ['SSH_AUTH_SOCK'] = os.environ['ANSIBLE_SSH_AGENT'] = sock
+
+
 class CLI(ABC):
-    ''' code behind bin/ansible* programs '''
+    """ code behind bin/ansible* programs """
 
     PAGER = C.config.get_config_value('PAGER')
 
@@ -124,6 +210,7 @@ class CLI(ABC):
     # -S (chop long lines) -X (disable termcap init and de-init)
     LESS_OPTS = 'FRSX'
     SKIP_INVENTORY_DEFAULTS = False
+    USES_CONNECTION = False
 
     def __init__(self, args, callback=None):
         """
@@ -137,6 +224,9 @@ class CLI(ABC):
         self.parser = None
         self.callback = callback
 
+        self.show_devel_warning()
+
+    def show_devel_warning(self) -> None:
         if C.DEVEL_WARNING and __version__.endswith('dev0'):
             display.warning(
                 'You are running the development version of Ansible. You should only run Ansible from "devel" if '
@@ -208,7 +298,7 @@ class CLI(ABC):
     @staticmethod
     def setup_vault_secrets(loader, vault_ids, vault_password_files=None,
                             ask_vault_pass=None, create_new_password=False,
-                            auto_prompt=True):
+                            auto_prompt=True, initialize_context=True):
         # list of tuples
         vault_secrets = []
 
@@ -305,24 +395,22 @@ class CLI(ABC):
         if last_exception and not found_vault_secret:
             raise last_exception
 
+        if initialize_context:
+            VaultSecretsContext.initialize(VaultSecretsContext(vault_secrets))
+
         return vault_secrets
 
     @staticmethod
-    def _get_secret(prompt):
-
-        secret = getpass.getpass(prompt=prompt)
-        if secret:
-            secret = to_unsafe_text(secret)
-        return secret
+    def _get_secret(prompt: str) -> str:
+        return getpass.getpass(prompt=prompt)
 
     @staticmethod
     def ask_passwords():
-        ''' prompt for connection and become passwords if needed '''
+        """ prompt for connection and become passwords if needed """
 
         op = context.CLIARGS
         sshpass = None
         becomepass = None
-        become_prompt = ''
 
         become_prompt_method = "BECOME" if C.AGNOSTIC_BECOME_PROMPT else op['become_method'].upper()
 
@@ -344,10 +432,10 @@ class CLI(ABC):
         except EOFError:
             pass
 
-        return (sshpass, becomepass)
+        return sshpass, becomepass
 
     def validate_conflicts(self, op, runas_opts=False, fork_opts=False):
-        ''' check for conflicting options '''
+        """ check for conflicting options """
 
         if fork_opts:
             if op.forks < 1:
@@ -459,7 +547,7 @@ class CLI(ABC):
 
     @staticmethod
     def version_info(gitinfo=False):
-        ''' return full ansible version info '''
+        """ return full ansible version info """
         if gitinfo:
             # expensive call, user with care
             ansible_version_string = opt_help.version()
@@ -485,7 +573,7 @@ class CLI(ABC):
 
     @staticmethod
     def pager(text):
-        ''' find reasonable way to display text '''
+        """ find reasonable way to display text """
         # this is a much simpler form of what is in pydoc.py
         if not sys.stdout.isatty():
             display.display(text, screen_only=True)
@@ -504,7 +592,7 @@ class CLI(ABC):
 
     @staticmethod
     def pager_pipe(text):
-        ''' pipe text through a pager '''
+        """ pipe text through a pager """
         if 'less' in CLI.PAGER:
             os.environ['LESS'] = CLI.LESS_OPTS
         try:
@@ -515,8 +603,7 @@ class CLI(ABC):
         except KeyboardInterrupt:
             pass
 
-    @staticmethod
-    def _play_prereqs():
+    def _play_prereqs(self):
         # TODO: evaluate moving all of the code that touches ``AnsibleCollectionConfig``
         # into ``init_plugin_loader`` so that we can specifically remove
         # ``AnsibleCollectionConfig.playbook_paths`` to make it immutable after instantiation
@@ -547,6 +634,12 @@ class CLI(ABC):
                                                 auto_prompt=False)
         loader.set_vault_secrets(vault_secrets)
 
+        if self.USES_CONNECTION:
+            try:
+                _launch_ssh_agent()
+            except Exception as e:
+                raise AnsibleError('Failed to launch ssh agent', orig_exc=e)
+
         # create the inventory, and filter it based on the subset specified (if any)
         inventory = InventoryManager(loader=loader, sources=options['inventory'], cache=(not options.get('flush_cache')))
 
@@ -554,8 +647,19 @@ class CLI(ABC):
         # the code, ensuring a consistent view of global variables
         variable_manager = VariableManager(loader=loader, inventory=inventory, version_info=CLI.version_info(gitinfo=False))
 
+        # flush fact cache if requested
+        if options['flush_cache']:
+            CLI._flush_cache(inventory, variable_manager)
+
         return loader, inventory, variable_manager
 
+    @staticmethod
+    def _flush_cache(inventory, variable_manager):
+        variable_manager.clear_facts('localhost')
+        for host in inventory.list_hosts():
+            hostname = host.get_name()
+            variable_manager.clear_facts(hostname)
+
     @staticmethod
     def get_host_list(inventory, subset, pattern='all'):
 
@@ -575,10 +679,9 @@ class CLI(ABC):
         return hosts
 
     @staticmethod
-    def get_password_from_file(pwd_file):
-
+    def get_password_from_file(pwd_file: str) -> str:
         b_pwd_file = to_bytes(pwd_file)
-        secret = None
+
         if b_pwd_file == b'-':
             # ensure its read as bytes
             secret = sys.stdin.buffer.read()
@@ -598,14 +701,13 @@ class CLI(ABC):
 
             stdout, stderr = p.communicate()
             if p.returncode != 0:
-                raise AnsibleError("The password script %s returned an error (rc=%s): %s" % (pwd_file, p.returncode, stderr))
+                raise AnsibleError("The password script %s returned an error (rc=%s): %s" % (pwd_file, p.returncode, to_text(stderr)))
             secret = stdout
 
         else:
             try:
-                f = open(b_pwd_file, "rb")
-                secret = f.read().strip()
-                f.close()
+                with open(b_pwd_file, "rb") as password_file:
+                    secret = password_file.read().strip()
             except (OSError, IOError) as e:
                 raise AnsibleError("Could not read password file %s: %s" % (pwd_file, e))
 
@@ -614,7 +716,7 @@ class CLI(ABC):
         if not secret:
             raise AnsibleError('Empty password was provided from file (%s)' % pwd_file)
 
-        return to_unsafe_text(secret)
+        return to_text(secret)
 
     @classmethod
     def cli_executor(cls, args=None):
@@ -635,54 +737,22 @@ class CLI(ABC):
             else:
                 display.debug("Created the '%s' directory" % ansible_dir)
 
-            try:
-                args = [to_text(a, errors='surrogate_or_strict') for a in args]
-            except UnicodeError:
-                display.error('Command line args are not in utf-8, unable to continue.  Ansible currently only understands utf-8')
-                display.display(u"The full traceback was:\n\n%s" % to_text(traceback.format_exc()))
-                exit_code = 6
-            else:
-                cli = cls(args)
-                exit_code = cli.run()
-
-        except AnsibleOptionsError as e:
-            cli.parser.print_help()
-            display.error(to_text(e), wrap_text=False)
-            exit_code = 5
-        except AnsibleParserError as e:
-            display.error(to_text(e), wrap_text=False)
-            exit_code = 4
-    # TQM takes care of these, but leaving comment to reserve the exit codes
-    #    except AnsibleHostUnreachable as e:
-    #        display.error(str(e))
-    #        exit_code = 3
-    #    except AnsibleHostFailed as e:
-    #        display.error(str(e))
-    #        exit_code = 2
-        except AnsibleError as e:
-            display.error(to_text(e), wrap_text=False)
-            exit_code = 1
+            cli = cls(args)
+            exit_code = cli.run()
+        except AnsibleError as ex:
+            display.error(ex)
+            exit_code = ex._exit_code
         except KeyboardInterrupt:
             display.error("User interrupted execution")
-            exit_code = 99
-        except Exception as e:
-            if C.DEFAULT_DEBUG:
-                # Show raw stacktraces in debug mode, It also allow pdb to
-                # enter post mortem mode.
-                raise
-            have_cli_options = bool(context.CLIARGS)
-            display.error("Unexpected Exception, this is probably a bug: %s" % to_text(e), wrap_text=False)
-            if not have_cli_options or have_cli_options and context.CLIARGS['verbosity'] > 2:
-                log_only = False
-                if hasattr(e, 'orig_exc'):
-                    display.vvv('\nexception type: %s' % to_text(type(e.orig_exc)))
-                    why = to_text(e.orig_exc)
-                    if to_text(e) != why:
-                        display.vvv('\noriginal msg: %s' % why)
-            else:
-                display.display("to see the full traceback, use -vvv")
-                log_only = True
-            display.display(u"the full traceback was:\n\n%s" % to_text(traceback.format_exc()), log_only=log_only)
-            exit_code = 250
+            exit_code = ExitCode.KEYBOARD_INTERRUPT
+        except Exception as ex:
+            try:
+                raise AnsibleError("Unexpected Exception, this is probably a bug.") from ex
+            except AnsibleError as ex2:
+                # DTFIX-RELEASE: clean this up so we're not hacking the internals- re-wrap in an AnsibleCLIUnhandledError that always shows TB, or?
+                from ansible.module_utils._internal import _traceback
+                _traceback._is_traceback_enabled = lambda *_args, **_kwargs: True
+                display.error(ex2)
+                exit_code = ExitCode.UNKNOWN_ERROR
 
         sys.exit(exit_code)