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

ansible/keyword_desc.yml

@@ -13,7 +13,7 @@ become_method: Which method of privilege escalation to use (such as sudo or su).
 become_user: "User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user."
 block: List of tasks in a block.
 changed_when: "Conditional expression that overrides the task's normal 'changed' status."
-check_mode: A boolean that controls if a task is executed in 'check' mode. See :ref:`check_mode_dry`.
+check_mode: A boolean that controls if a task is run normally or avoids changes to the target and tries to report what it would have done (check mode/dry run). See :ref:`check_mode_dry`.
 collections: |
     List of collection namespaces to search for modules, plugins, and roles. See :ref:`collections_using_playbook`
 

ansible/module_utils/_internal/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import collections.abc as c
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.compat.typing import TypeGuard
+
+
+INTERMEDIATE_MAPPING_TYPES = (c.Mapping,)
+"""
+Mapping types which are supported for recursion and runtime usage, such as in serialization and templating.
+These will be converted to a simple Python `dict` before serialization or storage as a variable.
+"""
+
+INTERMEDIATE_ITERABLE_TYPES = (tuple, set, frozenset, c.Sequence)
+"""
+Iterable types which are supported for recursion and runtime usage, such as in serialization and templating.
+These will be converted to a simple Python `list` before serialization or storage as a variable.
+CAUTION: Scalar types which are sequences should be excluded when using this.
+"""
+
+ITERABLE_SCALARS_NOT_TO_ITERATE = (str, bytes)
+"""Scalars which are also iterable, and should thus be excluded from iterable checks."""
+
+
+def is_intermediate_mapping(value: object) -> TypeGuard[c.Mapping]:
+    """Returns `True` if `value` is a type supported for projection to a Python `dict`, otherwise returns `False`."""
+    return isinstance(value, INTERMEDIATE_MAPPING_TYPES)
+
+
+def is_intermediate_iterable(value: object) -> TypeGuard[c.Iterable]:
+    """Returns `True` if `value` is a type supported for projection to a Python `list`, otherwise returns `False`."""
+    return isinstance(value, INTERMEDIATE_ITERABLE_TYPES) and not isinstance(value, ITERABLE_SCALARS_NOT_TO_ITERATE)
+
+
+is_controller: bool = False
+"""Set to True automatically when this module is imported into an Ansible controller context."""
+
+
+def get_controller_serialize_map() -> dict[type, t.Callable]:
+    """
+    Called to augment serialization maps.
+    This implementation is replaced with the one from ansible._internal in controller contexts.
+    """
+    return {}
+
+
+def import_controller_module(_module_name: str, /) -> t.Any:
+    """
+    Called to conditionally import the named module in a controller context, otherwise returns `None`.
+    This implementation is replaced with the one from ansible._internal in controller contexts.
+    """
+    return None

ansible/module_utils/_internal/_ambient_context.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2024 Ansible Project
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+
+# deprecated: description='typing.Self exists in Python 3.11+' python_version='3.10'
+from ..compat import typing as t
+
+
+class AmbientContextBase:
+    """
+    An abstract base context manager that, once entered, will be accessible via its `current` classmethod to any code in the same
+    `contextvars` context (e.g. same thread/coroutine), until it is exited.
+    """
+
+    __slots__ = ('_contextvar_token',)
+
+    # DTFIX-FUTURE: subclasses need to be able to opt-in to blocking nested contexts of the same type (basically optional per-callstack singleton behavior)
+    # DTFIX-FUTURE: this class should enforce strict nesting of contexts; overlapping context lifetimes leads to incredibly difficult to
+    #        debug situations with undefined behavior, so it should fail fast.
+    # DTFIX-FUTURE: make frozen=True dataclass subclasses work (fix the mutability of the contextvar instance)
+
+    _contextvar: t.ClassVar[contextvars.ContextVar]  # pylint: disable=declare-non-slot  # pylint bug, see https://github.com/pylint-dev/pylint/issues/9950
+    _contextvar_token: contextvars.Token
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        cls._contextvar = contextvars.ContextVar(cls.__name__)
+
+    @classmethod
+    def when(cls, condition: bool, /, *args, **kwargs) -> t.Self | contextlib.nullcontext:
+        """Return an instance of the context if `condition` is `True`, otherwise return a `nullcontext` instance."""
+        return cls(*args, **kwargs) if condition else contextlib.nullcontext()
+
+    @classmethod
+    def current(cls, optional: bool = False) -> t.Self | None:
+        """
+        Return the currently active context value for the current thread or coroutine.
+        Raises ReferenceError if a context is not active, unless `optional` is `True`.
+        """
+        try:
+            return cls._contextvar.get()
+        except LookupError:
+            if optional:
+                return None
+
+            raise ReferenceError(f"A required {cls.__name__} context is not active.") from None
+
+    def __enter__(self) -> t.Self:
+        # DTFIX-FUTURE: actively block multiple entry
+        self._contextvar_token = self.__class__._contextvar.set(self)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.__class__._contextvar.reset(self._contextvar_token)
+        del self._contextvar_token

