Passing values through requires

[henryiii]

How would this feature be useful?

For some cases (notably, building a wheel), it's helpful to be able to pass values from a session into the sessions that are requiring it.

Describe the solution you'd like

I think we could add a new property, .required, that holds a dict with all the sessions that were listed in requires=[...], and holds the return values for all of them. I don't think we use the return value at all for now, so is this a good way to use the return value?

Describe alternatives you've considered

We could (officially) support session.data, and let anyone write to it / read from it. That might be more explicit. That would leave return values available for future use. I think the main use for this is a "build" step, so maybe we could just work on adding official "build" support and punt on this for now. Currently, users have to use a global to pass data around.

Anything else?

Proposed example:

@nox.session
def build(session: nox.Session) -> str:
    """
    Make an SDist and a wheel.
    """
    extra = ["--installer=uv"] if session.venv_backend == "uv" else []
    session.install("build")
    tmpdir = session.create_tmp()
    session.run("python", "-m", "build", "--outdir", tmpdir, *extra)
    (wheel_path,) = Path(tmpdir).glob("*.whl")
    (sdist_path,) = Path(tmpdir).glob("*.tar.gz")
    Path("dist").mkdir(exist_ok=True)
    wheel_path.rename(f"dist/{wheel_path.name}")
    sdist_path.rename(f"dist/{sdist_path.name}")

    return wheel_path.name


@nox.session(requires=["build"])
def tests(session: nox.Session) -> None:
    """
    Run the tests.
    """
    wheel = session.required["build"]
    session.install(f"./dist/{wheel}[test]")
    session.run("pytest", *session.posargs)