diff --git a/src/tox/session/env_select.py b/src/tox/session/env_select.py index 8051f30bc..6a09879af 100644 --- a/src/tox/session/env_select.py +++ b/src/tox/session/env_select.py @@ -27,7 +27,22 @@ class CliEnv: # noqa: PLW1641 - """CLI tox env selection.""" + """A `CliEnv` is the user's selection of tox test environments, usually supplied via the ``-e`` command-line + option. It may be treated as a sequence if it's not a "default" or "all" selection. + + It is in one of three forms: + + - A list of specific environments, instantiated with a string that is a comma-separated list of the environment + names. As a sequence this will be a sequence of those names. + + - "ALL" which is all environments defined by the tox configuration. This is instantiated with ``ALL`` either + alone or as any element of a comma-separated list; any other environment names are ignored. `is_all()` will be + true and as a sequence it will be empty. This prints in string representation as ``ALL``. + + - The default environments as chosen by tox configuration. This is instantiated with `None` as the parameter, + `is_default_list()` will be true, and as a sequence this will be empty. This prints in string representation + as ````. + """ def __init__(self, value: None | list[str] | str = None) -> None: if isinstance(value, str): @@ -39,6 +54,7 @@ def __iter__(self) -> Iterator[str]: yield from self._names def __bool__(self) -> bool: + """A `CliEnv` is `True` if it's not the default set of environments.""" return bool(self._names) def __str__(self) -> str: diff --git a/tests/session/test_env_select.py b/tests/session/test_env_select.py index 6b3d744fe..102c22ce0 100644 --- a/tests/session/test_env_select.py +++ b/tests/session/test_env_select.py @@ -36,6 +36,8 @@ def test_clienv(user_input: str, env_names: tuple[str], is_all: bool, is_default: bool) -> None: ce = CliEnv(user_input) assert (ce.is_all, ce.is_default_list, tuple(ce)) == (is_all, is_default, tuple(env_names)) + assert ce is not ce.is_default_list + assert CliEnv(user_input) == ce @pytest.mark.parametrize(