PEP 518: Add subsections to Specification section

[pradyunsg]

It is common to reference to different parts of the specification when
discussing the changes brought about by this PEP. This change makes it
easier to do so by introducing subsections to the main specification.

/cc @ncoghlan @dstufft @njs @brettcannon

[pradyunsg]

While we're here, I'd also point out that the PEP is not clear about the behavior when there's a pyproject.toml file in the project but it does not define the build-system.requires key. This ambiguity has caused some confusion and pip's behavior today is just weird in this situation today (see: pypa/pip#5416 (comment)).

Making the build-system table optional means that adding configuration to tools that use the tool table for configuration won't change the semantics of how the project is built. It adds a more explicit opt-in to the new behavior.

OTOH, making it mandatory makes pip's life easier since it will be able to simply trigger "new" behavior (read: build time isolation and future PEP 517 behavior) based on the presence of pyproject.toml; at the cost of making some existing published packages invalid (most notably pytest).

I'll be happy to add language to make the build-system table optional (or mandatory, if that's what we want) in this PR and update pip's implementation accordingly.

_{Edit: Reworded + Added paragraph on mandatory build-system}

---

Or does this need to go through distutils-sig?

[ncoghlan]

The original intent was that if pyproject.toml was present, but build-system.requires was missing, then that would be interpreted as no additional dependencies being needed.

PEP 517 was more explicit about falling back to setup.py regardless of whether or not the entire file was missing, or just the build-system.build-backend table entry.

Given that, I think it would be reasonable to clarify the spec to say that tools are free to interpret any missing build-system.requires as equivalent to ["setuptools", "wheel"].

[ncoghlan]

See https://www.python.org/dev/peps/pep-0440/#summary-of-changes-to-pep-440 for an example of a post-release clarification/amendment in one of the packaging PEPs.

[pradyunsg]

Sounds good to me. I'll make a new PR for it. I also think adding language to allow tools to default to their existing semantics if pyproject.toml is omitted would be nice (since pip does that).

[pfmoore]

One point (that may not be relevant to the PEP but which does affect pip) is whether a missing build-system.requires should be treated the same as a pyproject.toml with build-system.requires = ["setuptools", "wheel"] or whether it should be treated the same as a missing pyproject.toml.

In pip, the distinction is whether we use build isolation or not - the legacy (no pyproject.toml) case does not use build isolation, whereas if there is a pyproject.toml, we use the new code path which does invoke build isolation.

As I say, the subtlety of that distinction may only be relevant to pip, although the PEP's precise wording may inform the debate we have over there :-)