Skip to content

✨ feat(toml): add generative env_list via product dict#3797

Merged
gaborbernat merged 1 commit intotox-dev:mainfrom
gaborbernat:feat/3797-toml-product-env-list
Feb 20, 2026
Merged

✨ feat(toml): add generative env_list via product dict#3797
gaborbernat merged 1 commit intotox-dev:mainfrom
gaborbernat:feat/3797-toml-product-env-list

Conversation

@gaborbernat
Copy link
Copy Markdown
Member

TOML users have had to manually enumerate every environment in env_list when they need a test matrix, while INI users could write concise expressions like py3{12,13}-django{42,50}. This gap made TOML configuration verbose and error-prone for projects with large matrices, and was one of the most visible feature disparities between the two formats.

✨ This introduces a TOML-native product dict syntax that leverages TOML's type system instead of mimicking INI's string-based brace expansion. Factor groups are expressed as arrays of strings or range dicts, and tox computes the Cartesian product joining combinations with -. Range dicts ({ prefix = "py3", start = 12, stop = 14 }) generate sequential factors, with open-ended bounds matching INI's py3{10-} behavior. An exclude key allows skipping specific combinations — a capability not available in INI at all.

env_list = [
    "lint",
    { product = [
        { prefix = "py3", start = 12, stop = 14 },
        ["django42", "django50"],
    ] },
]

Documentation has been updated across all four Diataxis dimensions (tutorial, how-to, reference, explanation) with TOML shown first in all tab pairs. The "TOML feature gaps" section has been renamed to "Format comparison" since generative env_list was the last major functional gap — only generative section names remain INI-exclusive. The JSON schema has been extended to validate product dicts with their factor groups and optional exclude arrays.

TOML users had to manually enumerate environment matrices while INI
had concise curly-brace expansion. This adds a TOML-native syntax
using arrays and dicts that leverages TOML's type system and brings
a capability INI lacks: exclusions.

Product dicts compute the cartesian product of factor groups joined
with dashes. Range dicts generate sequential factor lists with
open-ended bounds matching INI's behavior. Documentation updated
across all four Diataxis dimensions with TOML shown first in all
tab pairs.
@gaborbernat gaborbernat force-pushed the feat/3797-toml-product-env-list branch from 457f562 to 36da817 Compare February 20, 2026 15:00
@gaborbernat gaborbernat enabled auto-merge (squash) February 20, 2026 15:04
@gaborbernat gaborbernat merged commit b11c645 into tox-dev:main Feb 20, 2026
28 checks passed
@gaborbernat gaborbernat deleted the feat/3797-toml-product-env-list branch February 20, 2026 15:20
@nedbat
Copy link
Copy Markdown
Contributor

nedbat commented Feb 25, 2026

The tox.ini syntax was compact and understandable. Why not allow that same syntax in .toml? This dictionary seems cumbersome.

@gaborbernat
Copy link
Copy Markdown
Member Author

The tox.ini syntax was compact and understandable. Why not allow that same syntax in .toml? This dictionary seems cumbersome.

I think this is one of those cases where it was understandable for people who knew. I was constantly reminded when talking to people unfamiliar with the project that they have no idea what's happening. Furthermore learning from the mistakes of various string markers being very difficult to compose I purposefully wanted to not use any string level information and have this schema be fully type safe via native toml. See how now we have a concrete IDE automatically validated schema generated and published.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants