Offer direct guidance for replacing bdist_wheel.universal

[webknjaz]

This is a follow-up to #4617 which deprecated the universal flag of bdist_wheel. It originally offered people to complain in issues. I, however, think that it's useful to mention the non-deprecated alternative that will keep working past deprecation date. This is what this patch implements.

Summary of changes

Ref #4617

Pull Request Checklist

• Changes have tests
• News fragment added in newsfragments/.
  (See documentation for details)

[abravalheri]

Hi @webknjaz thank you very much for the PR.

The original issue motivating #4617 and reported in #4613 was that users expected setuptools to automatically validate python-requires and indicate that the universal setting was incompatible.

It appears that python_tag may be affected by a similar limitation. Given that, I am uncertain about the recommendation proposed in this PR.

[webknjaz]

@abravalheri there's a number of projects that might need backwards compatibility, many versions back. So people end up having to set this option and building across a big matrix of Pythons. This means that they'll have to use a very old version of setuptools in a portion of jobs and a very new one in the rest. And so this suggestion makes it possible.

[abravalheri]

That is fair.

Should we add a note saying that compatibility with python_requires/requires-python is not automatically enforced by setuptools and required to be manually verified by the package developer then?

[fervand1]

Hello @webknjaz @abravalheri

In our project we have following set in setup.cfg

[bdist_wheel]
universal = 1

If I understand correctly, the change would be to just set following is that right?

[bdist_wheel]
python_tag = py2.py3 

I did a quick test and it seems to work.

But if I have set python_tag under the options in setup.cfg. The wheel generated are either py3-none-any.whl (tested) or py2-none-any.whl (didn't check this but am assuming based on py3 whl compilation) depending on the python environment the build was created on which is not maintaining the same behavious as the universal whl creation flag.

Update: on how I set under the options as I wasn't if this is the correct usage

[options]
python-tag = 
	py2.py3

Your inputs will be valuable. Thanks

[webknjaz]

Should we add a note saying that compatibility with python_requires/requires-python is not automatically enforced by setuptools and required to be manually verified by the package developer then?

Probably. I wasn't planning on submitting additional content for this within the scope of the PR, though. It's just a thing I've faced and wanted to document publicly.

---

If I understand correctly, the change would be to just set following is that right?

[bdist_wheel]
python_tag = py2.py3 

I did a quick test and it seems to work.

Yes, this is correct. It's a direct equivalent of universal. This section is processed by the wheel code (the bdist_wheel subcommand).

universal = 1 is literally implemented as setting python_tag = py2.py3 instead of computing it dynamically: https://github.com/pypa/setuptools/blob/7fc3471/setuptools/command/bdist_wheel.py#L336-L340. It does nothing beyond that. Note that it's only applicable in case of pure-python projects. And in projects with C-extensions, both are no-op.

But if I have set python_tag under the options in setup.cfg. The wheel generated are either py3-none-any.whl (tested) or py2-none-any.whl (didn't check this but am assuming based on py3 whl compilation) depending on the python environment the build was created on which is not maintaining the same behavious as the universal whl creation flag.

Update: on how I set under the options as I wasn't if this is the correct usage

[options]
python-tag = 
	py2.py3

This is not a genetic setting applicable to setuptools. You must configure the wheel subsystem to apply proper tags. Other artifacts, like sdist, don't have tags and so it's not applicable on the global level. Setuptools will usually ignore unknown options.

[webknjaz]

users expected setuptools to automatically validate python-requires and indicate that the universal setting was incompatible.

Actually, this reminds me of a number of discussions I've had 4 years ago, starting with pypa/packaging.python.org#726 (comment).

If anything, it's Twine that would need to validate such things. Because it's about metadata and not backend-specific configs.

In fact, it looks like all my issues that still remain open in Twine revolve around this topic: https://github.com/pypa/twine/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20author%3Awebknjaz.
Especially, pypa/twine#739.

[Copilot]

Pull Request Overview

This PR updates the deprecation messaging for the "universal" flag in bdist_wheel to provide direct guidance on replacing it with the recommended configuration alternative.

• Updated the help text for the "universal" option in the command options list.
• Revised the deprecation message in finalize_options to instruct users to set "python_tag = py2.py3" in setup.cfg.

Comments suppressed due to low confidence (2)

setuptools/command/bdist_wheel.py:177

• Consider adding a link or reference to the relevant documentation that explains the python_tag = py2.py3 configuration in detail.

"*DEPRECATED* make a universal wheel [default: false]\n\nSet `python_tag = py2.py3` in `setup.cfg` instead."

setuptools/command/bdist_wheel.py:276

• For consistency, consider unifying the wording between the help text and this deprecation message, ideally including the same phrasing or reference.

"The use of this setting can be replaced with `python_tag = py2.py3`\n                entry in `setup.cfg`."