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

[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

[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?

[maxfenv]

Thank you @stinovlas for both the kind words towards the setuptools maintainers, and for your suggestion of tuning PYTHONWARNINGS in the CI phase. Do you have a suggestion for an appropriate value there?

Presumably something along the lines of 'error:::setuptools' or similar.

I am not a setuptools maintainer or contributor, but I re-iterate that I thought the communities response to the issue yesterday was unhelpful. Thank you for your efforts and I'm sorry that you have to deal with the borderline hostile response every time. Packaging is hard.

[zahlman]

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

To put numbers on it: support for PEP 517 started in version 40.8.0, but in my testing, 41.1.0 is required for Python 3.11. Python 3.12 made much more disruptive changes (both the removal of distutils and the reform of the importlib machinery, which broke old Setuptools system for optional vendoring) so it presumably requires a considerably higher version than that.

(Honestly, I don't think that legacy projects - the kind that never even had a pyproject.toml - should be/have been expected to work on new versions of CPython indefinitely in the first place. 3.12 seems like as good a place as any to make a clean break. For that matter, it strikes me as absurd that the PSF didn't prioritize modernizing the build process for Requests when taking ownership of it - if you want people to follow modern practices, set a good example! As it stands, Requests has a pyproject.toml, but only uses it for dev tool configuration.)

[eli-schwartz]

(Honestly, I don't think that legacy projects - the kind that never even had a pyproject.toml - should be/have been expected to work on new versions of CPython indefinitely in the first place. 3.12 seems like as good a place as any to make a clean break. For that matter, it strikes me as absurd that the PSF didn't prioritize modernizing the build process for Requests when taking ownership of it - if you want people to follow modern practices, set a good example! As it stands, Requests has a pyproject.toml, but only uses it for dev tool configuration.)

v68.1.0 is the first version of setuptools that had non-experimental support for pyproject.toml as a replacement for setup.cfg

This is a considerably more pessimized timeframe than your reference to 40.8.0

PEP 517 means very little here as no meaningful changes need or needed be made by projects for it. The specification itself already mandates that the absence of PEP 517 metadata means to invoke the setuptools PEP 517 backend, explicitly spelling it out does nearly nothing. (If you think it does something, I invite you to look at the setuptools source code and see the actual difference between the legacy and regular build_meta APIs.)

[stinovlas]

Thank you @stinovlas for both the kind words towards the setuptools maintainers, and for your suggestion of tuning PYTHONWARNINGS in the CI phase. Do you have a suggestion for an appropriate value there?

Presumably something along the lines of 'error:::setuptools' or similar.

@maxfenv: I'd personally go for error::DeprecationWarning. I'd setup a scheduled pipeline with this PYTHONWARNINGS value, which would detect any deprecation warnings that need to be handled (not just setuptools), but wouldn't distrupt normal pipelines while merging features and bugfixes.

[notatallshaw]

If the problem is that deprecation warnings are ignored1 (by tools, humans, or both), I'm unsure how this is an improvement

FWIW I am pushing to have pip output warnings, I am hoping to get this done in time for pip 24.2 (~July release).

However, as you have mentioned, users will then need to read those warnings, but it's at least a step forward. There will need to be further improvement in tooling, and best practices will need to be formed, for users of sdists using build backends that make backwards incompatible changes.

[webknjaz]

I was just looking into another deprecation and realized that I was using the PYTHONWARNINGS thing in many places but not when building the dists.

And so I verified that the following surfaces the warnings just fine:
PYTHONWARNINGS='error,ignore:git archive did not support describe output:UserWarning:setuptools_scm.git,ignore:unprocessed git archival found (no export subst applied):UserWarning:setuptools_scm.git' some-venv/bin/python -Im build

I think that the problem is that it is not recommended by the docs loudly enough. And so I also wanted to suggest having a How-to guide-style document in the docs.

I think that such a document should demonstrate a combination of two or three things:

• PIP_CONSTRAINT with setuptools pinned
• PYTHONWARNINGS
• A transparent update mechanism for the constraint files

The last point could feature pip-tools' --all-build-deps and Dependabot.

This would show PIP_CONSTRAINT=dist-build-constraints.txt PYTHONWARNINGS='error,ignore:git archive did not support describe output:UserWarning:setuptools_scm.git,ignore:unprocessed git archival found (no export subst applied):UserWarning:setuptools_scm.git' some-venv/bin/python -Im build integrated into the build processes (perhaps into workflow tools like tox/nox), being called in CI. And a separate explanation that the constraint bumps must always go through dedicated PRs with traceable outcome.

This could explain how to react to deprecations in a transactional manner.

P.S. OTOH, a better place for such a guide might be PyPUG as it could be generic enough. And setuptools could link that external guide.

[abravalheri]

Thank you @webknjaz.

It is early stages, but I have been considering writing something like (it should expand, this is a very very early draft):

I imagine that https://packaging.python.org/guides/sdist-drawbacks-and-reproducibility would be a nice place to include it? (then we can link it elsewhere).

Just for the clarification: Setuptools try to be as responsive as possible, but it cannot guarantee disruptions will not happen and most importantly it cannot guarantee patches will be applied immediately ("zero-downtime" is not possible). If a project cannot afford waiting for setuptools patches, it is highly recommended to revise the use of sdists and adopt practices that improve reproducibility.

(Sorry for the other participants in the thread. I have not able to go through all the comments yet. So far, what I have been thinking is that a 2-phase deprecation may be beneficial as it allows the users to "temporarily revert" a removal themselves, while making sure the acknowledge the long term risk).