feat: support PEP 723 with a toml load function

[henryiii]

This is the suggestion from #808. As detailed there, I think this is a flexible first step that will help noxfile authors support PEP 723 in scripts, and could have a followup later that provides a more integrated solution.

This also allows noxfile authors to finally integrate with pyproject.toml on all versions of Python, rather than requiring nox be installed on Python 3.11+, by ensuring that a toml library is always present. You might need to read the version, etc. from pyproject.toml in your noxfile, and now you can.

I made all the errors ValueError because that's what the PEP did in the example implementation. Happy to make them something else if there's something better.

[cjolowicz]

Should we fail the session instead of raising ValueError? Nox can be more opinionated about the error handling than say a library, and it would avoid the traceback.

[henryiii]

Hmm, we could, but most of the improperly configured calls seem to also raise ValueError, such as

nox/nox/sessions.py

Line 219 in 956f10c

raise ValueError("The environment does not have a bin directory.")

and

nox/nox/sessions.py

Lines 388 to 393 in 956f10c

	if not args:
	raise ValueError("At least one argument required to run().")
	if len(args) == 1 and isinstance(args[0], (list, tuple)):
	msg = "First argument to `session.run` is a list. Did you mean to use `session.run(*args)`?"
	raise ValueError(msg)

[henryiii]

Current name (from the issue) is nox.project.load_toml. nox.project is imported by default.

[cjolowicz]

Looks great!

Do we want to mark this as a provisional API in some way?

It feels like new territory. We may want to adapt to evolving packaging standards and move around or rename things without going through deprecation.

[henryiii]

Do we want to mark this as a provisional API in some way? ...

I think what we've added here is pretty conservative. nox.project is a place for project related tools. load_toml does exactly that, it loads toml and nothing more. (It does support PEP 723, but that's accepted so it isn't allowed to change significantly without a new PEP). We've left it up to the user to handle converting pyproject.toml's and script blocks into useable information.

If we add more things here, then possibly. If we have a session_from_script helper or something, that could be provisional. Or helpers for parametrizing over the Python versions allowed. Etc.

(But happy to call this provisional too if you prefer)