mirror of
https://github.com/astral-sh/uv.git
synced 2025-11-01 12:24:15 +00:00
5a95f50619
## Summary This PR adds limited support for PEP 440-compatible local version testing. Our behavior is _not_ comprehensively in-line with the spec. However, it does fix by _far_ the biggest practical limitation, and resolves all the issues that've been raised on uv related to local versions without introducing much complexity into the resolver, so it feels like a good tradeoff for me. I'll summarize the change here, but for more context, see [Andrew's write-up](https://github.com/astral-sh/uv/issues/1855#issuecomment-1967024866) in the linked issue. Local version identifiers are really tricky because of asymmetry. `==1.2.3` should allow `1.2.3+foo`, but `==1.2.3+foo` should not allow `1.2.3`. It's very hard to map them to PubGrub, because PubGrub doesn't think of things in terms of individual specifiers (unlike the PEP 440 spec) -- it only thinks in terms of ranges. Right now, resolving PyTorch and friends fails, because... - The user provides requirements like `torch==2.0.0+cu118` and `torchvision==0.15.1+cu118`. - We then match those exact versions. - We then look at the requirements of `torchvision==0.15.1+cu118`, which includes `torch==2.0.0`. - Under PEP 440, this is fine, because `torch @ 2.0.0+cu118` should be compatible with `torch==2.0.0`. - In our model, though, it's not, because these are different versions. If we change our comparison logic in various places to allow this, we risk breaking some fundamental assumptions of PubGrub around version continuity. - Thus, we fail to resolve, because we can't accept both `torch @ 2.0.0` and `torch @ 2.0.0+cu118`. As compared to the solutions we explored in https://github.com/astral-sh/uv/issues/1855#issuecomment-1967024866, at a high level, this approach differs in that we lie about the _dependencies_ of packages that rely on our local-version-using package, rather than lying about the versions that exist, or the version we're returning, etc. In short: - When users specify local versions upfront, we keep track of them. So, above, we'd take note of `torch` and `torchvision`. - When we convert the dependencies of a package to PubGrub ranges, we check if the requirement matches `torch` or `torchvision`. If it's an`==`, we check if it matches (in the above example) for `torch==2.0.0`. If so, we _change_ the requirement to `torch==2.0.0+cu118`. (If it's `==` some other version, we return an incompatibility.) In other words, we selectively override the declared dependencies by making them _more specific_ if a compatible local version was specified upfront. The net effect here is that the motivating PyTorch resolutions all work. And, in general, transitive local versions work as expected. The thing that still _doesn't_ work is: imagine if there were _only_ local versions of `torch` available. Like, `torch @ 2.0.0` didn't exist, but `torch @ 2.0.0+cpu` did, and `torch @ 2.0.0+gpu` did, and so on. `pip install torch==2.0.0` would arbitrarily choose one one `2.0.0+cpu` or `2.0.0+gpu`, and that's correct as per PEP 440 (local version segments should be completely ignored on `torch==2.0.0`). However, uv would fail to identify a compatible version. I'd _probably_ prefer to fix this, although candidly I think our behavior is _ok_ in practice, and it's never been reported as an issue. Closes https://github.com/astral-sh/uv/issues/1855. Closes https://github.com/astral-sh/uv/issues/2080. Closes https://github.com/astral-sh/uv/issues/2328. |
||
|---|---|---|
| .. | ||
| python | ||
| src | ||
| test | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| License-Apache | ||
| License-BSD | ||
| Readme.md | ||
PEP440 in rust
A library for python version numbers and specifiers, implementing PEP 440. See Reimplementing PEP 440 for some background.
Higher level bindings to the requirements syntax are available in pep508_rs.
use std::str::FromStr;
use pep440_rs::{parse_version_specifiers, Version, VersionSpecifier};
let version = Version::from_str("1.19").unwrap();
let version_specifier = VersionSpecifier::from_str("==1.*").unwrap();
assert!(version_specifier.contains(&version));
let version_specifiers = parse_version_specifiers(">=1.16, <2.0").unwrap();
assert!(version_specifiers.contains(&version));
In python (pip install pep440_rs):
from pep440_rs import Version, VersionSpecifier
assert Version("1.1a1").any_prerelease()
assert Version("1.1.dev2").any_prerelease()
assert not Version("1.1").any_prerelease()
assert VersionSpecifier(">=1.0").contains(Version("1.1a1"))
assert not VersionSpecifier(">=1.1").contains(Version("1.1a1"))
# Note that python comparisons are the version ordering, not the version specifiers operators
assert Version("1.1") >= Version("1.1a1")
assert Version("2.0") in VersionSpecifier("==2")
PEP 440 has a lot of unintuitive features, including:
- An epoch that you can prefix the version which, e.g.
1!1.2.3. Lower epoch always means lower version (1.0 <=2!0.1) - post versions, which can be attached to both stable releases and prereleases
- dev versions, which can be attached to sbpth table releases and prereleases. When attached to a prerelease the dev version is ordered just below the normal prerelease, however when attached to a stable version, the dev version is sorted before a prereleases
- prerelease handling is a mess: "Pre-releases of any kind, including developmental releases, are implicitly excluded from all version specifiers, unless they are already present on the system, explicitly requested by the user, or if the only available version that satisfies the version specifier is a pre-release.". This means that we can't say whether a specifier matches without also looking at the environment
- prelease vs. prerelease incl. dev is fuzzy
- local versions on top of all the others, which are added with a + and have implicitly typed string and number segments
- no semver-caret (
^), but a pseudo-semver tilde (~=) - ordering contradicts matching: We have e.g.
1.0+local > 1.0when sorting, but==1.0matches1.0+local. While the ordering of versions itself is a total order the version matching needs to catch all sorts of special cases