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

ansible_test/_internal/debugging.py

@@ -0,0 +1,166 @@
+"""Setup and configure remote debugging."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import re
+
+from .util import (
+    cache,
+    display,
+    raw_command,
+    ApplicationError,
+)
+
+from .processes import (
+    Process,
+    get_current_process,
+)
+
+from .config import (
+    EnvironmentConfig,
+)
+
+from .metadata import (
+    DebuggerSettings,
+    DebuggerFlags,
+)
+
+from . import (
+    data_context,
+    CommonConfig,
+)
+
+
+def initialize_debugger(args: CommonConfig) -> None:
+    """Initialize the debugger settings before delegation."""
+    if not isinstance(args, EnvironmentConfig):
+        return
+
+    if args.metadata.loaded:
+        return  # after delegation
+
+    if collection := data_context().content.collection:
+        args.metadata.collection_root = collection.root
+
+    load_debugger_settings(args)
+
+
+def parse_debugger_settings(value: str) -> DebuggerSettings:
+    """Parse remote debugger settings and apply defaults."""
+    try:
+        settings = DebuggerSettings(**json.loads(value))
+    except Exception as ex:
+        raise ApplicationError(f"Invalid debugger settings: {ex}") from ex
+
+    if not settings.module:
+        if not settings.package or 'pydevd-pycharm' in settings.package:
+            module = 'pydevd_pycharm'
+        else:
+            module = 'pydevd'
+
+        settings = dataclasses.replace(settings, module=module)
+
+    if settings.package is None:
+        if settings.module == 'pydevd_pycharm':
+            if pycharm_version := detect_pycharm_version():
+                package = f'pydevd-pycharm~={pycharm_version}'
+            else:
+                package = None
+        else:
+            package = 'pydevd'
+
+        settings = dataclasses.replace(settings, package=package)
+
+    settings.settrace.setdefault('suspend', False)
+
+    if port := detect_pydevd_port():
+        settings = dataclasses.replace(settings, port=port)
+
+        if detect_pycharm_process():
+            # This only works with the default PyCharm debugger.
+            # Using it with PyCharm's "Python Debug Server" results in hangs in Ansible workers.
+            # Further investigation is required to understand the cause.
+            settings = dataclasses.replace(settings, args=settings.args + ['--multiprocess'])
+
+    return settings
+
+
+def load_debugger_settings(args: EnvironmentConfig) -> None:
+    """Load the remote debugger settings."""
+    if args.metadata.debugger_flags.on_demand:
+        # On-demand debugging only enables debugging if we're running under a debugger, otherwise it's a no-op.
+
+        if not detect_pydevd_port():
+            display.info('Debugging disabled because no debugger was detected.', verbosity=1)
+            args.metadata.debugger_flags = DebuggerFlags.all(False)
+            return
+
+        display.info('Enabling on-demand debugging.', verbosity=1)
+
+        if not args.metadata.debugger_flags.enable:
+            # Assume the user wants all debugging features enabled, since on-demand debugging with no features is pointless.
+            args.metadata.debugger_flags = DebuggerFlags.all(True)
+
+    if not args.metadata.debugger_flags.enable:
+        return
+
+    value = os.environ.get('ANSIBLE_TEST_REMOTE_DEBUGGER') or '{}'
+    settings = parse_debugger_settings(value)
+
+    display.info(f'>>> Debugger Settings\n{json.dumps(dataclasses.asdict(settings), indent=4)}', verbosity=3)
+
+    args.metadata.debugger_settings = settings
+
+
+@cache
+def detect_pydevd_port() -> int | None:
+    """Return the port for the pydevd instance hosting this process, or `None` if not detected."""
+    current_process = get_current_process_cached()
+    args = current_process.args
+
+    if any('/pydevd.py' in arg for arg in args) and (port_idx := args.index('--port')):
+        port = int(args[port_idx + 1])
+        display.info(f'Detected pydevd debugger port {port}.', verbosity=1)
+        return port
+
+    return None
+
+
+@cache
+def detect_pycharm_version() -> str | None:
+    """Return the version of PyCharm running ansible-test, or `None` if PyCharm was not detected. The result is cached."""
+    if pycharm := detect_pycharm_process():
+        output = raw_command([pycharm.args[0], '--version'], capture=True)[0]
+
+        if match := re.search('^Build #PY-(?P<version>[0-9.]+)$', output, flags=re.MULTILINE):
+            version = match.group('version')
+            display.info(f'Detected PyCharm version {version}.', verbosity=1)
+            return version
+
+    display.warning('Skipping installation of `pydevd-pycharm` since the running PyCharm version could not be detected.')
+
+    return None
+
+
+@cache
+def detect_pycharm_process() -> Process | None:
+    """Return the PyCharm process running ansible-test, or `None` if PyCharm was not detected. The result is cached."""
+    current_process = get_current_process_cached()
+    parent = current_process.parent
+
+    while parent:
+        if parent.path.name == 'pycharm':
+            return parent
+
+        parent = parent.parent
+
+    return None
+
+
+@cache
+def get_current_process_cached() -> Process:
+    """Return the current process. The result is cached."""
+    return get_current_process()

ansible_test/_internal/delegation.py

@@ -1,4 +1,5 @@
 """Delegate test execution to another environment."""
+
 from __future__ import annotations
 
 import collections.abc as c
@@ -112,23 +113,27 @@ def delegate(args: CommonConfig, host_state: HostState, exclude: list[str], requ
     assert isinstance(args, EnvironmentConfig)
 
     with delegation_context(args, host_state):
-        if isinstance(args, TestConfig):
-            args.metadata.ci_provider = get_ci_provider().code
-
-            make_dirs(ResultType.TMP.path)
+        args.metadata.ci_provider = get_ci_provider().code
 
-            with tempfile.NamedTemporaryFile(prefix='metadata-', suffix='.json', dir=ResultType.TMP.path) as metadata_fd:
-                args.metadata_path = os.path.join(ResultType.TMP.relative_path, os.path.basename(metadata_fd.name))
-                args.metadata.to_file(args.metadata_path)
+        make_dirs(ResultType.TMP.path)
 
-                try:
-                    delegate_command(args, host_state, exclude, require)
-                finally:
-                    args.metadata_path = None
-        else:
+        with metadata_context(args):
             delegate_command(args, host_state, exclude, require)
 
 
+@contextlib.contextmanager
+def metadata_context(args: EnvironmentConfig) -> t.Generator[None]:
+    """A context manager which exports delegation metadata."""
+    with tempfile.NamedTemporaryFile(prefix='metadata-', suffix='.json', dir=ResultType.TMP.path) as metadata_fd:
+        args.metadata_path = os.path.join(ResultType.TMP.relative_path, os.path.basename(metadata_fd.name))
+        args.metadata.to_file(args.metadata_path)
+
+        try:
+            yield
+        finally:
+            args.metadata_path = None
+
+
 def delegate_command(args: EnvironmentConfig, host_state: HostState, exclude: list[str], require: list[str]) -> None:
     """Delegate execution based on the provided host state."""
     con = host_state.controller_profile.get_origin_controller_connection()
@@ -188,6 +193,10 @@ def delegate_command(args: EnvironmentConfig, host_state: HostState, exclude: li
             networks = container.get_network_names()
 
             if networks is not None:
+                if args.metadata.debugger_flags.enable:
+                    networks = []
+                    display.warning('Skipping network isolation to enable remote debugging.')
+
                 for network in networks:
                     try:
                         con.disconnect_network(network)
@@ -333,6 +342,7 @@ def filter_options(
         ('--redact', 0, False),
         ('--no-redact', 0, not args.redact),
         ('--host-path', 1, args.host_path),
+        ('--metadata', 1, args.metadata_path),
     ]
 
     if isinstance(args, TestConfig):
@@ -345,7 +355,6 @@ def filter_options(
             ('--ignore-unstaged', 0, False),
             ('--changed-from', 1, False),
             ('--changed-path', 1, False),
-            ('--metadata', 1, args.metadata_path),
             ('--exclude', 1, exclude),
             ('--require', 1, require),
             ('--base-branch', 1, False),

ansible_test/_internal/dev/__init__.py

@@ -1,2 +1,3 @@
 """Development and testing support code. Enabled through the use of `--dev-*` command line options."""
+
 from __future__ import annotations

ansible_test/_internal/dev/container_probe.py

@@ -1,4 +1,5 @@
 """Diagnostic utilities to probe container cgroup behavior during development and testing (both manual and integration)."""
+
 from __future__ import annotations
 
 import dataclasses

ansible_test/_internal/diff.py

@@ -1,4 +1,5 @@
 """Diff parsing functions and classes."""
+
 from __future__ import annotations
 
 import re
@@ -128,14 +129,14 @@ class DiffParser:
             try:
                 self.action()
             except Exception as ex:
-                message = textwrap.dedent('''
+                message = textwrap.dedent("""
                 %s
 
                      Line: %d
                  Previous: %s
                   Current: %s
                 %s
