Pull out high-level interfaces as an extended example

[takluyver]

An attempt to tackle #82, by putting all the code that tries to manage environments & installation into a separate buildtool_demo package, which does not get installed.

This will break things for anyone who was relying on the high-level functionality being in pep517, but I don't see any way to clean it up without doing that.

The functions for loading & checking the build-system info are retained as part of the real package, in pep517.pyproject.

[pradyunsg]

Suggestion: move it into examples/*, to clearly denote that it's an example and make room for us to add additional things/examples/demos if we want to in the future.

[takluyver]

OK, I've moved it into an examples/ folder; I agree that's neater. After some fiddling with CI, the tests embedded in that example are working again.

[takluyver]

Thanks @pradyunsg :-)

[pradyunsg]

How do we plan to manage the rollout of this change? There's probably a fair number of folks using this as a CLI tool.

[FFY00]

I'd probably wait until a new python-build release/python-build gets into PyPA, so that we can recommend that as an alternative.

[pradyunsg]

@FFY00 any ETA on that? anything to help with that?

[FFY00]

I need to fix some simple issues and probably improve the test suite a bit. I don't think it should take too long.

[pganssle]

Am I correct in understanding that this removes pep517.build? Was there ever a deprecation warning on this?

I guess I should have taken more seriously the warnings that it wasn't necessarily ready for production use, but given that this was the only PEP 517 build front-end for several years, I would kind of expect it to keep working at least for a while. I'll now have to run around and pin the versions on a bunch of my projects now.

If the justification is "we'll get a release of python-build soon, and we'll release this after that", that... doesn't seem like a long enough overlap.

[pganssle]

I should note that pep517.build is included in this guide to automatic publishing with Github Actions on packaging.python.org.

There's a good chance that it's pretty widely used.

[gaborbernat]

IMHO this should be done at shortest 6 months post python-build release to stop hundreds of ci failing all of sudden, and emmit a warning in the meantime about moving to python build. Definitely way to early to proceed with this. I'm strong -1 on this. Especially considering python-build is not yet even under pypa.

[webknjaz]

Also, @jaraco's skeleton relies on this CLI IIRC + I've seen it used in many other places. I use it in own projects and I guess since I've put this command into the guide that doesn't help. So I second the call to have a proper depreciation period + have some effort to clean up the widely used recommendations from tutorials and other examples. While it is not a big deal for me to pin the version, it'd be challenging for folks who are less familiar with packaging.

[Julian]

(Another +1 for "this will break CI on every repo I own", so definitely a slowerish release would be super appreciated here too).

[takluyver]

If I hold off releasing this change, will everyone stop filing issues about all the shortcomings of pep517.build? That's what led to this PR - I wrote the simplest possible PEP 517 frontend as a proof of concept and a starting point for serious frontends, and I failed to make it clear that that's what it was, so everyone's treating this quick sketch like it's meant to be the gold standard.

E.g. a proper build frontend would set up an isolated build environment (using something like venv), and let the user control how build dependencies were satisfied (e.g. get packages from this private index, or ignore the build requirements from the package and install these things instead). It would provide a way to pass config settings to the backend, probably options to control its output. Maybe optimisations for building multiple packages together. pep517.build does none of these things!

[gaborbernat]

@takluyver I think would be better to make a release that starts emiting that warning instead of just holding off with the release. So users can know they need to migrate in the next (6) months? If you do the release in two months it will still be an abrupt removal without some warning emited beforehand...

[takluyver]

Maybe we should hold off on even the warning until python-build is ready? I'm not sure a warning is much use if it can't suggest what to do instead.

Maybe once we can point people to python-build, it won't even be necessary to remove this. To be honest, I hadn't realised just how many people were relying on it. I don't want to break everybody's workflow, I just want to somehow make it clear that the pep517 package is primarily meant as a component for building PEP 517 frontends (like pip), not a frontend in itself.

[gaborbernat]

Maybe we should hold off on even the warning until python-build is ready?

I think it's ready. The latest release 0.0.4 should be good as first release. We don't have to move the project under PyPa to recommend it IMHO (but eventually will move under PyPa... but that's not end user facing change).

[webknjaz]

@takluyver that's a good option too. I think the major reason pep517.build got popular is mainly because pip only has pip wheel but there's no command for producing source dists. I wanted to use pip for this but couldn't and didn't want to resort to calling setuptools directly.

I didn't realize you were annoyed by pep517.build bug reports (I don't think I posted any but still...). May I suggest that as a part of this effort, we could configure a custom issue template chooser? https://docs.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser

There's an example config @ https://github.com/pypa/pip/blob/master/.github/ISSUE_TEMPLATE/config.yml and the preview is here https://github.com/pypa/pip/issues/new/choose.

The idea is that we could add an item that has an external link to python-build instead of an issue creation button. This way, you could redirect some of this traffic to the right place. Plus you can add some text description explaining that folks shouldn't create issues but rather switch the tool...

[takluyver]

Aha, I hadn't seen the python-build release yet. Thanks @FFY00!

So, how does this plan look:

• [ ] Point to python-build in the README & possibly issue templates (thanks @webknjaz )
• [x] Make a new branch from before this PR was merged (inc-pep517.build)
• [ ] Add a deprecationg warning when pep517.build is used
• [ ] Release a version with the warning - possibly after a bit of a wait, to give people a chance to start moving to python-build and flush out any bugs there.

[takluyver]

I've made a branch inc-pep517.build. I can't spend much time on this right now, but PRs are welcome for warnings & links in the documentation. Other PyPA people with access should feel free to merge stuff if they're confident in it - I don't want to be the bottleneck.

[pradyunsg]

Thanks @takluyver! I was reading this and was gonna propose making a branch for the new stuff and I'm glad that you did that already. 🙃

The only thing I'd say is we should have a deprecation warning for all of the pep517 CLI stuff, since all of it is going to go away. Off the top if my head, that means also including a warning on pep517.check.

[pradyunsg]

91 exists as the tracking issue and the place for further discussion. :)