Add support for exec subcommand (#2142)

* Add support for exec subcommand

Run arbitrary commands within your tox environment. Don't abuse it.

Signed-off-by: Bernát Gábor <[email protected]>

* Update docs/changelog/1790.feature.rst

Co-authored-by: Jürgen Gmach <[email protected]>

* reindent

Signed-off-by: Bernát Gábor <[email protected]>

Co-authored-by: Jürgen Gmach <[email protected]>

Author: gaborbernat

docs/changelog/1790.feature.rst

@@ -0,0 +1,2 @@
+Add ``exec`` subcommand that allows users to run an arbitrary command within the tox environment (without needing to
+modify their configuration) - by :user:`gaborbernat`.

src/tox/plugin/manager.py

@@ -8,7 +8,7 @@
 from tox.config.loader import api as loader_api
 from tox.config.sets import ConfigSet
 from tox.session import state
-from tox.session.cmd import depends, devenv, legacy, list_env, quickstart, show_config, version_flag
+from tox.session.cmd import depends, devenv, exec_, legacy, list_env, quickstart, show_config, version_flag
 from tox.session.cmd.run import parallel, sequential
 from tox.tox_env import package as package_api
 from tox.tox_env.python.virtual_env import runner
@@ -31,6 +31,7 @@ def __init__(self) -> None:
             api,
             legacy,
             version_flag,
+            exec_,
             quickstart,
             show_config,
             devenv,

src/tox/session/cmd/devenv.py

@@ -12,14 +12,10 @@
 
 @impl
 def tox_add_option(parser: ToxParser) -> None:
-    our = parser.add_command(
-        "devenv",
-        ["d"],
-        "sets up a development environment at ENVDIR based on the tox configuration specified ",
-        devenv,
-    )
+    help_msg = "sets up a development environment at ENVDIR based on the tox configuration specified "
+    our = parser.add_command("devenv", ["d"], help_msg, devenv)
     our.add_argument("devenv_path", metavar="path", default=Path("venv").absolute(), nargs="?")
-    env_list_flag(our, default=CliEnv("py"))
+    env_list_flag(our, default=CliEnv("py"), multiple=False)
     env_run_create_flags(our, mode="devenv")
 
 

src/tox/session/cmd/exec_.py

@@ -0,0 +1,35 @@
+"""
+Execute a command in a tox environment.
+"""
+from tox.config.cli.parser import ToxParser
+from tox.config.loader.memory import MemoryLoader
+from tox.config.types import Command
+from tox.plugin import impl
+from tox.report import HandledError
+from tox.session.cmd.run.common import env_run_create_flags
+from tox.session.cmd.run.sequential import run_sequential
+from tox.session.common import CliEnv, env_list_flag
+from tox.session.state import State
+
+
+@impl
+def tox_add_option(parser: ToxParser) -> None:
+    our = parser.add_command("exec", ["e"], "execute an arbitrary command within a tox environment", exec_)
+    our.epilog = "For example: tox exec -e py39 -- python --version"
+    env_list_flag(our, default=CliEnv("py"), multiple=False)
+    env_run_create_flags(our, mode="exec")
+
+
+def exec_(state: State) -> int:
+    if not state.conf.pos_args:
+        raise HandledError("You must specify a command as positional arguments, use -- <command>")
+    env_list = list(state.env_list(everything=False))
+    if len(env_list) != 1:
+        raise HandledError(f"exactly one target environment allowed in exec mode but found {', '.join(env_list)}")
+    loader = MemoryLoader(  # these configuration values are loaded from in-memory always (no file conf)
+        commands_pre=[],
+        commands=[Command(list(state.conf.pos_args))],
+        commands_post=[],
+    )
+    state.conf.get_env(env_list[0], loaders=[loader])
+    return run_sequential(state)

src/tox/session/common.py

@@ -39,11 +39,10 @@ def use_default_list(self) -> bool:
         return len(list(self)) == 0
 
 
-def env_list_flag(parser: ArgumentParser, default: Optional[CliEnv] = None) -> None:
-    parser.add_argument(
-        "-e",
-        dest="env",
-        help="tox environment(s) to run (ALL -> all environments, not set -> <env_list>)",
-        default=CliEnv() if default is None else default,
-        type=CliEnv,
+def env_list_flag(parser: ArgumentParser, default: Optional[CliEnv] = None, multiple: bool = True) -> None:
+    help_msg = (
+        "tox environment(s) to run (ALL -> all environments, not set -> <env_list>)"
+        if multiple
+        else "tox environment to run"
     )
+    parser.add_argument("-e", dest="env", help=help_msg, default=CliEnv() if default is None else default, type=CliEnv)

tests/config/cli/conftest.py

@@ -4,6 +4,7 @@
 
 from tox.session.cmd.depends import depends
 from tox.session.cmd.devenv import devenv
+from tox.session.cmd.exec_ import exec_
 from tox.session.cmd.legacy import legacy
 from tox.session.cmd.list_env import list_env
 from tox.session.cmd.quickstart import quickstart
@@ -32,4 +33,6 @@ def core_handlers() -> Dict[str, Callable[[State], int]]:
         "depends": depends,
         "le": legacy,
         "legacy": legacy,
+        "e": exec_,
+        "exec": exec_,
     }

tests/session/cmd/test_exec_.py

@@ -0,0 +1,33 @@
+import sys
+from typing import List
+
+import pytest
+
+from tox.pytest import ToxProjectCreator
+
+
+@pytest.mark.parametrize("trail", [[], ["--"]], ids=["no_posargs", "empty_posargs"])
+def test_exec_fail_no_posargs(tox_project: ToxProjectCreator, trail: List[str]) -> None:
+    outcome = tox_project({"tox.ini": ""}).run("e", "-e", "py39,py38", *trail)
+    outcome.assert_failed()
+    msg = "ROOT: HandledError| You must specify a command as positional arguments, use -- <command>\n"
+    outcome.assert_out_err(msg, "")
+
+
+def test_exec_fail_multiple_target(tox_project: ToxProjectCreator) -> None:
+    outcome = tox_project({"tox.ini": ""}).run("e", "-e", "py39,py38", "--", "py")
+    outcome.assert_failed()
+    msg = "ROOT: HandledError| exactly one target environment allowed in exec mode but found py39, py38\n"
+    outcome.assert_out_err(msg, "")
+
+
+@pytest.mark.parametrize("exit_code", [1, 0])
+def test_exec(tox_project: ToxProjectCreator, exit_code: int) -> None:  # noqa: U100
+    prj = tox_project({"tox.ini": "[testenv]\npackage=skip"})
+    py_cmd = f"import sys; print(sys.version); raise SystemExit({exit_code})"
+    outcome = prj.run("e", "-e", "py", "--", "python", "-c", py_cmd)
+    if exit_code:
+        outcome.assert_failed()
+    else:
+        outcome.assert_success()
+    assert sys.version in outcome.out

whitelist.txt

@@ -20,7 +20,7 @@ canonicalize
 capfd
 caplog
 capsys
-cfg
+Cfg
 changelog
 chardet
 chdir
@@ -67,13 +67,14 @@ entrypoints
 envs
 epilog
 eq
-eval
+Eval
 exc
 exe
 executables
 expr
 extlinks
 extractall
+fallbacks
 favicon
 filelock
 fixup
@@ -147,6 +148,7 @@ platformdirs
 pluggy
 Popen
 pos
+posargs
 posix
 prepend
 prereleases