ansible/module_utils/_internal/_ansiballz/_extensions/_coverage.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import atexit
+import dataclasses
+import importlib.util
+import os
+import sys
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Code coverage options."""
+
+    config: str
+    output: str | None
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Bootstrap `coverage` for the current Ansible module invocation."""
+    options = Options(**args)
+
+    if options.output:
+        # Enable code coverage analysis of the module.
+        # This feature is for internal testing and may change without notice.
+        python_version_string = '.'.join(str(v) for v in sys.version_info[:2])
+        os.environ['COVERAGE_FILE'] = f'{options.output}=python-{python_version_string}=coverage'
+
+        import coverage
+
+        cov = coverage.Coverage(config_file=options.config)
+
+        def atexit_coverage() -> None:
+            cov.stop()
+            cov.save()
+
+        atexit.register(atexit_coverage)
+
+        cov.start()
+    else:
+        # Verify coverage is available without importing it.
+        # This will detect when a module would fail with coverage enabled with minimal overhead.
+        if importlib.util.find_spec('coverage') is None:
+            raise RuntimeError('Could not find the `coverage` Python module.')

ansible/module_utils/_internal/_ansiballz/_extensions/_pydevd.py

@@ -0,0 +1,62 @@
+"""
+Remote debugging support for AnsiballZ modules.
+
+To use with PyCharm:
+
+1) Choose an available port for PyCharm to listen on (e.g. 5678).
+2) Create a Python Debug Server using that port.
+3) Start the Python Debug Server.
+4) Ensure the correct version of `pydevd-pycharm` is installed for the interpreter(s) which will run the code being debugged.
+5) Configure Ansible with the `_ANSIBALLZ_DEBUGGER_CONFIG` option.
+   See `Options` below for the structure of the debugger configuration.
+   Example configuration using an environment variable:
+     export _ANSIBLE_ANSIBALLZ_DEBUGGER_CONFIG='{"module": "pydevd_pycharm", "settrace": {"host": "localhost", "port": 5678, "suspend": false}}'
+6) Set any desired breakpoints.
+7) Run Ansible commands.
+
+A similar process should work for other pydevd based debuggers, such as Visual Studio Code, but they have not been tested.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+import json
+import os
+import pathlib
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Debugger options for pydevd and its derivatives."""
+
+    module: str = 'pydevd'
+    """The Python module which will be imported and which provides the `settrace` method."""
+    settrace: dict[str, object] = dataclasses.field(default_factory=dict)
+    """The options to pass to the `{module}.settrace` method."""
+    source_mapping: dict[str, str] = dataclasses.field(default_factory=dict)
+    """
+    A mapping of source paths to provide to pydevd.
+    This setting is used internally by AnsiballZ and is not required unless Ansible CLI commands are run from a different system than your IDE.
+    In that scenario, use this setting instead of configuring source mapping in your IDE.
+    The key is a path known to the IDE.
+    The value is the same path as known to the Ansible CLI.
+    Both file paths and directories are supported.
+    """
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Enable remote debugging."""
+
+    options = Options(**args)
+    temp_dir = pathlib.Path(__file__).parent.parent.parent.parent.parent.parent
+    path_mapping = [[key, str(temp_dir / value)] for key, value in options.source_mapping.items()]
+
+    os.environ['PATHS_FROM_ECLIPSE_TO_PYTHON'] = json.dumps(path_mapping)
+
+    debugging_module = importlib.import_module(options.module)
+    debugging_module.settrace(**options.settrace)
+
+    pass  # when suspend is True, execution pauses here -- it's also a convenient place to put a breakpoint

ansible/module_utils/_internal/_ansiballz/_loader.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2024 Ansible Project
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+
+"""Support code for exclusive use by the AnsiballZ wrapper."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import runpy
+import sys
+import typing as t
+
+from ansible.module_utils import basic
+from ansible.module_utils._internal import _errors, _traceback, _messages, _ansiballz
+from ansible.module_utils.common.json import get_module_encoder, Direction
+
+
+def run_module(
+    *,
+    json_params: bytes,
+    profile: str,
+    module_fqn: str,
+    modlib_path: str,
+    extensions: dict[str, dict[str, object]],
+    init_globals: dict[str, t.Any] | None = None,
+) -> None:  # pragma: nocover
+    """Used internally by the AnsiballZ wrapper to run an Ansible module."""
+    try:
+        for extension, args in extensions.items():
+            # importing _ansiballz instead of _extensions avoids an unnecessary import when extensions are not in use
+            extension_module = importlib.import_module(f'{_ansiballz.__name__}._extensions.{extension}')
+            extension_module.run(args)
+
+        _run_module(
+            json_params=json_params,
+            profile=profile,
+            module_fqn=module_fqn,
+            modlib_path=modlib_path,
+            init_globals=init_globals,
+        )
+    except Exception as ex:  # not BaseException, since modules are expected to raise SystemExit
+        _handle_exception(ex, profile)
+
+
+def _run_module(
+    *,
+    json_params: bytes,
+    profile: str,
+    module_fqn: str,
+    modlib_path: str,
+    init_globals: dict[str, t.Any] | None = None,
+) -> None:
+    """Used internally by `_run_module` to run an Ansible module after coverage has been enabled (if applicable)."""
+    basic._ANSIBLE_ARGS = json_params
+    basic._ANSIBLE_PROFILE = profile
+
+    init_globals = init_globals or {}
+    init_globals.update(_module_fqn=module_fqn, _modlib_path=modlib_path)
+
+    # Run the module. By importing it as '__main__', it executes as a script.
+    runpy.run_module(mod_name=module_fqn, init_globals=init_globals, run_name='__main__', alter_sys=True)
+
+    # An Ansible module must print its own results and exit. If execution reaches this point, that did not happen.
+    raise RuntimeError('New-style module did not handle its own exit.')
+
+
+def _handle_exception(exception: BaseException, profile: str) -> t.NoReturn:
+    """Handle the given exception."""
+    result = dict(
+        failed=True,
+        exception=_messages.ErrorSummary(
+            event=_errors.EventFactory.from_exception(exception, _traceback.is_traceback_enabled(_traceback.TracebackEvent.ERROR)),
+        ),
+    )
+
+    encoder = get_module_encoder(profile, Direction.MODULE_TO_CONTROLLER)
+
+    print(json.dumps(result, cls=encoder))  # pylint: disable=ansible-bad-function
+
+    sys.exit(1)  # pylint: disable=ansible-bad-function

