[Distutils] PEP for specifying build dependencies

[Nathaniel Smith]

On Thu, May 12, 2016 at 12:01 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On 12 May 2016 at 11:33, Donald Stufft <donald at stufft.io> wrote:
>> I don't really think of it as package vs tool, I think of it as an implicit
>> <standard stuff> vs an explicit <third party stuff>. I think it makes the
>> file
>> uglier to have the <standard stuff> explicit, particularly since I think the
>> example should really be something like:
>>
>>     [standard.package.build-system]
>>     requires = ["setuptools", "wheel"]
>>
>>     [tool.flake8]
>>     ...
>>
>> Because the value of the [package] namespace isn't that it separates us from
>> the [tool] namespace (we could get that easily without it), but that it
>> separates us from *other*, non packaging related but "standard" stuff that
>> might be added in the future.
>
> In that case though:
>
> 1. semantics-version isn't about the package, it's about the
> pyproject.toml file itself.
> 2. build-system feels like it could readily be top level as well,
> regardless of what other sections we added later
>
> That would make the example in the PEP
> ===============
> semantics-version = 1  # Optional; defaults to 1.
>
> [build-system]
> requires = ["setuptools", "wheel"]  # PEP 508 specifications.
> ===============
>
> So I'm not clear on what the [package] namespace is buying us over
> just having [build-system] as a top level namespace (it would be
> different with a section name of "build" - for that, [package.build]
> reads nicely, and you can mostly ignore that it creates a nested
> namespace TOML. As noted elsewhere, I don't like "build" though -
> we're not configuring the build, we're specifying what's needed to run
> the build system in the first place).

When we were spitballing the draft, I think where [package] originally
came from was the idea that having semantics-version at the top level
is not actually useful -- most tools will only care about the
semantics of the [tool.whatever] table and the only PEP change that
would affect them is if we for some reason redefined the [tool] table
itself. Which we aren't going to do. But if semantics-version is
top-level, then presumably everyone has to check for it and error out
if it changes. So bumping semantics-version would cause all these
tools to error out, even though the part of the file that they
actually care about didn't change, which would mean in practice we
would just never actually bump the semantics-version because the flag
day would be too painful. Introducing a [package] level and pushing
semantics-version down inside [package] insulates from that.

...Given how complicated this is ending up being, I'm sorta inclined
to just drop semantics-version. It's only in there as a "hey why not
it doesn't hurt" thing. I can't imagine any situation in which we'd
actually bump the semantics version. If we need to make some
incompatible change we'll actually do it by adding a [build-system-2]
or something, and specify that [build-system] and [build-system-2] are
both allowed in the same file, and if both are present then new tools
should ignore [build-system] -- way smoother and backwards-compatible.

-n

-- 
Nathaniel J. Smith -- https://vorpus.org