Improved factor selection to allow multiple uses of `-f` for "OR" and to allow hyphenated factors #2786

sirosen · 2022-12-28T23:44:34Z

Summary

To enable better factor selection, this PR applies two changes. (resolves #2766)

-f can now be passed multiple times. Envs matching any -f usage are selected (OR) on top of the existing behavior that envs must match all factors in a given usage (AND).
-f will now split factors with hyphens.

(1) is the key functional change. (2) is not strictly necessary, but makes usage conform a little better to user expectations (or at least the expectations of one user! 👋 😉 ).

Example Usage

Consider an env list as follows:

envlist = py3{10,9}-django2{0,1}{,-cov}

Prior to this change, the following usage was valid: tox l -f py39 django20 and would select py39-django20 py39-django20-cov.
After this change, the same selection can be expressed with tox l -f py39-django20. Furthermore, the following selection which was previously not possible can be expressed:

$ tox l -f py39-django20 -f django21-cov
py310-django21-cov
py39-django20
py39-django20-cov
py39-django21-cov

The groups of selections are combined with OR semantics, but the individual selections are combined with AND.

Implementation Notes

I separated these two features into two commits, anticipating that (2) might be contentious. I would like to keep it as I don't think it adds much complexity, but I'm ready and willing to pull it out if necessary.

The parsing/interpretation of factors is now separated out into a dedicated helper method, which I note most other CLI args do not have. It looks like the CLI code avoids breaking things apart into too many small functions, but I thought this case benefits enough in terms of readability to be worth it. Again, I'm happy to change this in response to feedback.

The help message is rather long for this now, and I'm still not sure it's fully descriptive. Perhaps a future FAQ on how to use factors and labels would help.

Checklist

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

Previously, when `-f` was passed, it overwrote the last value. The result was that `-f foo -f bar` was equivalent to only passing `-f bar`. Under the new behavior, `-f foo -f bar` combines `foo` and `bar` as selection criteria, using OR-semantics. Envs matching `foo OR bar` will be selected. The existing multi-value argument behavior for `-f` is retained, in which `-f foo bar` means `foo AND bar`. The behaviors can be combined to express a variety of environment selections which were not previously possible in a single invocation. e.g. `-f foo bar -f baz` meaning `(foo AND bar) OR baz`. No existing tests fail, and the new behavior is checked by a new test. The help message for `-f` is updated.

The existing parsing of factors allows multiple factors to be selected by passing them as multiple arguments to the `-f` flag. For example, `-f foo bar` to pass both `foo` and `bar` as factors. This can now be passed equivalently using `-f foo-bar`. The meaning of this usage is identical to `-f foo bar`. A new test checks the behavior, and very closely mirrors the existing `-f` selection test so that their outputs are exactly equivalent.

These three tests are nearly identical in structure, and rely upon the same project configuration. Convert from three distinct test cases to a single parametrized test. Also apply pre-commit, which does some mild reformatting.

gaborbernat

Also, fix the type checker issues.

docs/changelog/2766.feature.rst

tests/session/test_env_select.py

src/tox/session/env_select.py

- use tuple instead of list for immutable data - use `continue` and `break` to skip unnecessary loop iterations

tests/session/test_env_select.py

src/tox/session/env_select.py

- convert args from list[str] to tuple[str, ...] - reformat str concat into a `.format()` usage

This check cannot be reached because it relies on an impossible combination of factors and labels.

sirosen · 2022-12-29T04:53:36Z

I think I've addressed the outstanding changes needed. If this is going to squash merge, I think it's ready. Otherwise, I'd like to rebase it to tidy the history a little bit.

This PR contains the following updates: | Package | Type | Update | Change | Pending | |---|---|---|---|---| | [tox](https://togithub.com/tox-dev/tox) ([changelog](https://tox.wiki/en/latest/changelog.html)) | dev | minor | `4.0.19` -> `4.1.0` | `4.2.8` (+11) | --- ### Release Notes <details> <summary>tox-dev/tox</summary> ### [`v4.1.0`](https://togithub.com/tox-dev/tox/releases/tag/4.1.0) [Compare Source](https://togithub.com/tox-dev/tox/compare/4.0.19...4.1.0) #### What's Changed - docs(config): Fix minor typo by [@rpatterson](https://togithub.com/rpatterson) in [tox-dev/tox#2785 - Update user_guide.rst by [@jamwil](https://togithub.com/jamwil) in [tox-dev/tox#2787 - Improved factor selection to allow multiple uses of `-f` for "OR" and to allow hyphenated factors by [@sirosen](https://togithub.com/sirosen) in [tox-dev/tox#2786 #### New Contributors - [@rpatterson](https://togithub.com/rpatterson) made their first contribution in [tox-dev/tox#2785 - [@jamwil](https://togithub.com/jamwil) made their first contribution in [tox-dev/tox#2787 - [@sirosen](https://togithub.com/sirosen) made their first contribution in [tox-dev/tox#2786 **Full Changelog**: tox-dev/tox@4.0.19...4.1.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box  Co-authored-by: descope[bot] <descope[bot]@users.noreply.github.com>

sirosen added 4 commits December 28, 2022 22:39

Make factor tests parametrized & apply pre-commit

08092bf

These three tests are nearly identical in structure, and rely upon the same project configuration. Convert from three distinct test cases to a single parametrized test. Also apply pre-commit, which does some mild reformatting.

Add changelog entry for tox-dev#2766

a8e9b15

sirosen requested a review from gaborbernat as a code owner December 28, 2022 23:44

psf-chronographer bot added the bot:chronographer:provided label Dec 28, 2022

gaborbernat requested changes Dec 29, 2022

View reviewed changes

docs/changelog/2766.feature.rst Outdated Show resolved Hide resolved

sirosen added 2 commits December 29, 2022 01:25

Fix missing annotation in tests

826e2a9

Fix changelog entry for tox-dev#2766

2be500b

sirosen force-pushed the improved-factor-selection branch from 1e75edd to 2be500b Compare December 29, 2022 01:26