ansible/module_utils/_internal/_ansiballz/_respawn.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import inspect
+import sys
+
+from ... import basic
+from . import _respawn_wrapper
+
+
+def create_payload() -> str:
+    """Create and return an AnsiballZ payload for respawning a module."""
+    main = sys.modules['__main__']
+    code = inspect.getsource(_respawn_wrapper)
+
+    args = dict(
+        module_fqn=main._module_fqn,
+        modlib_path=main._modlib_path,
+        profile=basic._ANSIBLE_PROFILE,
+        json_params=basic._ANSIBLE_ARGS,
+    )
+
+    args_string = '\n'.join(f'{key}={value!r},' for key, value in args.items())
+
+    wrapper = f"""{code}
+
+if __name__ == "__main__":
+    _respawn_main(
+{args_string}
+)
+"""
+
+    return wrapper

ansible/module_utils/_internal/_ansiballz/_respawn_wrapper.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+def _respawn_main(
+    json_params: bytes,
+    profile: str,
+    module_fqn: str,
+    modlib_path: str,
+) -> None:
+    import sys
+
+    sys.path.insert(0, modlib_path)
+
+    from ansible.module_utils._internal._ansiballz import _loader
+
+    _loader.run_module(
+        json_params=json_params,
+        profile=profile,
+        module_fqn=module_fqn,
+        modlib_path=modlib_path,
+        extensions={},
+        init_globals=dict(_respawned=True),
+    )

ansible/module_utils/_internal/_concurrent/_daemon_threading.py

@@ -1,4 +1,5 @@
 """Proxy stdlib threading module that only supports non-joinable daemon threads."""
+
 # NB: all new local module attrs are _ prefixed to ensure an identical public attribute surface area to the module we're proxying
 
 from __future__ import annotations as _annotations

ansible/module_utils/_internal/_dataclass_validation.py

