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

ansible_test/_internal/metadata.py

@@ -1,10 +1,15 @@
 """Test metadata for passing data to delegated tests."""
+
 from __future__ import annotations
+
+import dataclasses
 import typing as t
 
 from .util import (
     display,
     generate_name,
+    ANSIBLE_TEST_ROOT,
+    ANSIBLE_LIB_ROOT,
 )
 
 from .io import (
@@ -21,13 +26,19 @@ from .diff import (
 class Metadata:
     """Metadata object for passing data to delegated tests."""
 
-    def __init__(self) -> None:
+    def __init__(self, debugger_flags: DebuggerFlags) -> None:
         """Initialize metadata."""
         self.changes: dict[str, tuple[tuple[int, int], ...]] = {}
         self.cloud_config: t.Optional[dict[str, dict[str, t.Union[int, str, bool]]]] = None
         self.change_description: t.Optional[ChangeDescription] = None
         self.ci_provider: t.Optional[str] = None
         self.session_id = generate_name()
+        self.ansible_lib_root = ANSIBLE_LIB_ROOT
+        self.ansible_test_root = ANSIBLE_TEST_ROOT
+        self.collection_root: str | None = None
+        self.debugger_flags = debugger_flags
+        self.debugger_settings: DebuggerSettings | None = None
+        self.loaded = False
 
     def populate_changes(self, diff: t.Optional[list[str]]) -> None:
         """Populate the changeset using the given diff."""
@@ -54,8 +65,13 @@ class Metadata:
             changes=self.changes,
             cloud_config=self.cloud_config,
             ci_provider=self.ci_provider,
-            change_description=self.change_description.to_dict(),
+            change_description=self.change_description.to_dict() if self.change_description else None,
             session_id=self.session_id,
+            ansible_lib_root=self.ansible_lib_root,
+            ansible_test_root=self.ansible_test_root,
+            collection_root=self.collection_root,
+            debugger_flags=dataclasses.asdict(self.debugger_flags),
+            debugger_settings=dataclasses.asdict(self.debugger_settings) if self.debugger_settings else None,
         )
 
     def to_file(self, path: str) -> None:
@@ -75,12 +91,20 @@ class Metadata:
     @staticmethod
     def from_dict(data: dict[str, t.Any]) -> Metadata:
         """Return metadata loaded from the specified dictionary."""
-        metadata = Metadata()
+        metadata = Metadata(
+            debugger_flags=DebuggerFlags(**data['debugger_flags']),
+        )
+
         metadata.changes = data['changes']
         metadata.cloud_config = data['cloud_config']
         metadata.ci_provider = data['ci_provider']
-        metadata.change_description = ChangeDescription.from_dict(data['change_description'])
+        metadata.change_description = ChangeDescription.from_dict(data['change_description']) if data['change_description'] else None
         metadata.session_id = data['session_id']
+        metadata.ansible_lib_root = data['ansible_lib_root']
+        metadata.ansible_test_root = data['ansible_test_root']
+        metadata.collection_root = data['collection_root']
+        metadata.debugger_settings = DebuggerSettings(**data['debugger_settings']) if data['debugger_settings'] else None
+        metadata.loaded = True
 
         return metadata
 
@@ -129,3 +153,70 @@ class ChangeDescription:
         changes.no_integration_paths = data['no_integration_paths']
 
         return changes
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class DebuggerSettings:
+    """Settings for remote debugging."""
+
+    module: str | None = None
+    """
+    The Python module to import.
+    This should be pydevd or a derivative.
+    If not provided it will be auto-detected.
+    """
+
+    package: str | None = None
+    """
+    The Python package to install for debugging.
+    If `None` then the package will be auto-detected.
+    If an empty string, then no package will be installed.
+    """
+
+    settrace: dict[str, object] = dataclasses.field(default_factory=dict)
+    """
+    Options to pass to the `{module}.settrace` method.
+    Used for running AnsiballZ modules only.
+    The `host` and `port` options will be provided by ansible-test.
+    The `suspend` option defaults to `False`.
+    """
+
+    args: list[str] = dataclasses.field(default_factory=list)
+    """
+    Arguments to pass to `pydevd` on the command line.
+    Used for running Ansible CLI programs only.
+    The `--client` and `--port` options will be provided by ansible-test.
+    """
+
+    port: int = 5678
+    """
+    The port on the origin host which is listening for incoming connections from pydevd.
+    SSH port forwarding will be automatically configured for non-local hosts to connect to this port as needed.
+    """
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class DebuggerFlags:
+    """Flags for enabling specific debugging features."""
+
+    self: bool = False
+    """Debug ansible-test itself."""
+
+    ansiballz: bool = False
+    """Debug AnsiballZ modules."""
+
+    cli: bool = False
+    """Debug Ansible CLI programs other than ansible-test."""
+
+    on_demand: bool = False
+    """Enable debugging features only when ansible-test is running under a debugger."""
+
+    @property
+    def enable(self) -> bool:
+        """Return `True` if any debugger feature other than on-demand is enabled."""
+        return any(getattr(self, field.name) for field in dataclasses.fields(self) if field.name != 'on_demand')
+
+    @classmethod
+    def all(cls, enabled: bool) -> t.Self:
+        """Return a `DebuggerFlags` instance with all flags enabled or disabled."""
+        return cls(**{field.name: enabled for field in dataclasses.fields(cls)})

ansible_test/_internal/payload.py

@@ -1,4 +1,5 @@
 """Payload management for sending Ansible files and test content to other systems (VMs, containers)."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/processes.py

@@ -0,0 +1,80 @@
+"""Wrappers around `ps` for querying running processes."""
+
+from __future__ import annotations
+
+import collections
+import dataclasses
+import os
+import pathlib
+import shlex
+
+from ansible_test._internal.util import raw_command
+
+
+@dataclasses.dataclass(frozen=True)
+class ProcessData:
+    """Data about a running process."""
+
+    pid: int
+    ppid: int
+    command: str
+
+
+@dataclasses.dataclass(frozen=True)
+class Process:
+    """A process in the process tree."""
+
+    pid: int
+    command: str
+    parent: Process | None = None
+    children: tuple[Process, ...] = dataclasses.field(default_factory=tuple)
+
+    @property
+    def args(self) -> list[str]:
+        """The list of arguments that make up `command`."""
+        return shlex.split(self.command)
+
+    @property
+    def path(self) -> pathlib.Path:
+        """The path to the process."""
+        return pathlib.Path(self.args[0])
+
+
+def get_process_data(pids: list[int] | None = None) -> list[ProcessData]:
+    """Return a list of running processes."""
+    if pids:
+        args = ['-p', ','.join(map(str, pids))]
+    else:
+        args = ['-A']
+
+    lines = raw_command(['ps'] + args + ['-o', 'pid,ppid,command'], capture=True)[0].splitlines()[1:]
+    processes = [ProcessData(pid=int(pid), ppid=int(ppid), command=command) for pid, ppid, command in (line.split(maxsplit=2) for line in lines)]
+
+    return processes
+
+
+def get_process_tree() -> dict[int, Process]:
+    """Return the process tree."""
+    processes = get_process_data()
+    pid_to_process: dict[int, Process] = {}
+    pid_to_children: dict[int, list[Process]] = collections.defaultdict(list)
+
+    for data in processes:
+        pid_to_process[data.pid] = process = Process(pid=data.pid, command=data.command)
+
+        if data.ppid:
+            pid_to_children[data.ppid].append(process)
+
+    for data in processes:
+        pid_to_process[data.pid] = dataclasses.replace(
+            pid_to_process[data.pid],
+            parent=pid_to_process.get(data.ppid),
+            children=tuple(pid_to_children[data.pid]),
+        )
+
+    return pid_to_process
+
+
+def get_current_process() -> Process:
+    """Return the current process along with its ancestors and descendants."""
+    return get_process_tree()[os.getpid()]

ansible_test/_internal/provider/__init__.py

@@ -1,4 +1,5 @@
 """Provider (plugin) infrastructure for ansible-test."""
+
 from __future__ import annotations
 
 import abc

ansible_test/_internal/provider/layout/__init__.py

@@ -1,4 +1,5 @@
 """Code for finding content."""
+
 from __future__ import annotations
 
 import abc

ansible_test/_internal/provider/layout/ansible.py

@@ -1,4 +1,5 @@
 """Layout provider for Ansible source."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/provider/layout/collection.py

@@ -1,4 +1,5 @@
 """Layout provider for Ansible collections."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/provider/layout/unsupported.py

@@ -1,4 +1,5 @@
 """Layout provider for an unsupported directory layout."""
+
 from __future__ import annotations
 
 from . import (

ansible_test/_internal/provider/source/__init__.py

@@ -1,4 +1,5 @@
 """Common code for source providers."""
+
 from __future__ import annotations
 
 import abc

ansible_test/_internal/provider/source/git.py

@@ -1,4 +1,5 @@
 """Source provider for a content root managed by git version control."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/provider/source/installed.py

@@ -1,4 +1,5 @@
 """Source provider for content which has been installed."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/provider/source/unsupported.py

@@ -1,4 +1,5 @@
 """Source provider to use when the layout is unsupported."""
+
 from __future__ import annotations
 
 from . import (

ansible_test/_internal/provider/source/unversioned.py

@@ -1,4 +1,5 @@
 """Fallback source provider when no other provider matches the content root."""
+
 from __future__ import annotations
 
 import os

ansible_test/_internal/provisioning.py

@@ -1,4 +1,5 @@
 """Provision hosts for running tests."""
+
 from __future__ import annotations
 
 import collections.abc as c
@@ -115,9 +116,11 @@ def prepare_profiles(
     else:
         run_pypi_proxy(args, targets_use_pypi)
 
+        controller_host_profile = t.cast(ControllerHostProfile, create_host_profile(args, args.controller, None))
+
         host_state = HostState(
-            controller_profile=t.cast(ControllerHostProfile, create_host_profile(args, args.controller, True)),
-            target_profiles=[create_host_profile(args, target, False) for target in args.targets],
+            controller_profile=controller_host_profile,
+            target_profiles=[create_host_profile(args, target, controller_host_profile) for target in args.targets],
         )
 
         if args.prime_containers:
@@ -136,7 +139,9 @@ def prepare_profiles(
             if not skip_setup:
                 profile.setup()
 
-        dispatch_jobs([(profile, WrappedThread(functools.partial(provision, profile))) for profile in host_state.profiles])
+        dispatch_jobs(
+            [(profile, WrappedThread(functools.partial(provision, profile), f'Provision: {profile}')) for profile in host_state.profiles]
+        )
 
         host_state.controller_profile.configure()
 
@@ -156,7 +161,9 @@ def prepare_profiles(
             if requirements:
                 requirements(profile)
 
-        dispatch_jobs([(profile, WrappedThread(functools.partial(configure, profile))) for profile in host_state.target_profiles])
+        dispatch_jobs(
+            [(profile, WrappedThread(functools.partial(configure, profile), f'Configure: {profile}')) for profile in host_state.target_profiles]
+        )
 
     return host_state
 

ansible_test/_internal/pypi_proxy.py

@@ -1,4 +1,5 @@
 """PyPI proxy management."""
+
 from __future__ import annotations
 
 import os
@@ -69,7 +70,7 @@ def run_pypi_proxy(args: EnvironmentConfig, targets_use_pypi: bool) -> None:
         display.warning('Unable to use the PyPI proxy because Docker is not available. Installation of packages using `pip` may fail.')
         return
 
-    image = 'quay.io/ansible/pypi-test-container:3.2.0'
+    image = 'quay.io/ansible/pypi-test-container:3.3.0'
     port = 3141
 
     run_support_container(
@@ -134,11 +135,11 @@ def configure_target_pypi_proxy(args: EnvironmentConfig, profile: HostProfile, p
 def configure_pypi_proxy_pip(args: EnvironmentConfig, profile: HostProfile, pypi_endpoint: str, pypi_hostname: str) -> None:
     """Configure a custom index for pip based installs."""
     pip_conf_path = os.path.expanduser('~/.pip/pip.conf')
-    pip_conf = '''
+    pip_conf = """
 [global]
 index-url = {0}
 trusted-host = {1}
-'''.format(pypi_endpoint, pypi_hostname).strip()
+""".format(pypi_endpoint, pypi_hostname).strip()
 
     def pip_conf_cleanup() -> None:
         """Remove custom pip PyPI config."""
@@ -159,10 +160,10 @@ trusted-host = {1}
 def configure_pypi_proxy_easy_install(args: EnvironmentConfig, profile: HostProfile, pypi_endpoint: str) -> None:
     """Configure a custom index for easy_install based installs."""
     pydistutils_cfg_path = os.path.expanduser('~/.pydistutils.cfg')
-    pydistutils_cfg = '''
+    pydistutils_cfg = """
 [easy_install]
 index_url = {0}
-'''.format(pypi_endpoint).strip()
+""".format(pypi_endpoint).strip()
 
     if os.path.exists(pydistutils_cfg_path) and not profile.config.is_managed:
         raise ApplicationError('Refusing to overwrite existing file: %s' % pydistutils_cfg_path)

ansible_test/_internal/python_requirements.py

@@ -1,4 +1,5 @@
 """Python requirements management"""
+
 from __future__ import annotations
 
 import base64
@@ -54,6 +55,11 @@ from .coverage_util import (
     get_coverage_version,
 )
 
+if t.TYPE_CHECKING:
+    from .host_profiles import (
+        HostProfile,
+    )
+
 QUIET_PIP_SCRIPT_PATH = os.path.join(ANSIBLE_TEST_TARGET_ROOT, 'setup', 'quiet_pip.py')
 REQUIREMENTS_SCRIPT_PATH = os.path.join(ANSIBLE_TEST_TARGET_ROOT, 'setup', 'requirements.py')
 
@@ -121,6 +127,7 @@ class PipBootstrap(PipCommand):
 
 def install_requirements(
     args: EnvironmentConfig,
+    host_profile: HostProfile | None,
     python: PythonConfig,
     ansible: bool = False,
     command: bool = False,
@@ -132,6 +139,7 @@ def install_requirements(
     create_result_directories(args)
 
     if not requirements_allowed(args, controller):
+        post_install(host_profile)
         return
 
     if command and isinstance(args, (UnitsConfig, IntegrationConfig)) and args.coverage:
@@ -160,7 +168,17 @@ def install_requirements(
         sanity=None,
     )
 
+    from .host_profiles import DebuggableProfile
+
+    if isinstance(host_profile, DebuggableProfile) and host_profile.debugging_enabled and args.metadata.debugger_settings.package:
+        commands.append(PipInstall(
+            requirements=[],
+            constraints=[],
+            packages=[args.metadata.debugger_settings.package],
+        ))
+
     if not commands:
+        post_install(host_profile)
         return
 
     run_pip(args, python, commands, connection)
@@ -169,6 +187,16 @@ def install_requirements(
     if any(isinstance(command, PipInstall) and command.has_package('pyyaml') for command in commands):
         check_pyyaml(python)
 
+    post_install(host_profile)
+
+
+def post_install(host_profile: HostProfile) -> None:
+    """Operations to perform after requirements are installed."""
+    from .host_profiles import DebuggableProfile
+
+    if isinstance(host_profile, DebuggableProfile):
+        host_profile.activate_debugger()
+
 
 def collect_bootstrap(python: PythonConfig) -> list[PipCommand]:
     """Return the details necessary to bootstrap pip into an empty virtual environment."""

ansible_test/_internal/ssh.py

@@ -1,4 +1,5 @@
 """High level functions for working with SSH."""
+
 from __future__ import annotations
 
 import dataclasses
@@ -12,7 +13,6 @@ import shlex
 import typing as t
 
 from .encoding import (
-    to_bytes,
     to_text,
 )
 
@@ -222,13 +222,10 @@ def run_ssh_command(
     cmd_show = shlex.join(cmd)
     display.info('Run background command: %s' % cmd_show, verbosity=1, truncate=True)
 
-    cmd_bytes = [to_bytes(arg) for arg in cmd]
-    env_bytes = dict((to_bytes(k), to_bytes(v)) for k, v in env.items())
-
     if args.explain:
         process = SshProcess(None)
     else:
-        process = SshProcess(subprocess.Popen(cmd_bytes, env=env_bytes, bufsize=-1,  # pylint: disable=consider-using-with
+        process = SshProcess(subprocess.Popen(cmd, env=env, bufsize=-1,  # pylint: disable=consider-using-with
                                               stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE))
 
     return process

ansible_test/_internal/target.py

@@ -1,4 +1,5 @@
 """Test target identification, iteration and inclusion/exclusion."""
+
 from __future__ import annotations
 
 import collections
@@ -581,6 +582,14 @@ class IntegrationTarget(CompletionTarget):
         else:
             static_aliases = tuple()
 
+        # non-group aliases which need to be extracted before group mangling occurs
+
+        self.env_set: dict[str, str] = {
+            match.group('key'): match.group('value') for match in (
+                re.match(r'env/set/(?P<key>[^/]+)/(?P<value>.*)', alias) for alias in static_aliases
+            ) if match
+        }
+
         # modules
 
         if self.name in modules:

ansible_test/_internal/test.py

@@ -1,4 +1,5 @@
 """Classes for storing and processing test results."""
+
 from __future__ import annotations
 
 import collections.abc as c
@@ -141,12 +142,12 @@ class TestTimeout(TestResult):
 
         # Include a leading newline to improve readability on Shippable "Tests" tab.
         # Without this, the first line becomes indented.
-        output = '''
+        output = """
 One or more of the following situations may be responsible:
 
 - Code changes have resulted in tests that hang or run for an excessive amount of time.
 - Tests have been added which exceed the time limit when combined with existing tests.
-- Test infrastructure and/or external dependencies are operating slower than normal.'''
+- Test infrastructure and/or external dependencies are operating slower than normal."""
 
         if args.coverage:
             output += '\n- Additional overhead from collecting code coverage has resulted in tests exceeding the time limit.'

ansible_test/_internal/thread.py

@@ -1,4 +1,5 @@
 """Python threading tools."""
+
 from __future__ import annotations
 
 import collections.abc as c
@@ -16,11 +17,12 @@ TCallable = t.TypeVar('TCallable', bound=t.Callable[..., t.Any])
 class WrappedThread(threading.Thread):
     """Wrapper around Thread which captures results and exceptions."""
 
-    def __init__(self, action: c.Callable[[], t.Any]) -> None:
+    def __init__(self, action: c.Callable[[], t.Any], name: str) -> None:
         super().__init__()
         self._result: queue.Queue[t.Any] = queue.Queue()
         self.action = action
         self.result = None
+        self.name = name
 
     def run(self) -> None:
         """

ansible_test/_internal/timeout.py

@@ -1,4 +1,5 @@
 """Timeout management for tests."""
+
 from __future__ import annotations
 
 import dataclasses
@@ -125,6 +126,6 @@ def configure_test_timeout(args: TestConfig) -> None:
 
     signal.signal(signal.SIGUSR1, timeout_handler)
 
-    instance = WrappedThread(functools.partial(timeout_waiter, timeout_remaining.total_seconds()))
+    instance = WrappedThread(functools.partial(timeout_waiter, timeout_remaining.total_seconds()), 'Timeout Watchdog')
     instance.daemon = True
     instance.start()