How do conditional commands in TOML syntax work?

[luziferius]

I want to modernise my current tox.ini and port/move it to native TOML inside pyproject.toml, but I can't figure out how to add platform-specific commands in the new syntax.

I'm running the latest version 4.49.1, and looking at the documentation, there is https://tox.wiki/en/4.49.1/reference/config.html#conditional-value-reference
under Check for platform factors:

[env_run_base]
commands = [
    { replace = "if", condition = "factor.linux", then = [["pytest", "--numprocesses=auto"]] },
    { replace = "if", condition = "not factor.linux", then = [["pytest"]] },
]

Because I wasn't able to make it work, I tried and copy&pasted the above commands list verbatim into an environment (named pkg), and running tox config -e pkg gives this error

[…]
commands = # Exception: HandledError("failed to load pkg.commands: ['pytest', '--numprocesses=auto'] is not of type 'str'")
[…]

So it doesn't expect a list of commands, but a single command? Modifying the sample above to instead read

commands = [
    { replace = "if", condition = "factor.linux", then = ["pytest", "--numprocesses=auto"] },
    { replace = "if", condition = "not factor.linux", then = ["pytest"] },
]

instead gives this error message:

commands = # Exception: HandledError("failed to load pkg.commands: '' is not list")

Now it got an empty string, but expects a list?!

What's going on here?

[gaborbernat]

Hi @luziferius, great question!

The missing piece is extend = true on the conditional replacement. Without it, tox appends the then value as a single element into the commands list, which creates an extra level of nesting that fails validation. With extend = true, the contents are unpacked into the parent list instead.

For your specific use case (conditionally adding --numprocesses=auto), the simplest approach is to keep a single command and conditionally inject the extra argument:

commands = [["pytest", { replace = "if", condition = "factor.linux", then = ["--numprocesses=auto"], extend = true }]]

On linux this runs pytest --numprocesses=auto, on other platforms just pytest.

If you need entirely different commands per platform, you can also do:

commands = [
    { replace = "if", condition = "factor.linux", then = [["pytest", "--numprocesses=auto"]], extend = true },
    { replace = "if", condition = "not factor.linux", then = [["pytest"]], extend = true },
]

When the condition is false and no else is given, it defaults to an empty value, so the falsy branch simply contributes nothing to the list.

You can find more details and examples in the Conditional value reference section of the docs at https://tox.wiki/en/latest/.

Hope that helps!

[luziferius]

My use case is something else, but extend=true is the missing link and will solve this. Thanks!

What I quoted was straight up copied verbatim from the documentation. So a copy&paste from the current docs failed, so I was struggling.