pip: Docs issue: `setup_requires` is explained as problematic in cookbook, but no comparable replacement appears to be given

https://pip.readthedocs.io/en/1.4.1/cookbook.html#controlling-setup-requires

This section and various other sources (like https://github.com/cython/cython/issues/2730#issuecomment-473716573 and other helpful comments) say that setup_requires has issues due to its reliance on easy_install and should be avoided.

However, the above cookbook section doesn’t actually appear to offer any alternative! I think if you want people to stop using it, this section should really show one. All it appears to do is to show how to work around the package index options not working while still using setup_requires, or am I misunderstanding this section completely?

It would be incredibly helpful if that cookbook section could be expanded to add a demonstration of a full example of a modern setup_requires-equivalent, how it should be done if one wants to avoid deprecated functionality. (or if that is already somewhere else in the cookbook, maybe it would be wise to add a link/reference here?) Because it’s not obvious at all to me how to do it 😕

PS: you’re doing great work this is just a minor bump I found worth reporting!

About this issue

Original URL
State: closed
Created 5 years ago
Reactions: 1
Comments: 18 (9 by maintainers)

Commits related to this issue

Update documentation slightly to mention pyproject.toml and build requirements refs #6345 — committed to benjaoming/pip by benjaoming 3 years ago
Update documentation slightly to mention pyproject.toml and build requirements refs #6345 — committed to benjaoming/pip by benjaoming 3 years ago

Most upvoted comments

Documentation PRs to clarify would be welcome.

pradyunsg on Mar 26, 2019

@JonasT setupmeta is a tool that auto-generates some setup.py content (I know it’s not entirely accurate, but let’s keep things simple). It is not essential to packaging, thus not mentioned in docs.

uranusjr on Mar 24, 2019

What is setup_requires="setupmeta"? That doesn’t appear to be mentioned in the cookbook either

ghost on Mar 20, 2019

I believe setuptools maintainers still prefer people to not use setup_requires, so it still makes sense for pip documentation to discourage it.

Indeed
https://setuptools.readthedocs.io/en/latest/references/keywords.html setup_requires
Warning

Using setup_requires is discouraged in favor of PEP-518

I’m not against PEP-518 or against what pip is currently doing/recommending/warning about, but that particular quote must be from a time before setuptools 42.0, since it continues with ...even going so far as to download them using EasyInstall

soerenwolfers on Feb 10, 2021

Example pyproject.toml:

[build-system]
requires = ["flit"]  # <--- this is what [build-system.requires] is referring to
build-backend = "flit.api:main"

IMHO using [build-system.requires] to refer to it is wrong because it is not a table. build-system.requires on the other hand is correct. The below file is equivalent to the above per the toml spec.

pyproject.toml:

build-system.requires = ["flit"]
build-system.build-backend = "flit.api:main"

hexagonrecursion on Feb 5, 2021

What is pytoml.yml?

The equivalent of setup_requires is roughly PEP 518’s [build-system.requires] in pyproject.toml. The equivalence may not be exact - the principle is the same, but replicating the precise feature set of setup_requires was not the goal of the PEP (specifically, build-system.requires uses pip’s mechanisms for finding packages, whereas setup_requires uses easy_install’s).

BTW, the link you posted is to an extremely old version of the docs. The current version is here (but it says the same, so your point remains).

Documentation PRs to clarify would be welcome.

pfmoore on Mar 17, 2019