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

[ghost]

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

This section and various other sources (like cython/cython#2730 (comment) 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!

[ghost]

I'm wondering, is it pyproject.toml's build_requires which I should be using maybe? But I'm really wildly guessing here, I really don't know

(Edited by @uranusjr to correct the file name.)

[pfmoore]

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.

[ghost]

@pfmoore yeah I meant pyproject.toml 😂 I know so little about it I don't even get the name right

[jpic]

Personnally i'm very happy with setup_requires="setupmeta" which takes care of the setup.py boilerplate for us. Now if this were to become something that would also require configuration in a new file for distutils configurations, then we'd be defeated in our purpose to eliminate boilerplate code using setup_requires.

[ghost]

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

[uranusjr]

@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.

[pradyunsg]

Documentation PRs to clarify would be welcome.

[joesinghh]

Hello , can i get assigned for this issue ?

[uranusjr]

@Joe-Sin7h Sure, please feel free to go ahead!

[joesinghh]

@uranusjr Hello sir could you help me , I'm new to open source.
Could you Please explain me in detail about the issue. In pyproject.toml there is no [build-system.requires].
I also Tried Looking into this File.
Not Sure if that's the right file.

I'll be thankful to you

[hexagonrecursion]

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"

[soerenwolfers]

The problems with setup_requires disappeared with setuptools 42.0.0, which switched to using pip to resolve setup_requires (https://setuptools.readthedocs.io/en/latest/history.html#v42-0-0)

[uranusjr]

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

[hexagonrecursion]

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

[hexagonrecursion]

https://pip.pypa.io/en/stable/user_guide/#installation-bundles

Warning

Finally, beware of the setup_requires keyword arg in setup.py. The (rare) packages that use it will cause those dependencies to be downloaded by setuptools directly, skipping pip’s protections. If you need to use such a package, see Controlling setup_requires.

This warning is aimed at the users of pip - people who use pip to install packages rather than package authors. The warning is given in the context of the section "Ensuring Repeatability". The section talks about different options (pinned version numbers, hash-checking and pip wheel) pip has to help its users create reproducible environments. IMHO given the context and the audience it gives the only advice that is relevant.

[soerenwolfers]

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

[benjaoming]

@pradyunsg is looking to fix this through #9475

[pradyunsg]

This is now covered within https://pip.pypa.io/en/stable/reference/build-system/#controlling-setup-requires. There's also cross links to that section in https://pip.pypa.io/en/stable/topics/repeatable-installs/ (at the end) and https://pip.pypa.io/en/stable/topics/secure-installs/#repeatable-installs.