Amend PEP 518 to explicitly specify tool behaviour when pyproject.toml with missing/partial build-tools definition

Packaging
#1

Spun up from When you kick the packaging hornet's nest on Twitter, the hornets seem to want an opinionated, KISS solution.

Currently the PEP specifies

It is up to the tool to decide how to handle [a pyproject.toml file without the build-system table]. Potential options are:

  1. Act as if the pyproject.toml file does not exist.
  2. Assume the table exists with the default values specified above.

IMO this has potential for unnecessarily confusion. In practice most would simply follow pip’s behaviour (1. if the table is missing entirely; 2. if the table exists but misses values). Why not specify that?

#2

IMO, largely because we don’t (certainly didn’t at the time) know for certain whether pip’s behaviour is correct, and want to leave the option open for experimentation. Also, it’s much easier just to change pip if it turns out the current behaviour is problematic than it would be to change PEP 518.

Having said all that, I won’t object if someone wants to make the PEP require the same behaviour as pip.

#3

Because you haven’t said what that behaviour is in this thread (for instance I don’t know what pip does in either of these cases). :wink:

#4

IIRC pip’s behaviour is to trigger build isolation if pyproject.toml exists, and fill in missing fields with default values (i.e. option 2. in PEP 518).

Ref: https://github.com/pypa/pip/issues/5416#issuecomment-406788181

#5

If this proposal is to go anywhere, someone needs to confirm that for certain. And the PEP needs to explain the required behaviour without reference to pip (specifically, the justification for the mandated behaviour needs to stand on its own, and not be “because that’s what pip does”).

Also, be careful here - build isolation is not a PEP 518 concept. The idea of an isolated build environment is from PEP 517, and pip’s triggering it based on the existence of pyproject.toml choice is a tool-specific choice not covered by either of the PEPs1 (regardless of whether this clarification is made). The real question here is whether tools are required to treat projects as having opted in to PEP 518 if a pyproject.toml exists - even if that’s only for an unrelated reason such as black configuration.

1 Build isolation in PEP 517 is recommended, but optional.

2 Likes
#6

And it is that switch to isolated builds that caused issues for black and seems to be a reason for other tools to hold off on pyproject.toml adoption (the other reason cited being the lack of a stdlib toml parser).

See:

It’s unfortunate that the PEP did not nail this down more clearly.

#7

I’ve been avoiding the packaging threads mostly, but should’ve realised this was already being discussed in detail. Please ignore my remarks.

#8

The current pip behaviour is (from my experiements):

  • If pyproject.toml is not present, use legacy behaviour (build with Setuptools).
  • If pyproject.toml is present but missing [build-system], use PEP 517 and defaults to Setuptools as backend.
  • If pyproject.toml is present with [build-system] but lacks requires, error out.
  • If pyproject.toml is present with build-system.requires, use PEP 517 and defaults to Setuptools as backend.
  • If pyproject.toml is present with all mandatory fields, use PEP 517.

@pradyunsg could you help confirm this?

1 Like
#9

I don’t have the time to check the code, but that sounds correct to me, FWIW.

#10

Same position as @pf_moore – I think this is right but can’t check to verify right now.

#11

Do note that the PEP is marked as experimental so technically no one has to follow the PEP. :wink:

Since no one is worried enough to verify then I think it’s reasonable to assume that this is how pip operates.

Proposal

Tools should not require the existence of the [build-system] table. A pyproject.toml file may be used to store configuration details other than build-related data and thus lack a [build-system] table legitimately. If the file exists but is lacking the [build-system] table then the default values as specified above should be used. If the table is specified but is missing required fields then the tool should consider it an error.

What do people think of that as the change to that section of the PEP?

3 Likes
#12

Brett’s suggestion looks good to me.

#13

The pip behavior described also matches the docs.

2 Likes
#14

And the code matches – now that I finally got time to validate this. :slight_smile:

2 Likes
#15

If people don’t end up disagreeing I will plan on making this change later this week or next week.

/cc @njs @dstufft

1 Like
#16

Looks good to me.

#17

Changed in https://github.com/python/peps/commit/1542941b34d61f99d48b70e7e80c47737e3be078.

Thanks for the help, everyone!

3 Likes