Repository navigation
Maintaining the example build backend specifiers #1886
Description
Issue Description
In #1880, questions were raised regarding the maintainability of the example build backend dependencies. Specifically:
- how to handle backends that recommend upper bounds on the backend version (while tools that create per-package build environments can handle those without issue, they are a potential problem for build systems that aim to create unified build environments, such as those for Linux distros and from-source stack building projects like fromager)
- how to ensure we're not recommending excessively outdated versions of the backends
Some flavour of automation could help with the latter problem, but the former problem is a trickier one.
Code of Conduct
- I am aware that participants in this repository must follow the PSF Code of Conduct.
Activity
sinoroc commented on Aug 3, 2025
As I said over there, I wonder if the guide should maintain those version numbers at all. Maybe the guide should rather focus on teaching what versions constraints are, why they matter, how to use them, and when to use them. The guide should also nudge the readers to refer to each project's documentation (and change log) to find project specific and up to date advice (actual version numbers), i.e. things the guide's authors might not want to be held responsible for.
Is it something Dependabot could do, or be tricked into doing? It seems Dependabot might have support for build-system.requires.
webknjaz commented on Aug 14, 2025
I don't think Dependabot is the answer. The guide should include minimum versions that introduce features being demonstrated. But since some backends are at odds with downstreams, we should at least include a warning in the example widget talking about the dangers and referencing the discussion contributed @ #1791.
Talking about the constraints is useful but I think the context is not exactly the same. Constraints are useful for the upstreams to keep the CI stable and the builds reproducible.
It would be nice to have the actual concrete versions included in the metadata of sdists/wheels. They'd be useful for future troubleshooting and knowing what actually worked at the time a project published their dists to PyPI.
At EuroPython somebody (I don't remember the name) suggested that this might require something like a core packaging metadata change. I think @uranusjr and I (IIRC) suggested that it's possible to have a PoC without a metadata update, though.
notatallshaw commented on Aug 14, 2025
Taking a step back, who is this documentation targeted towards?
For personal or private applications all of this is probably the wrong advice, and almost certainly the correct advise is either to pin to a major version, e.g. setuptools ~= 77.0, or pin to an exact version, e.g. setuptools == 70.3.0. And to regularly check for updates (preferably using automated tooling) to see if new build backend versions are still compatible with existing build.
This pinning is required because no lock file yet offers build dependency locking, so it can not be recommended to have permissive requirements and but use a lock file for reproducible dependencies and builds.
But I assume that the documentation is targeting open source library authors? Which makes sense on the one hand because we're probably all open source library maintainers here, but is odd in another because there's probably significantly more personal and private applications using Python than there are open source libraries.
Personally I would like to see lock files, rather than constraints, offered by applications as part of their metadata, for users to be able to have the option to use the application authors predefined reproducible dependencies and builds, but there was significant push back on this idea: https://discuss.python.org/t/pre-pep-include-pylock-toml-files-inside-wheels/99385 / https://discuss.python.org/t/pre-pep-add-ability-to-install-a-package-with-reproducible-dependencies/99497 (although IMO the author of these threads didn't understand the rigors of providing a PEP).
rgommers commented on Nov 12, 2026
It's inside a tutorial about writing one's pyproject.toml, so I think open source authors as well as folks writing their own Python code locally (this is a much larger group).
This looks like a false duality to me. About half the user base are doing science, data science, ML/AI etc. by now; that kind of user isn't an "application" developer or user, but essentially a power user managing their work through standard packaging tools and interfaces that are also used for open source libraries.
+1
This doesn't look like the right advice for the power user use case in general. Perhaps for setuptools yes, because it's so unstable. But in general, no bounds or a wide range works just fine - other well-maintained build backends seem to not put any version numbers in their docs. uv_build may be the exception here because it's so new and fast-moving.
I think either this, or no versions at all unless it's specific to a section that uses a very new feature.
In practice the current state wouldn't be much of an issue if the lower bounds got bumped say quarterly. The current no-bumps for most backends and weekly bumps for uv_build is just not good.
There is an existing cron job for uv_build, perhaps the pragmatic solution here is to extend that to other build backends and put it to some reasonable frequency (minimum monthly, better quarterly) to avoid PR pollution.
rgommers commented on Nov 12, 2026
uv_build update frequency was reduced (i.e., improved) in gh-2184. Lower bounds of other build backends wasn't touched yet, updates to those are manual right now.