Refactor tool execution logic (#189)

Author: ofek

CHANGELOG.md

@@ -8,6 +8,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
+***Changed:***
+
+- Rename the `[git.user]` section to `[tools.git.author]`
+- The `Tool` interface now uses a single execution context instead of the dedicated methods `format_command` and `env_vars`
+
+***Added:***
+
+- Add `git` tool
+- Add `[user]` section to the configuration
+- Add abstract context manager `execution_context` method to the `Tool` interface
+
 ## 0.26.0 - 2025-09-09
 
 ***Added:***

docs/reference/interface/tool.md

@@ -2,6 +2,8 @@
 
 -----
 
+::: dda.tools.base.ExecutionContext
+
 ::: dda.tools.base.Tool
     options:
       show_labels: true

src/dda/config/model/user.py

@@ -14,11 +14,12 @@ class UserConfig(Struct, frozen=True):
     name = "U.N. Owen"
     email = "void@some.where"
     ```
-    These values will be used for dda-related functionality, such as telemetry.
-    Both `email` and `name` can be set to `auto`, in which case they will be equal to the values in the [`[tools.git]`][dda.config.model.tools.GitConfig] section.
+
+    These values will be used for `dda`-related functionality like telemetry. Both `email` and `name` can be
+    set to `auto`, in which case they will be equal to the values in the
+    [`[tools.git.author]`][dda.config.model.tools.GitAuthorConfig] section.
     ///
     """
 
-    # Default username and email are equal to the values in [tools.git]
     name: str = "auto"
     email: str = "auto"

src/dda/tools/base.py

@@ -4,39 +4,36 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, NoReturn
 
+from msgspec import Struct
+
 from dda.utils.process import EnvVars
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
     from subprocess import CompletedProcess
-    from types import TracebackType
 
     from dda.cli.application import Application
 
 
-class Tool(ABC):
+class ExecutionContext(Struct, frozen=True):
     """
-    Base class for all tools. A tool is an executable that may require special
-    handling to be executed properly.
-
-    This class supports being used as a context manager and is guaranteed to be entered at all times.
+    Configuration for an execution of a tool.
     """
 
-    def __init__(self, app: Application) -> None:
-        self.__app = app
+    command: list[str]
+    env_vars: dict[str, str]
 
-    @abstractmethod
-    def format_command(self, command: list[str]) -> list[str]:
-        """
-        Format a command to be executed by the tool.
 
-        Parameters:
-            command: The command to format.
+class Tool(ABC):
+    """
+    A tool is an external program that may require special handling to be executed properly.
+    """
 
-        Returns:
-            The formatted command.
-        """
+    def __init__(self, app: Application) -> None:
+        self.__app = app
 
     @property
     def app(self) -> Application:
@@ -45,18 +42,24 @@ def app(self) -> Application:
         """
         return self.__app
 
-    def env_vars(self) -> dict[str, str]:  # noqa: PLR6301
+    @contextmanager
+    @abstractmethod
+    def execution_context(self, command: list[str]) -> Generator[ExecutionContext, None, None]:
         """
-        Returns:
-            The environment variables to set for the tool.
+        A context manager bound to the lifecycle of each tool execution.
+
+        Parameters:
+            command: The command to execute.
+
+        Yields:
+            The execution context.
         """
-        return {}
 
     def run(self, command: list[str], **kwargs: Any) -> int:
         """
-        Equivalent to [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run] with the `command` formatted
-        by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment variables set
-        by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -65,15 +68,15 @@ def run(self, command: list[str], **kwargs: Any) -> int:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            return self.app.subprocess.run(self.format_command(command), **kwargs)
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            return self.app.subprocess.run(context.command, **kwargs)
 
     def capture(self, command: list[str], **kwargs: Any) -> str:
         """
-        Equivalent to [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture] with the `command`
-        formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment
-        variables set by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -82,15 +85,15 @@ def capture(self, command: list[str], **kwargs: Any) -> str:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            return self.app.subprocess.capture(self.format_command(command), **kwargs)
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            return self.app.subprocess.capture(context.command, **kwargs)
 
     def wait(self, command: list[str], **kwargs: Any) -> None:
         """
-        Equivalent to [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait] with the `command` formatted
-        by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment variables set
-        by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -99,15 +102,15 @@ def wait(self, command: list[str], **kwargs: Any) -> None:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            self.app.subprocess.wait(self.format_command(command), **kwargs)
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            self.app.subprocess.wait(context.command, **kwargs)
 
     def exit_with(self, command: list[str], **kwargs: Any) -> NoReturn:
         """
-        Equivalent to [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with]
-        with the `command` formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and
-        the environment variables set by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -116,15 +119,15 @@ def exit_with(self, command: list[str], **kwargs: Any) -> NoReturn:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            self.app.subprocess.exit_with(self.format_command(command), **kwargs)
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            self.app.subprocess.exit_with(context.command, **kwargs)
 
     def attach(self, command: list[str], **kwargs: Any) -> CompletedProcess:
         """
-        Equivalent to [`SubprocessRunner.attach`][dda.utils.process.SubprocessRunner.attach] with the `command`
-        formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment
-        variables set by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.attach`][dda.utils.process.SubprocessRunner.attach] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -133,15 +136,15 @@ def attach(self, command: list[str], **kwargs: Any) -> CompletedProcess:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.attach`][dda.utils.process.SubprocessRunner.attach].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            return self.app.subprocess.attach(self.format_command(command), **kwargs)
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            return self.app.subprocess.attach(context.command, **kwargs)
 
     def redirect(self, command: list[str], **kwargs: Any) -> CompletedProcess:
         """
-        Equivalent to [`SubprocessRunner.redirect`][dda.utils.process.SubprocessRunner.redirect] with the `command`
-        formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment
-        variables set by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+        Equivalent to [`SubprocessRunner.redirect`][dda.utils.process.SubprocessRunner.redirect] with the tool's
+        [`execution_context`][dda.tools.base.Tool.execution_context] determining the final command and
+        environment variables.
 
         Parameters:
             command: The command to execute.
@@ -150,23 +153,17 @@ def redirect(self, command: list[str], **kwargs: Any) -> CompletedProcess:
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.redirect`][dda.utils.process.SubprocessRunner.redirect].
         """
-        with self:
-            self.__populate_env_vars(kwargs)
-            return self.app.subprocess.redirect(self.format_command(command), **kwargs)
-
-    def __populate_env_vars(self, kwargs: dict[str, Any]) -> None:
-        env_vars = self.env_vars()
-        if not env_vars:
-            return
+        with self.execution_context(command) as context:
+            _populate_env_vars(kwargs, context.env_vars)
+            return self.app.subprocess.redirect(context.command, **kwargs)
 
-        if isinstance(env := kwargs.get("env"), dict):
-            for key, value in env_vars.items():
-                env.setdefault(key, value)
-        else:
-            kwargs["env"] = EnvVars(env_vars)
 
-    def __enter__(self) -> None: ...
+def _populate_env_vars(kwargs: dict[str, Any], env_vars: dict[str, str]) -> None:
+    if not env_vars:
+        return
 
-    def __exit__(
-        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
-    ) -> None: ...
+    if isinstance(env := kwargs.get("env"), dict):
+        for key, value in env_vars.items():
+            env.setdefault(key, value)
+    else:
+        kwargs["env"] = EnvVars(env_vars)

src/dda/tools/bazel.py

@@ -3,13 +3,16 @@
 # SPDX-License-Identifier: MIT
 from __future__ import annotations
 
+from contextlib import contextmanager
 from functools import cached_property
 from typing import TYPE_CHECKING
 
-from dda.tools.base import Tool
+from dda.tools.base import ExecutionContext, Tool
 from dda.utils.platform import PLATFORM_ID, which
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
+
     from dda.utils.fs import Path
 
 
@@ -25,8 +28,9 @@ class Bazel(Tool):
     to an internal location if `bazel` nor `bazelisk` are already on PATH.
     """
 
