[FR] Suggestion for 2 phase deprecation system from community

[abravalheri]

If you have been using python -m build to build your package you might have seen something like this before.

... and if you have automated your builds with CI/CD, then the deprecation warnings got lost in noise and CI logs that nobody reads.

#4892 and #4910 are a clear indication that setuptool's current deprecation system and policy is not working for the community. Even your own CI detected a problem with this deprecation. You disabled the failing test in #4909 instead of reconsidering the root cause for the failing test.

I suggest that you adopt a multi-phase deprecation system. In the first phase you issue a warning and document the deprecation. In the second phase you turn the deprecation warning into an error, but have a setting (environment variable) that turns the exception back into a warning. The setting is bound to a version number, e.g. SETUPTOOLS_DEPRECATIONS=77.0.0.

Originally posted by @tiran in #4911 (comment)

[mattwthompson]

If the problem is that deprecation warnings are ignored¹ (by tools, humans, or both), I'm unsure how this is an improvement. The deprecations in the first phase would continue to be ignored in CI logs until errors are raised. When errors are raised in the second "phase", carve-outs for behavior would need to be shimmed in for an undetermined amount of time, likely just pushing the pain into the future. What about errors that can't simply be quieted down to warnings?

How many versions would this SETUPTOOLS_DEPRECATIONS band-aid be supported for? If for only one major version, the value add over just using the older version is usually going to be small. If forever, that would be wildly complex to maintain. If for a few major versions or some rolling window of many months to a few years, it wouldn't really fix the problem of people wanting to install un-maintained software, or at least won't do any better than just using an old version of Setuptools.

Footnotes

1. Evidently this is at least a part of the problem, if a deprecation from March 2021 can't be actioned by the ecosystem in March 2025 ↩

[david-engelmann]

When switching over to the second phase, we should ensure that the libraries helper functions are prepared for the change. One of the challenges of the #4910 issue today, was libraries without an explicit setup.cfg files failed, even though they use the libraries provided setup function from from setuptools import setup. It's one thing if the user has ignored the warnings and can quickly adjust the - to and _ but its another if its handled by the setuptools library itself

[abravalheri]

Hi @david-engelmann could you please name which projects without setup.cfg fail for investigation.

Is this because a dependency had the problem? I want to understand this other scenario. If they failed because a dependency failed I would still consider a problem exclusive to setup.cfg.

Please note that setuptools does not have control of the installation of dependencies.

[david-engelmann]

@abravalheri here is the repos issue related to #4910 -> olirice/alembic_utils#153 (comment). basically, the repo uses just a setup.py file, which calls the from setuptools import setup. If an additional setup.cfg file is added with the new name, it was possible to build but without adding an explicit setup.cfg, we were at the mercy of the setuptools setup function

[abhiaagarwal]

Imo, this is more of a sin of the build system standard implicitly installing the latest version of setuptools. I don't really mind there was a breaking change in abstract. I do mind that the transitive dependency of setuptools that I have zero control over (and not in my uv.lock file) nuked our CI for a day.

[david-engelmann]

Imo, this is more of a sin of the build system standard implicitly installing the latest version of setuptools. I don't really mind there was a breaking change in abstract. I do mind that the transitive dependency of setuptools that I have zero control over (and not in my uv.lock file) nuked our CI for a day.

Yeah, the fact that poetry can't pickup a setuptools version with a simple pyproject.toml change is a major part of the resolution issue, and I was just lucky I could include the below commands before my main poetry install command

poetry run pip install setuptools==77.0.3 && \
poetry run pip install --no-build-isolation alembic_utils==0.8.3 && ...

I still think regardless, if a breaking change is pushed, the helper functions should be able to handle it, or depreciate those functions

[abhiaagarwal]

@david-engelmann yep, which leads to the implication that reproducible builds aren't possible... I'm honestly shocked that build systems exist "outside" a package rather than being part of it. I'm not sure how setuptools can have any sort of deprecation without some sort of agreement that starting today, we all put constraints on our build-system.requires, and all prior packages imply setuptools<x.

[jackklika]

