Report an empty TOML command value as a handled error (#4041)

`install_command = []` in TOML raises `AttributeError: 'NoneType' object
has no attribute 'args'` with a traceback and exit code 2.
`list_dependencies_command = []` does the same. The ini spelling
`install_command=` reports `unable to determine pip install command:
attempting to parse '' into a command failed` and exits 1.

## The cause

`Convert.to_command` is declared `Command | None`, and the two loaders
disagree on what `None` means. `StrConvert.to_command("")` raises
`ValueError`; `TomlLoader.to_command([])` returns `None`, which is what
lets #3388 drop empty entries inside `commands`. For a scalar
`of_type=Command` that `None` is cast straight through to the caller,
which then dereferences it.

## The fix

`to_command` now returns a `Command` or raises, in every loader. The
TOML rule that an empty entry inside a list of commands is dropped moves
into `TomlLoader.to_list`, which is where `StrConvert.to_list` already
drops empty tokens. `convert.py` loses its `Command`-shaped branch in
the shared list path, so the format-specific rule no longer leaks into
the format-agnostic layer.

Making the abstract return type `Command` also surfaced that
`StrConvert.to_command` never returned `None` in the first place - `ty`
rejected the override until the annotation was corrected.

Both formats now stop before the dereference:

```
$ printf '[env.py]\ninstall_command = []\n' > tox.toml && tox r -e py
py: failed to load py.install_command: attempting to parse [] into a command failed
```

Drive-by: `TomlLoader.to_set` was a byte-for-byte copy of `to_list` and
now delegates to it.

## Verification

`test_toml_loader_command_empty_nok` covers the scalar rejection and
`test_toml_loader_command_list_drops_empty` pins the #3388 behaviour;
removing either half of the change fails the matching test.
`test_pip_toml_empty_command_error` is parametrised over
`install_command` and `list_dependencies_command`, the two scalar
`Command` settings.

Full suite passes, as do `tox -e type` (ty, mypy, pyrefly) and `tox -e
fix`.

- [x] ran the linter to address style issues (`tox -e fix`)
- [x] wrote descriptive pull request text
- [x] ensured there are test(s) validating the fix
- [x] added news fragment in `docs/changelog` folder
- [ ] updated/extended the documentation

Co-authored-by: Dylan Pulver <dylanpulver@users.noreply.github.com>

Author: dylanpulver

docs/changelog/4041.bugfix.rst

@@ -0,0 +1,2 @@
+Report an empty ``install_command`` or ``list_dependencies_command`` in a TOML configuration as a handled error instead
+of an unhandled traceback - by :user:`dylanpulver`

src/tox/config/loader/convert.py

@@ -63,8 +63,6 @@ def _to_typing(self, raw: T, of_type: type[V] | UnionType, factory: Factory[V])
         if origin in {list, list}:
             entry_type = type_args[0]
             result = [self.to(i, entry_type, factory) for i in self.to_list(raw, entry_type)]
-            if isclass(entry_type) and issubclass(entry_type, Command):
-                result = [i for i in result if i is not None]
         elif origin in {set, set}:
             entry_type = type_args[0]
             result = {self.to(i, entry_type, factory) for i in self.to_set(raw, entry_type)}
@@ -180,7 +178,7 @@ def to_path(value: T) -> Path:
 
     @staticmethod
     @abstractmethod
-    def to_command(value: T) -> Command | None:
+    def to_command(value: T) -> Command:
         """Convert to a command to execute.
 
         :param value: the value to convert

src/tox/config/loader/memory.py

@@ -53,7 +53,7 @@ def to_path(value: Any) -> Path:
         return Path(value)
 
     @staticmethod
-    def to_command(value: Any) -> Command | None:
+    def to_command(value: Any) -> Command:
         if isinstance(value, Command):
             return value
         if isinstance(value, str):

src/tox/config/loader/str_convert.py

@@ -74,7 +74,7 @@ def _win32_process_path_backslash(value: str, escape: str, special_chars: str) -
         return "".join(result)
 
     @staticmethod
-    def to_command(value: str) -> Command | None:
+    def to_command(value: str) -> Command:
         """At this point, ``value`` has already been substituted out, and all punctuation / escapes are final.
 
         Value will typically be stripped of whitespace when coming from an ini file.

src/tox/config/loader/toml/__init__.py

@@ -105,13 +105,15 @@ def to_bool(value: TomlTypes) -> bool:
 
     @staticmethod
     def to_list(value: TomlTypes, of_type: type[_T]) -> Iterator[_T]:
-        result = validate(value, cast("type[list[Any]]", GenericAlias(list, (of_type,))))
-        return iter(cast("list[_T]", result))
+        result = cast("list[_T]", validate(value, cast("type[list[Any]]", GenericAlias(list, (of_type,)))))
+        if inspect.isclass(of_type) and issubclass(of_type, Command):
+            # a generated command list leaves gaps rather than compacting itself, so drop them here (see #3388)
+            return iter([i for i in result if i])
+        return iter(result)
 
     @staticmethod
     def to_set(value: TomlTypes, of_type: type[_T]) -> Iterator[_T]:
-        result = validate(value, cast("type[list[Any]]", GenericAlias(list, (of_type,))))
-        return iter(cast("list[_T]", result))
+        return TomlLoader.to_list(value, of_type)
 
     @staticmethod
     def to_dict(value: TomlTypes, of_type: tuple[type[_T], type[_V]]) -> Iterator[tuple[_T, _V]]:
@@ -123,10 +125,11 @@ def to_path(value: TomlTypes) -> Path:
         return Path(TomlLoader.to_str(value))
 
     @staticmethod
-    def to_command(value: TomlTypes) -> Command | None:
-        if value:
-            return Command(args=cast("list[str]", value))  # validated during load in _ensure_type_correct
-        return None
+    def to_command(value: TomlTypes) -> Command:
+        if not value:
+            msg = f"attempting to parse {value!r} into a command failed"
+            raise ValueError(msg)
+        return Command(args=cast("list[str]", value))  # validated during load in _ensure_type_correct
 
     @staticmethod
     def to_env_list(value: TomlTypes) -> EnvList:

tests/config/loader/test_toml_loader.py

@@ -122,6 +122,16 @@ def test_toml_loader_command_nok() -> None:
         perform_load([["a", 1]], list[Command])
 
 
+def test_toml_loader_command_list_drops_empty() -> None:
+    commands = perform_load([[], ["c"]], list[Command])
+    assert [i.args for i in commands] == [["c"]]
+
+
+def test_toml_loader_command_empty_nok() -> None:
+    with pytest.raises(HandledError, match=_PREFIX + r"attempting to parse \[\] into a command failed"):
+        perform_load([], Command)
+
+
 def test_toml_loader_env_list_ok() -> None:
     res = perform_load(["a", "b"], EnvList)
     assert isinstance(res, EnvList)

tests/tox_env/python/pip/test_pip_install.py

@@ -8,9 +8,11 @@
 import pytest
 from packaging.requirements import Requirement
 
+from tox.report import HandledError
 from tox.tox_env.errors import Fail
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
     from pathlib import Path
 
     from tox.pytest import CaptureFixture, SubRequest, ToxProject, ToxProjectCreator
@@ -50,6 +52,25 @@ def test_pip_install_empty_command_error(tox_project: ToxProjectCreator) -> None
         pip.install([Requirement("name")], "section", "type")
 
 
+@pytest.mark.parametrize(
+    ("key", "use"),
+    [
+        pytest.param(
+            "install_command",
+            lambda pip: pip.install([Requirement("name")], "section", "type"),
+            id="install_command",
+        ),
+        pytest.param("list_dependencies_command", lambda pip: pip.installed(), id="list_dependencies_command"),
+    ],
+)
+def test_pip_toml_empty_command_error(tox_project: ToxProjectCreator, key: str, use: Callable[[Any], object]) -> None:
+    proj = tox_project({"tox.toml": f"[env.py]\n{key} = []"})
+    pip = proj.run("l").state.envs["py"].installer
+
+    with pytest.raises(HandledError, match=rf"failed to load py\.{key}: attempting to parse \[\] into a command"):
+        use(pip)
+
+
 def test_pip_install_flags_only_error(tox_project: ToxProjectCreator) -> None:
     proj = tox_project({"tox.ini": "[testenv:py]\ndeps=-i a"})
     result = proj.run("r")