-    def format_command(self, command: list[str]) -> list[str]:
-        return [self.path, *command]
+    @contextmanager
+    def execution_context(self, command: list[str]) -> Generator[ExecutionContext, None, None]:
+        yield ExecutionContext(command=[self.path, *command], env_vars={})
 
     @property
     def managed(self) -> bool:

src/dda/tools/docker.py

@@ -3,9 +3,14 @@
 # SPDX-License-Identifier: MIT
 from __future__ import annotations
 
+from contextlib import contextmanager
 from functools import cached_property
+from typing import TYPE_CHECKING
 
-from dda.tools.base import Tool
+from dda.tools.base import ExecutionContext, Tool
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
 
 
 class Docker(Tool):
@@ -20,11 +25,9 @@ class Docker(Tool):
     ```
     """
 
-    def format_command(self, command: list[str]) -> list[str]:
-        return [self.path, *command]
-
-    def env_vars(self) -> dict[str, str]:  # noqa: PLR6301
-        return {"DOCKER_CLI_HINTS": "0"}
+    @contextmanager
+    def execution_context(self, command: list[str]) -> Generator[ExecutionContext, None, None]:
+        yield ExecutionContext(command=[self.path, *command], env_vars={"DOCKER_CLI_HINTS": "0"})
 
     @cached_property
     def path(self) -> str:

src/dda/tools/git.py

@@ -3,11 +3,16 @@
 # SPDX-License-Identifier: MIT
 from __future__ import annotations
 
+from contextlib import contextmanager
 from functools import cached_property
+from typing import TYPE_CHECKING
 
-from dda.tools.base import Tool
+from dda.tools.base import ExecutionContext, Tool
 from dda.utils.git.constants import GitEnvVars
 
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
 
 class Git(Tool):
     """
@@ -18,27 +23,26 @@ class Git(Tool):
     ```
     """
 
-    def env_vars(self) -> dict[str, str]:
-        name = self.app.config.tools.git.author.name.strip()
-        email = self.app.config.tools.git.author.email.strip()
-        result = {}
-        if name:
-            result[GitEnvVars.AUTHOR_NAME] = name
-            result[GitEnvVars.COMMITTER_NAME] = name
-        if email:
-            result[GitEnvVars.AUTHOR_EMAIL] = email
-            result[GitEnvVars.COMMITTER_EMAIL] = email
-        return result
+    @contextmanager
+    def execution_context(self, command: list[str]) -> Generator[ExecutionContext, None, None]:
+        author_name = self.app.config.tools.git.author.name.strip()
+        author_email = self.app.config.tools.git.author.email.strip()
+        env_vars = {}
+        if author_name:
+            env_vars[GitEnvVars.AUTHOR_NAME] = author_name
+            env_vars[GitEnvVars.COMMITTER_NAME] = author_name
+        if author_email:
+            env_vars[GitEnvVars.AUTHOR_EMAIL] = author_email
+            env_vars[GitEnvVars.COMMITTER_EMAIL] = author_email
+
+        yield ExecutionContext(command=[self.path, *command], env_vars=env_vars)
 
     @cached_property
     def path(self) -> str:
         import shutil
 
         return shutil.which("git") or "git"
 
-    def format_command(self, command: list[str]) -> list[str]:
-        return [self.path, *command]
-
     @cached_property
     def author_name(self) -> str:
         """