Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document setuptools.build_meta #1698

Open
pganssle opened this issue Feb 22, 2019 · 14 comments
Open

Document setuptools.build_meta #1698

pganssle opened this issue Feb 22, 2019 · 14 comments

Comments

@pganssle
Copy link
Member

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
Copy link
Member Author

@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
Copy link
Member

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
Copy link
Member

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

@alvyjudy
Copy link
Contributor

alvyjudy commented Mar 30, 2020

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

cbm755 added a commit to plomgrading/plom that referenced this issue Jun 1, 2020
I read pypa/setuptools#1698, and a side effect
of source root not being in sys.path is mentioned: probably that is
related to PyInstaller and other things so I left a commented out thing
in setup.py b/c odds seem high that will effect us.
@bhrutledge
Copy link
Contributor

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
Copy link

mcshaman commented Oct 4, 2020

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
Copy link

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: pypa/pip#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.

@codeandfire
Copy link
Contributor

Hi, is this issue still open for work? Currently I am trying to package a Python project with Rust extensions, and I am finding existing documentation to be sorely lacking, in that most tutorials/guides describe the old way of using setup.py commands. I can't find much advice on migrating to the new PEP-517 style of pyproject.toml and specifying a build-backend like setuptools.build_meta. I would be happy to work through the setuptools.build_meta code and contribute to documentation including tutorials/guides/examples as to how this is meant to be used and what it does behind the scenes. Please do let me know! Thanks!

@abravalheri
Copy link
Contributor

Hi @codeandfire please feel free to submit PRs, documentation improvements are always welcome!

I just recomend discussing your ideas first if they are very big or disruptive (e.g. removing/moving documentation pages).

@codeandfire
Copy link
Contributor

@abravalheri Sure, I do understand. I don't think I want to remove/move anything at the moment, I'm intending to add to the existing documentation and will submit PRs accordingly.

@jacalata
Copy link
Contributor

I think the original topic in this issue has been covered, and it can be closed?

Separately, I opened a discussion proposing moving/removing several pages at #3400

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

10 participants