Stepping back, what specific reasons are there not to allow dash aliases like long-description instead of long_description? If it has been working as intended this long, what specific, real issues are there with recognizing and supporting de facto usage?

[david-engelmann]

Stepping back, what specific reasons are there not to allow dash aliases like long-description instead of long_description? If it has been working as intended this long, what specific, real issues are there with recognizing and supporting de facto usage?

IMO, the specifics of todays changes are irrelevant for this issue

[jackklika]

Stepping back, what specific reasons are there not to allow dash aliases like long-description instead of long_description? If it has been working as intended this long, what specific, real issues are there with recognizing and supporting de facto usage?

IMO, the specifics of todays changes are irrelevant for this issue

OK. I will start a different issue at #4918 . Sorry for off-topic

[eli-schwartz]

@david-engelmann yep, which leads to the implication that reproducible builds aren't possible... I'm honestly shocked that build systems exist "outside" a package rather than being part of it. I'm not sure how setuptools can have any sort of deprecation without some sort of agreement that starting today, we all put constraints on our build-system.requires, and all prior packages imply setuptools<x.

Reproducible builds are possible, linux distros have been doing them for a while. Pip is not involved, and build isolation is explicitly shunned.

Constraints don't help, by the way. New versions of setuptools are sometimes mandatory in order to support new versions of CPython.

Keeping software usable over the course of years and decades is a challenging job. Linux distros have managed for a long time, including by reserving the right to apply patches to software in order to keep it building. Sometimes those patches are to remove constraints ;) and other times it is to fix deprecated and removed API usage.

[eli-schwartz]

How many versions would this SETUPTOOLS_DEPRECATIONS band-aid be supported for? If for only one major version, the value add over just using the older version is usually going to be small. If forever, that would be wildly complex to maintain. If for a few major versions or some rolling window of many months to a few years, it wouldn't really fix the problem of people wanting to install un-maintained software, or at least won't do any better than just using an old version of Setuptools.

It seems like the current state of the art in deprecations for setuptools development is to have no errors, just deprecations, for a very long period of time until the setuptools developers eventually decide they have "had enough", on the scale of a few years.

The problem is apparently that nobody notices them until the very end.

Switching over to a SETUPTOOLS_DEPRECATIONS variable, as the suggestion was given, doesn't affect the several years long timeframe at all... it would mean that you'd start getting errors after only a few months, but still have several years to band-aid the problem in order to get things working.

I don't really see how that adds any more "wildly complex" maintenance, or makes the problem worse from a perspective of these deprecations being overall desirable.

[mattwthompson]

My "wildly complex" wording refers only to the scenario that these backdoors for old behavior exist forever for all removals or breaking changes. That seems obviously bad, or at very least underspecified.

[eli-schwartz]

It is approximately as bad / underspecified as any software that periodically adds additional features but doesn't tend to drop features. Software becomes more complex and also more capable. It's just yet another software development philosophy.

But that's irrelevant either way. You're the first person in this ticket to suggest that this ticket may entail keeping it forever, so maybe the answer to your question about scenarios is to simply recant that entire line of thought and instead talk about the actual proposal of the ticket.

For the record I do apologize for initially being confused, and thinking that you had a question about the proposal, and seeking to explain it.

[stinovlas]

I have an utmost respect for setuptools maintainers. Selflessly maintaining a cornerstone of Python package ecosystem is hard and nobody should be angry at you for removing a feature that has been deprecated for 4 years. It is unfortunate that people just cry for a revert each time you do something like this.

As for the deprecation process: I think that the proposed process is helpful. Especially the second phase, where you raise an error (which causes people to notice the change), but also provide an easy way to silence it before it's resolved. This is important because people can continue with their work and resolve the problem when they have more time for it. If they just set the silencer and don't fix it, well, than that's on them when the feature is finally removed.

However, I think people can already implement this with appropriately aggressive setting of PYTHONWARNINGS in their build CIs (making the errors opt-in rather than opt-out, which is less optimal, but still better than the current state). Maybe suggesting that in the setuptools docs would be a good first step that should be fairly easy to implement?