Add uv-build to table

[cbrnr]

uv-build is stable since 0.7.19 and supports PEP 639.

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1880.org.readthedocs.build/en/1880/

[cbrnr]

I'm happy to add uv-build in the other locations mentioned in the linked issue. Is it OK in this PR, or should I open a new one?

[cbrnr]

I think it's easy enough to add this here.

[cbrnr]

I noticed that the table in writing-pyproject-toml.rst lists hatchling 1.27.0, whereas build-backend-tabs.rst contains 1.26.0. Should I fix this and if so, which one is the correct version?

[webknjaz]

It's probably a good idea to separate such changes. Also, the broken link needs a separate PR too, to unblock this.

[webknjaz]

Upper limits are normally discouraged. What's the justification here?

[cbrnr]

See the note in their official docs: https://docs.astral.sh/uv/concepts/build-backend/#using-the-uv-build-backend

[konstin]

We make (careful) breaking changes in the configuration format in 0.x releases, i.e. the configuration is only stable between >=0.x and <0.(x+1). Being a build backend, the usual concerns about upper bounds don't apply: The uv build backend is a binary with only a minimal Python shim, so older versions of the build backend will still work with newer Python versions. It has zero dependencies and is the only package in the build venv, so the aren't any conflicts the upper bound could cause.

[webknjaz]

Being a build backend, the usual concerns about upper bounds don't apply

That may be true upstream, but may present a challenge for the downstream maintainers as they often have a single version of a thing across their entire repositories (per distro release).

cc @befeleme @hroncok @mgorny any downstream insights on this?

[hroncok]

Please don't encourage upper bounds here. If you do, we'll and up in a position where we cannot update uv-build until we lift them. We won't be even able to test the packages with the new uv-build version in Fedora because of the pin.

Thanks @webknjaz for the mention.

[ncoghlan]

Getting back to the specific question of this PR review (rather than the more general ones of showing exact version numbers and upper bounds in build dependencies):

• mentioning uv-build is a reasonable change to make
• the exact build backend version number problem is an existing issue, not new in this PR
• the upper bound problem is an existing issue (due to flit), not new in this PR

That says to me that we should define a new PyPUG issue regarding the maintainability of those config snippets, and avoid having that concern block this PR.

I've created that issue here: #1886

@webknjaz Given the creation of the dedicated issue, are you happy to consider the question resolved for the purpose of adding uv-build to the example backends?

[webknjaz]

@ncoghlan I'm worried that accepting this as is would make the existing problem worse. And doing so is too impactful to just disregard it. The downstreams have expressed legitimate concern. Perhaps, we should address that issue you filed first so this PR wouldn't be as harmful?

---

@notatallshaw

because indeed they can not be kept up to date

I see regular PRs to update the setuptools lower bound, why would this be any different?

This is different because the example with setuptools is adding new features and when documenting them, the bound has to be updated for things to work. Inevitably.

But the same isn't happening when things break. Nobody comes in to update the guide documenting breakages and adjusting related bounds. And so there's no process for when this would be happening.

There should be a very obvious note leading to an explanation of why one should set version constraints with examples of how to write such version constraints and an advice to go check each project's own documentation regarding their versioning policies.

Every other build back end has lower bound version constraints, flit has lower and upper: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/

Why are you adding this requirement for uv_build when it's not been required to any other build back end?

Lower bounds are fine. Flit was mostly missed. It should also have an admonition explaining that upper bounds should be updated often. Maybe this admonition makes sense to have below all the examples, not selectively.

[ncoghlan]

I guess my view is that the PR itself isn't really making things worse, it's instead making this existing problem with the status quo more obvious.

Omitting the upper bounds creates an "old project releases may not build" scenario that affects potentially everyone, whereas including them has a more limited impact specifically on "unified build environment" scenarios (which could potentially be mitigated by build tooling changes, such as an option to ignore upper bounds in build dependency declarations and see if anything actually breaks with the newer build tool versions).

[webknjaz]

@mgorny @hroncok while merging this didn't exactly cater to your needs, I'd like to suggest discussing a systemic change to adding mentions of what's important for downstreams throughout PyPUG, if you're interested. Maybe, some admonitions linking to #1791 where relevant.

[konstin]

I've filed a PR to automatically update the uv_build version range, to address the concern that the bounds would go stale: #1899

[johnthagen]

Another place it might be worth mentioning uv_build

• https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license-and-license-files

[cbrnr]

@johnthagen that's already part of this PR.

[cbrnr]

@webknjaz the broken link works for me, can you re-run the failing test?

[webknjaz]

Okay, I restarted it, but since this has been failing in multiple PRs, I don't expect it to succeed. Sometimes, different websites rate-limit or block access for crawlers or networks. In that case, they may open in a regular browser but break when on GitHub's network or just based on the User-Agent or similar.
This means sometimes having to suppress select URLs or configuring something..

[cbrnr]

You're probably right, but I think this problem should then be fixed in a different PR. One option would be to add this URL to linkcheck_ignore. See #1881.

[mgorny]

And I think that the option of uv-build should include a warning that it introduces a dependency on the Rust compiler for pure Python packages, which is a limiting factor for downstream adoption.

[zanieb]

And I think that the option of uv-build should include a warning that it introduces a dependency on the Rust compiler for pure Python packages, which is a limiting factor for downstream adoption.

It sounds pretty challenging to say this in a way that makes sense to the target audience here? It adds a dependency on the Rust compiler for people who are on uncommon systems or won't use prebuilt wheels of uv-build. I don't mean to trivialize the concern, but I don't really see why this belongs in the list of available build backends.

[konstin]

Also note that we're only building pure Python py3-none-any wheels, so it is possible to build a package on any supported linux/windows/mac/... machine and reuse on any other system. Similarly, users of those packages never have to build from source, as py3-none-any wheels exist on the index.

Please see astral-sh/uv#3957 (comment), where we're addressing a lot of the common concerns there.

[ncoghlan]

LGTM, but I'll give @webknjaz time to consider my suggestion on the version number/bounds maintainability question.

[webknjaz]

Alright, let's give it a go.