feat: support for reuse_venv option

[samypr100]

Closes #488

This PR introduces a new option reuse_venv at the CLI and nox.options level as discussed in #488. It takes 4 possible values, namely no, yes, never, and always as discussed in the issue.
The code that evaluates if a venv should be reused has been switched to use this new option, and backwards compatiblity with reuse_existing_virtualenvs is kept using appropriate finalizer_func and merge_func on _options.py.

I've added tests to test new functionality as well do backwards compatibility checks and hopefully 🤞 updated the docs properly. I also added a new fixture generate_noxfile_options that helps with more dynamic configuration of resources/noxfile_options.py used in the tests to reduce boilerplate.

[johnthagen]

@theacodes We're excited to get to use this feature, was wondering if you were able to review or your thoughts? Thanks!

[johnthagen]

@FollowTheProcess Would you be willing to review this MR? Thanks.

[funkyfuture]

i only looked on the user docs and i'm wondering:

• could always and never be used for nox.options.reuse_venv?
• if so, do these values make any sense at that level / should they be disallowed to protect users from confusion?

thanks for the feature implementation!

[funkyfuture]

the prose about the feature and its usage is fine, but as a user i think the section would aso benefit from a summary such as #488 (comment) or a table.

[henryiii]

--reuse-venv is a bit longer then --reuse (and you always have to specify a value, too, so it's a little lengthy on the command line, but the current long option is --reuse-existing-virtualenvs. The option draws a parallel with reuse_venv: bool = ... in the sessions, so I would be okay with the longer from, but wouldn't object at all to the shorter --reuse either, especially since there's not a short option for it.
Anyone have thoughts? Otherwise, this looks good to me.

[cjolowicz]

This comment doesn't relate to the code below

[samypr100]

I tried to clarify this function with even more documentation here 715bc9a, let me know if it's better.

[cjolowicz]

This is super helpful

[cjolowicz]

I'd love to see this called out in the docs as well

[samypr100]

It should be in the docs, near the end of this statement in config.rst:

* ``nox.options.reuse_existing_virtualenvs`` is equivalent to specifying :ref:--reuse-existing-virtualenvs . You can force this off by specifying ``--no-reuse-existing-virtualenvs`` during invocation. Alias of ``nox.options.reuse_venv``.

[cjolowicz]

The docs should state explicitly that --reuse-venv=yes is equivalent to --reuse-existing-virtualenvs.

I'm happy for this to land as-is though. We probably want to deprecate the longer version anyway.

(OT: It might also be a nice improvement to allow specifying --reuse-venv without a value, defaulting to yes.)

[samypr100]

Agree, I didn't explicitly deprecate it on this PR but it can be done so in a follow up one. When that happens I think it makes sense to augment --reuse-venv (or add --reuse/--no-reuse like @henryiii prefers) to default to yes when specified. Note -r is a valid shorthand for --reuse-venv=yes since it's a shorcut to --reuse-existing-virtualenvs .

[samypr100]

The docs should state explicitly that --reuse-venv=yes is equivalent to --reuse-existing-virtualenvs.

Done in fdf876c and 88d11b7

[cjolowicz]

Personally I like the more explicit --reuse-venv. There are other things one might "reuse" (wheels?). AFAIU -r also becomes a short option for --reuse-venv=yes since it's equivalent.