@@ -0,0 +1,217 @@
+# Copyright (c) 2024 Ansible Project
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+
+"""Code generation of __post_init__ methods for efficient dataclass field type checking at runtime."""
+
+from __future__ import annotations
+
+import atexit
+import functools
+import itertools
+import shutil
+import tempfile
+import types
+import typing as t
+
+_write_generated_code_to_disk = False
+
+# deprecated: description='types.UnionType is available in Python 3.10' python_version='3.9'
+try:
+    _union_type: type | None = types.UnionType  # type: ignore[attr-defined]
+    _union_types: tuple = (t.Union, types.UnionType)  # type: ignore[attr-defined]
+except AttributeError:
+    _union_type = None  # type: ignore[assignment]
+    _union_types = (t.Union,)  # type: ignore[assignment]
+
+
+def inject_post_init_validation(cls: type, allow_subclasses=False) -> None:
+    """Inject a __post_init__ field validation method on the given dataclass. An existing __post_init__ attribute must already exist."""
+    # DTFIX-FUTURE: when cls must have a __post_init__, enforcing it as a no-op would be nice, but is tricky on slotted dataclasses due to double-creation
+    post_validate_name = '_post_validate'
+    method_name = '__post_init__'
+    exec_globals: dict[str, t.Any] = {}
+    known_types: dict[type, str] = {}
+    lines: list[str] = []
+    field_type_hints = t.get_type_hints(cls)
+    indent = 1
+
+    def append_line(line: str) -> None:
+        """Append a line to the generated source at the current indentation level."""
+        lines.append((' ' * indent * 4) + line)
+
+    def register_type(target_type: type) -> str:
+        """Register the target type and return the local name."""
+        target_name = f'{target_type.__module__.replace(".", "_")}_{target_type.__name__}'
+
+        known_types[target_type] = target_name
+        exec_globals[target_name] = target_type
+
+        return target_name
+
+    def validate_value(target_name: str, target_ref: str, target_type: type) -> None:
+        """Generate code to validate the specified value."""
+        nonlocal indent
+
+        origin_type = t.get_origin(target_type)
+
+        if origin_type is t.ClassVar:
+            return  # ignore annotations which are not fields, indicated by the t.ClassVar annotation
+
+        allowed_types = _get_allowed_types(target_type)
+
+        # check value
+
+        if origin_type is t.Literal:
+            # DTFIX-FUTURE: support optional literals
+
+            values = t.get_args(target_type)
+
+            append_line(f"""if {target_ref} not in {values}:""")
+            append_line(f"""    raise ValueError(rf"{target_name} must be one of {values} instead of {{{target_ref}!r}}")""")
+
+        allowed_refs = [register_type(allowed_type) for allowed_type in allowed_types]
+        allowed_names = [repr(allowed_type) for allowed_type in allowed_types]
+
+        if allow_subclasses:
+            if len(allowed_refs) == 1:
+                append_line(f"""if not isinstance({target_ref}, {allowed_refs[0]}):""")
+            else:
+                append_line(f"""if not isinstance({target_ref}, ({', '.join(allowed_refs)})):""")
+        else:
+            if len(allowed_refs) == 1:
+                append_line(f"""if type({target_ref}) is not {allowed_refs[0]}:""")
+            else:
+                append_line(f"""if type({target_ref}) not in ({', '.join(allowed_refs)}):""")
+
+        append_line(f"""    raise TypeError(f"{target_name} must be {' or '.join(allowed_names)} instead of {{type({target_ref})}}")""")
+
+        # check elements (for containers)
+
+        if target_ref.startswith('self.'):
+            local_ref = target_ref[5:]
+        else:
+            local_ref = target_ref
+
+        if tuple in allowed_types:
+            tuple_type = _extract_type(target_type, tuple)
+
+            idx_ref = f'{local_ref}_idx'
+            item_ref = f'{local_ref}_item'
+            item_name = f'{target_name}[{{{idx_ref}!r}}]'
+            item_type, _ellipsis = t.get_args(tuple_type)
+
+            if _ellipsis is not ...:
+                raise ValueError(f"{cls} tuple fields must be a tuple of a single element type")
+
+            append_line(f"""if isinstance({target_ref}, {known_types[tuple]}):""")
+            append_line(f"""    for {idx_ref}, {item_ref} in enumerate({target_ref}):""")
+
+            indent += 2
+            validate_value(target_name=item_name, target_ref=item_ref, target_type=item_type)
+            indent -= 2
+
+        if list in allowed_types:
+            list_type = _extract_type(target_type, list)
+
+            idx_ref = f'{local_ref}_idx'
+            item_ref = f'{local_ref}_item'
+            item_name = f'{target_name}[{{{idx_ref}!r}}]'
+            (item_type,) = t.get_args(list_type)
+
+            append_line(f"""if isinstance({target_ref}, {known_types[list]}):""")
+            append_line(f"""    for {idx_ref}, {item_ref} in enumerate({target_ref}):""")
+
+            indent += 2
+            validate_value(target_name=item_name, target_ref=item_ref, target_type=item_type)
+            indent -= 2
+
+        if dict in allowed_types:
+            dict_type = _extract_type(target_type, dict)
+
+            key_ref, value_ref = f'{local_ref}_key', f'{local_ref}_value'
+            key_type, value_type = t.get_args(dict_type)
+            key_name, value_name = f'{target_name!r} key {{{key_ref}!r}}', f'{target_name}[{{{key_ref}!r}}]'
+
+            append_line(f"""if isinstance({target_ref}, {known_types[dict]}):""")
+            append_line(f"""    for {key_ref}, {value_ref} in {target_ref}.items():""")
+
+            indent += 2
+            validate_value(target_name=key_name, target_ref=key_ref, target_type=key_type)
+            validate_value(target_name=value_name, target_ref=value_ref, target_type=value_type)
+            indent -= 2
+
+    for field_name in cls.__annotations__:
+        validate_value(target_name=f'{{type(self).__name__}}.{field_name}', target_ref=f'self.{field_name}', target_type=field_type_hints[field_name])
+
+    if hasattr(cls, post_validate_name):
+        append_line(f"self.{post_validate_name}()")
+
+    if not lines:
+        return  # nothing to validate (empty dataclass)
+
+    if '__init__' in cls.__dict__ and not hasattr(cls, method_name):
+        raise ValueError(f"{cls} must have a {method_name!r} method to override when invoked after the '__init__' method is created")
+
+    if any(hasattr(parent, method_name) for parent in cls.__mro__[1:]):
+        lines.insert(0, f'    super({register_type(cls)}, self).{method_name}()')
+
+    lines.insert(0, f'def {method_name}(self):')
+
+    source = '\n'.join(lines) + '\n'
+
+    if _write_generated_code_to_disk:
+        tmp = tempfile.NamedTemporaryFile(mode='w+t', suffix=f'-{cls.__module__}.{cls.__name__}.py', delete=False, dir=_get_temporary_directory())
+
+        tmp.write(source)
+        tmp.flush()
+
+        filename = tmp.name
+    else:
+        filename = f'<string> generated for {cls}'
+
+    code = compile(source, filename, 'exec')
+
+    exec(code, exec_globals)
+    setattr(cls, method_name, exec_globals[method_name])
+
+
+@functools.lru_cache(maxsize=1)
+def _get_temporary_directory() -> str:
+    """Create a temporary directory and return its full path. The directory will be deleted when the process exits."""
+    temp_dir = tempfile.mkdtemp()
+
+    atexit.register(lambda: shutil.rmtree(temp_dir))
+
+    return temp_dir
+
+
+def _get_allowed_types(target_type: type) -> tuple[type, ...]:
+    """Return a tuple of types usable in instance checks for the given target_type."""
+    origin_type = t.get_origin(target_type)
+
+    if origin_type in _union_types:
+        allowed_types = tuple(set(itertools.chain.from_iterable(_get_allowed_types(arg) for arg in t.get_args(target_type))))
+    elif origin_type is t.Literal:
+        allowed_types = (str,)  # DTFIX-FUTURE: support non-str literal types
+    elif origin_type:
+        allowed_types = (origin_type,)
+    else:
+        allowed_types = (target_type,)
+
+    return allowed_types
+
+
+def _extract_type(target_type: type, of_type: type) -> type:
+    """Return `of_type` from `target_type`, where `target_type` may be a union."""
+    origin_type = t.get_origin(target_type)
+
+    if origin_type is of_type:  # pylint: disable=unidiomatic-typecheck
+        return target_type
+
+    if origin_type is t.Union or (_union_type and isinstance(target_type, _union_type)):
+        args = t.get_args(target_type)
+        extracted_types = [arg for arg in args if type(arg) is of_type or t.get_origin(arg) is of_type]  # pylint: disable=unidiomatic-typecheck
+        (extracted_type,) = extracted_types
+        return extracted_type
+
+    raise NotImplementedError(f'{target_type} is not supported')