-                ''').strip() % (
+                """).strip() % (
                     ex,
                     self.line_number,
                     self.previous_line or '',

ansible_test/_internal/docker_util.py

@@ -1,4 +1,5 @@
 """Functions for accessing docker via the docker cli."""
+
 from __future__ import annotations
 
 import dataclasses
@@ -49,7 +50,7 @@ DOCKER_COMMANDS = [
     'podman',
 ]
 
-UTILITY_IMAGE = 'quay.io/ansible/ansible-test-utility-container:3.1.0'
+UTILITY_IMAGE = 'quay.io/ansible/ansible-test-utility-container:3.2.0'
 
 # Max number of open files in a docker container.
 # Passed with --ulimit option to the docker run command.

ansible_test/_internal/encoding.py

@@ -1,4 +1,5 @@
 """Functions for encoding and decoding strings."""
+
 from __future__ import annotations
 
 import typing as t

ansible_test/_internal/executor.py

@@ -1,4 +1,5 @@
 """Execute Ansible tests."""
+
 from __future__ import annotations
 
 import typing as t

ansible_test/_internal/git.py

@@ -1,4 +1,5 @@
 """Wrapper around git command-line tools."""
+
 from __future__ import annotations
 
 import re

ansible_test/_internal/host_configs.py

@@ -1,4 +1,5 @@
 """Configuration for the test hosts requested by the user."""
+
 from __future__ import annotations
 
 import abc