Setuptools: Document setuptools.build_meta

[pganssle]

There is currently no documentation for setuptools.build_meta!

We need to cover:

1. What it is - see this three part series for more background on python packaging and PEP 517
2. How to use it - you need to add a pyproject.toml to your source root with the following configuration (implementer - please confirm the right versions to pin):

[build-system]
requires = ["setuptools >= 40.6.0", "wheel"]
build-backend = "setuptools.build-meta"

1. How the semantics of a setuptools.build_meta differ from directly invoking setup.py; at the moment, the only deliberate difference is that with setuptools.build_meta, the source root is not on sys.path when you invoke it, meaning that you should either stop importing things from the local path, or add sys.path.insert(0, os.dirname(__file__)) to the top of your setup.py file.
2. The fact that, if you are a setup.cfg-only project, when using pyproject.toml setup.py is now optional!

We can cover setuptools.build_meta:__legacy__ in this ticket or in a separate one.

[ErikPohl-Lot49-Projects]

@pganssle Hello! I'd like to look into this one. Looks like a good challenge to take on!

[pganssle]

@ErikPohl-Lot49-Projects Sounds great! This is very important. I will be happy to review as soon as you have a draft.

[ErikPohl-Lot49-Projects]

@pganssle
Thanks! I'll let you know.

[ErikPohl-Lot49-Projects]

@pganssle
I'm going to find time Friday evening and this weekend to review the specifications. I'll let you know if I have questions!

[brettcannon]

I take it work on this has stalled? (I just tried to find the docs on PEP 517 support in setuptools and came up empty-handed and then found this issue.)

[brettcannon]

And a note in the docs that skipping setup.py prevents editable installs probably wouldn't go amiss.

[alvyjudy]

Hello! Just a trivial note, the build-backend in the pyroject.toml should be build_meta instead of build-meta otherwise an error will be thrown

[bhrutledge]

I found this via @brettcannon's blog post re: pyproject.toml, which says "no one has had the time to document all of this", and shows an example of a minimal pyproject.toml and setup.py shim.

It looks like there is now some documentation, albeit with room for improvement:

• Build System Support
  
  
  
  • Doesn't seem to be linked from anywhere
  
  
  • Doesn't mention the setup.py shim
  
  
• setup.cfg-only projects
  
  
  
  • It seems like the "Note" and "Warning" could be combined and rewritten to give an example of a setup.py shim for editable installs (or it could link to the previous item)
  
  

Of course, thanks to everyone who's written about this so far. It's very helpful!

[mcshaman]

Also the promise of a list of Resources on Python packaging is a bit of a tease 😅. Would be great if somebody could stick in some links to resources.

[normanius]

I think a note/warning about the following should be added to the documentation as well:

The installation of a PEP517-style package via the _TestPyPI_ infrastructure is likely to fail.
The issues is described in full here: detail: https://github.com/pypa/pip/issues/9242

Since the failure is unexpected and not present if the package is later installed via real PyPI, I recommend that some note is dropped about this until the issue is fixed otherwise.

Newbs (like me) might run quickly into such issues because the use of TestPyPI is advertised in popular packaging tutorials.