Aliases for commands to run in an environment?

[wshanks]

A project I work with has a tox.ini with multiple environments defined that have (or could have) the same dependencies. For example, test, lint, and docs. Is there any way to define multiple commands that can be called separately on one environment? For example, run tests, run lint, or build docs. If not, I think that tox exec can be used to reuse an environment with different commands and that tox exec commands could be captured using another tool like just for convenience. I wanted to check though if something more built into tox already existed or was planned (hatch for example allows defining multiple commands like this).

[gaborbernat]

You can use lables https://tox.wiki/en/4.11.3/config.html#labels see https://tox.wiki/en/4.11.3/cli_interface.html#tox-run--m

[wshanks]

Thanks, but I don't think labels do what I want. My understanding is that labels allow you to run the default command of multiple environments with a single tox invocation. What I am looking for is a way to define multiple aliases that each map to a different command to run in a shared environment. (In hatch there is a feature like this called scripts). Here is a tox.ini that I work with as an example. Here is a section for easier reference:

[testenv:docs]
usedevelop = False
passenv =
  EXPERIMENTS_DEV_DOCS
  PROD_BUILD
  RELEASE_STRING
  VERSION_STRING
commands =
  sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html

[testenv:docs-parallel]
usedevelop = False
passenv =
  EXPERIMENTS_DEV_DOCS
  PROD_BUILD
  RELEASE_STRING
  VERSION_STRING
commands =
  sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html

Running tox -edocs run and tox -edocs-parallel run for example results in separate .tox/docs and .tox/docs-parallel environments when really they could use the same environment. One way I know to deal with this is to define wrappers using tox exec. So tox -edocs-parallel run could become a docs-parallel wrapper that calls tox -edocs exec -- sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html (not the best example because this one can also just be done with posargs as tox -edocs run -- -j auto but the docs could be built in the same environment that runs pylint also). I was wondering if there was something more built-in for this.

[gaborbernat]

Purposely we do not support a shared environment. This is something you could achieve with a plugin, but we do not want to tackle that problem within the core environment.

[wshanks]

Thanks! Using the phrase "shared environment" I was able to find more results than I found before trying variations of "alias" and "command". I found this project that had one proposed solution and links to where similar things had been asked before: https://github.com/masenf/tox-ignore-env-name-mismatch

[wshanks]

@gaborbernat I noticed that you said you did not agree with the ignore env name mismatch plugin here. I was wondering if you just meant that you do not agree with trying to share an environment in general of if you meant specifically that you did not like having tox ignore the env name and only consider the dependencies for determining environment reuse.

I tried implementing a shared environment in a different way and I was wondering if you thought this method was okay or if a different approach would be better. For my approach I added a config value for listing other commands to be run and a command line option for selecting to run those commands. When those are both used, the commands config value is overridden.

"""
tox plugin which allows adding entry called ``alternative_commands`` to a tox
environment configuration section with different commands to run instead of the
main ``commands`` entry. The plugin also adds an ``--alt`` command line option
for selecting the alternative command sets. To use the alternative commands,
one must specify the runner as ``alternative_commands``.

For example, one might have environment for running ``black --check`` but set
up some alternate commands to check the ``black`` help or version (this is a
trivial example; one could use ``posargs`` to set this up without a plugin). To
do this one would have an environment config entry like

    [testenv:black]
    runner = alternative_commands
    skip_install = true
    deps =
      black
    commands = black --check
    alternative_commands =
      help =
        black --help
      version =
        black --version
        python --version

Then instead of the usual invocation of

    tox run -eblack

one could use

    tox run -eblack --alt help

to print the black help text.
"""
from __future__ import annotations

from typing import TYPE_CHECKING, List

from tox.config.loader.api import Override
from tox.plugin import impl
from tox.tox_env.python.virtual_env.runner import VirtualEnvRunner

if TYPE_CHECKING:
    from tox.cli.parser import ToxParser
    from tox.tox_env.register import ToxEnvRegister


@impl
def tox_register_tox_env(register: ToxEnvRegister) -> None:
    register.add_run_env(AlternativeCommandsRunner)


class AlternativeCommands:
    def __init__(self, raw: str):
        self.raw = raw

    def __eq__(self, other):
        return self.raw == other.raw

    def __ne__(self, other):
        return not (self == other)

    @property
    def parsed(self) -> dict[str, list[str]]:
        """Parse the alternative_commands config entry

        We turn an entry like

            alternative_commands = 
              set1 =
                cmd1 arg1
                cmd2 arg2
              set2 =
                cmd3 arg3
                cmd4 arg4

        which gets rendered a newline separated string into a dictionary like

            {"set1": "cmd1 arg1\ncmd2 arg2", "set2": "cmd3 arg3\ncmd4 arg4"}

        We don't parse the commands because we pass them as a config override
        and the config loader wants to load the override as a single string,
        not as a parsed list of Command objects.
        """
        output = {}
        name = ""
        for line in self.raw.splitlines():
            first, sep, second = line.partition("=")
            if sep:
                name = first.strip()
                value = second.strip()
            else:
                value = first.strip()

            if not name:
                raise ValueError(f"Badly formed alternative_commands: {self.raw}")
            if value:
                output.setdefault(name, []).append(value)

        return {k: "\n".join(v) for k, v in output.items()}


@impl
def tox_add_option(parser: ToxParser):
    parser.add_argument("--alt", "--alt-command", default="", dest="alt_command")


class AlternativeCommandsRunner(VirtualEnvRunner):

    def register_config(self):
        self.conf.add_config(
            keys=["alternative_commands"],
            of_type=AlternativeCommands,
            default=AlternativeCommands(""),
            desc="Alternative command sets that can be selected from command line",
        )
        super().register_config()
        alt_cmd = self.options.alt_command
        if alt_cmd:
            alt_commands = self.conf["alternative_commands"].parsed
            if alt_cmd not in alt_commands:
                raise ValueError(
                    f"Alt command {alt_cmd} not found in alternative_commands {list(alt_commands)}"
                )
            self.conf.loaders[0].overrides["commands"] = Override("commands=" + alt_commands[alt_cmd])

    @staticmethod
    def id() -> str:
        return "alternative_commands"

[gaborbernat]

With something like that I'm happy 😀 that is aliases, no environment reuse across different environments.