feat: support setting an empty session list

[henryiii]

Closes #465.

Setting an empty session list in the noxfile will default to listing the available sessions.

[FollowTheProcess]

@henryiii LGTM, just thinking maybe there should be a quick mention in the tutorial section of the docs? Probably fits best under the Selecting which sessions to run section. Otherwise looks great, thanks!

[cjolowicz]

See #465 (comment)

[cjolowicz]

Thanks for tackling this, this is looking great!

Here are a few minor things I noticed. I haven't had time to review the changed control flow yet.

[FollowTheProcess]

Looking good overall! My only (minor) nit is that if you set nox.options.sessions = [] and run bare nox you get the following:

However if you run nox -l you get the little selected message on the end:

I have two thoughts:

1. Ideally these two should be consistent with one another
2. I think all sessions shown when nox.options.sessions = [] should appear as "unselected"

However this could just be my OCD showing so I'm happy to be overruled if we're happy with this as is 🙂

[cjolowicz]

I feel the intent could be expressed a little more clearly here. How do you feel about the suggestion below?

I omitted the checks for keywords and pythons because these conditions would have led to bailing out earlier.

Suggested change

	if (
	not global_config.keywords
	and not global_config.pythons
	and not global_config.sessions
	and not global_config.list_sessions
	and global_config.sessions is not None
	):
	# List sessions if `nox.options.sessions` is an empty sequence.
	if (
	global_config.sessions is not None
	and not global_config.sessions
	and not global_config.list_sessions
	):

[henryiii]

I redid this, but I kept the keyword/python filtering, since nox -k keyword should select and run the tests with keyword, rather than forcing it to also be passed via -s, I think.

[cjolowicz]

See #523 (comment)

[cjolowicz]

I agree with @FollowTheProcess that we don't need to special-case the listing for the "no default sessions" case. To be precise, the sessions can be displayed with a minus because they are all deselected, and the explanatory sentence at the end can be kept. (Codewise, this would amount to dropping the ˋselectˋ parameter in ˋproduce_listingˋ.)

[cjolowicz]

Also I'm confused, why are there asterisks in the screenshot if all sessions are deselected?

[cjolowicz]

I realize now that you don't filter sessions by name when nox.options.sessions is an empty list. This also explains why nox --list displays all sessions as selected (with an asterisk) even though they're not.

Can we change the condition for this filter to check for None instead of falsiness?

You will need to check for a non-empty manifest after filtering by session name, like for the other filters. If the check fails, you can invoke produce_listing. This would replace the block at the end of the function.

I believe there are three good reasons for this change:

1. It would make the control flow easier to understand.
2. It's important that nox --list can be used to debug session selection.
3. Filtering by Python should not cause sessions to become selected. Currently, your PR changes this behavior (when the session list is empty).

As for selecting sessions by keyword even when nox.options.sessions is an empty list: This already works. The nox.options.sessions setting is ignored when -k is passed, see the function _sessions_and_keywords_merge_func in the _options module.

What do you think?

Update: My suggestion breaks some tests in test_tasks.py that initialize sessions to an empty tuple. The failing tests need to be updated by initializing sessions to None instead (which is the correct default value anyway).

[cjolowicz]

Should we use the logger here? It would make the message stand out from the session listing.

Suggested change

	print("No sessions selected. Please select a session with -s <session name>.\n")
	logger.warning(
	"No sessions selected. Please select a session with -s <session name>.\n"
	)

We'd need to adapt the new tests to use caplog.text instead of capsys.readouterr().out.

[henryiii]

Is it an error / warning though? The session listing is a print.

[henryiii]

As for selecting sessions by keyword even when nox.options.sessions is an empty list: This already works.

Ah, this was the piece I didn't know. I wanted to put the check here, but didn't realize it would not cause an issue with filtering. It's at all not obvious that this will be ignored from the logic in this function! Seems like it should have it in the if statement.

[henryiii]

(Haven't tested the recent comment by hand with the noxfile yet)

[cjolowicz]

Thanks so much @henryiii for all the work that went into this