Warn users on `~=` python version specifier by aaron-ang · Pull Request #14008 · astral-sh/uv

aaron-ang · 2025-06-12T22:07:58Z

Summary

Picking up on #8284, I noticed that the requires_python object already has its specifiers canonicalized in the intersection method, meaning ~=3.12 is converted to >=3.12, <4. To fix this, we check and warn in intersection.

Test Plan

Used the same tests from #8284.

aaron-ang · 2025-06-13T05:28:35Z

crates/uv/tests/it/lock.rs

+    ----- stdout -----
+
+    ----- stderr -----
+    warning: The release specifier (`~=3.12`) contains a compatible release match without a patch version. This will be interpreted as `>=3.12, <4`. Did you mean `~=3.12.[X]` to freeze the minor version?


How do I hardcode 0 as the patch version? The test converts the patch version to [X], for example ~=3.12.0 to ~=3.12.[X].

The test suite is agnostic to patch versions by default, to allow testing against a wider range of versions downstream.

Do you need the patch version to be represented in this snapshot?

I see, you want the literal .0 to show. There are a couple things

We should consider updating

uv/crates/uv/tests/it/common/mod.rs

Lines 571 to 576 in a748336

if version.patch().is_none() {

filters.push((

format!(r"({})\.\d+", regex::escape(version.to_string().as_str())),

"$1.[X]".to_string(),

));

}

to only filter the actual patch version used in the test, rather than an arbitrary \d — that seems separate from this change.

You can select a specific patch version from https://github.com/astral-sh/uv/blob/56ce40b0f4139539f345987f7d5bf88236ae2909/.python-versions then request it in test context construction and add the #[cfg(feature = "python-patch")] feature to the test

I couldn't figure out a straightforward way to get the patch version in crates/uv/tests/it/common/mod.rs, so I went with the second option.

aaron-ang · 2025-06-13T23:21:59Z

rebased with main

aaron-ang · 2025-06-23T15:10:11Z

hi @zanieb, any updates on this?

zanieb · 2025-06-27T20:48:38Z

Thanks for you patience :)

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.7.14` -> `0.7.16` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.7.16`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0716) [Compare Source](astral-sh/uv@0.7.15...0.7.16) ##### Python - Add Python 3.14.0b3 See the [`python-build-standalone` release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250626) for more details. ##### Enhancements - Include path or URL when failing to convert in lockfile ([#14292](astral-sh/uv#14292)) - Warn when `~=` is used as a Python version specifier without a patch version ([#14008](astral-sh/uv#14008)) ##### Preview features - Ensure preview default Python installs are upgradeable ([#14261](astral-sh/uv#14261)) ##### Performance - Share workspace cache between lock and sync operations ([#14321](astral-sh/uv#14321)) ##### Bug fixes - Allow local indexes to reference remote files ([#14294](astral-sh/uv#14294)) - Avoid rendering desugared prefix matches in error messages ([#14195](astral-sh/uv#14195)) - Avoid using path URL for workspace Git dependencies in `requirements.txt` ([#14288](astral-sh/uv#14288)) - Normalize index URLs to remove trailing slash ([#14245](astral-sh/uv#14245)) - Respect URL-encoded credentials in redirect location ([#14315](astral-sh/uv#14315)) - Lock the source tree when running setuptools, to protect concurrent builds ([#14174](astral-sh/uv#14174)) ##### Documentation - Note that GCP Artifact Registry download URLs must have `/simple` component ([#14251](astral-sh/uv#14251)) ### [`v0.7.15`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0715) [Compare Source](astral-sh/uv@0.7.14...0.7.15) ##### Enhancements - Consistently use `Ordering::Relaxed` for standalone atomic use cases ([#14190](astral-sh/uv#14190)) - Warn on ambiguous relative paths for `--index` ([#14152](astral-sh/uv#14152)) - Skip GitHub fast path when rate-limited ([#13033](astral-sh/uv#13033)) - Preserve newlines in `schema.json` descriptions ([#13693](astral-sh/uv#13693)) ##### Bug fixes - Add check for using minor version link when creating a venv on Windows ([#14252](astral-sh/uv#14252)) - Strip query parameters when parsing source URL ([#14224](astral-sh/uv#14224)) ##### Documentation - Add a link to PyPI FAQ to clarify what per-project token is ([#14242](astral-sh/uv#14242)) ##### Preview features - Allow symlinks in the build backend ([#14212](astral-sh/uv#14212)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

…14335) Follows #14008

ashb · 2025-07-02T14:27:57Z

Any chance we could revert this @zanieb @aaron-ang?

As discussed in #14335 (comment) this handling and warning of using ~=3.12 goes counter to the documented Python Version Specifier behaviour, and this is warning rejects something that is

Valid
Well defined and specified, and not actually ambiguous.
Was already behind handled as per the spec and in line with other tools

zanieb · 2025-07-02T14:35:45Z

I've opened an issue for discussion so we can centralize things instead of commenting across pull requests: #14422

notatallshaw · 2025-07-02T15:49:47Z

As discussed in #14335 (comment) this handling and warning of using ~=3.12 goes counter to the documented Python Version Specifier behaviour, and this is warning rejects something that is
1. Valid

2. Well defined and specified, and not actually ambiguous.

3. Was already behind handled as per the spec and in line with other tools

Unfortunately 1 is true, but 2 and 3 are incorrect.

The spec on pyproject.toml says:

Corresponding core metadata field: Requires-Python
The Python version requirements of the project.

And the core metadata field says:

This field specifies the Python version(s) that the distribution is compatible with. Installation tools may look at this when picking which version of a project to install.

The value must be in the format specified in Version specifiers.

Note that it says format of a Version specifier, not semantics of a Version specifier.

The semantics of what requires-python in the pyproject.toml and Requires-Python in the core metadata field are not specified. And this has led to different tools implementing them differently. There are multiple discussions threads on this:

It clear from the discussions that:

The intention was that requires-python should only specify the minimum
The intention was requires-python should only specify the language version (e.g. it should not encode CPython patch information).

I believe the pylock.toml specification explicitly encodes these intentions in it's specification of requires-python.

It should also be noted that NO tool treats requires-python nor Requires-Python exactly like a PEP 440 Version specifier.

I was hoping to write a PEP this year on standardizing this, but I've found so many different use cases I'm concerned it's not easily possible.

I have no objections to uv handling requires-python on how it best fits it's user. But be aware this is not defined by the specification and interoperability between different tools will continue to be an issue.

potiuk · 2025-07-02T21:42:14Z

Unfortunately 1 is true, but 2 and 3 are incorrect.

Thanks @notatallshaw -> TIL. That's a very sad state of affairs.

aaron-ang force-pushed the compat-version branch from 458dfec to 9137909 Compare June 13, 2025 00:30

aaron-ang temporarily deployed to release June 13, 2025 00:31 — with GitHub Actions Inactive

aaron-ang force-pushed the compat-version branch from 9137909 to ba7c925 Compare June 13, 2025 01:09

aaron-ang marked this pull request as ready for review June 13, 2025 01:11

aaron-ang commented Jun 13, 2025

View reviewed changes

zanieb added the error messages Messaging when something goes wrong label Jun 13, 2025

aaron-ang added 3 commits June 13, 2025 16:16

Warn users on ~= python version specifier

d35a0b9

Use Python 3.13.0 in test

b6b6014

Add uv-warnings dependency

991d3fb

aaron-ang force-pushed the compat-version branch from cb296d2 to 991d3fb Compare June 13, 2025 23:20

aaron-ang temporarily deployed to release June 13, 2025 23:20 — with GitHub Actions Inactive

aaron-ang requested a review from zanieb June 13, 2025 23:22

aaron-ang mentioned this pull request Jun 27, 2025

Warn when project defines a requires-python that pins to a .0 patch version #7426

Closed

zanieb approved these changes Jun 27, 2025

View reviewed changes

zanieb merged commit eab938b into astral-sh:main Jun 27, 2025
110 checks passed

zanieb mentioned this pull request Jun 27, 2025

Update the tilde version specifier warning to include more context #14335

Merged

BrewTestBot mentioned this pull request Jun 27, 2025

uv 0.7.16 Homebrew/homebrew-core#228406

Merged

zanieb added a commit that referenced this pull request Jul 2, 2025

Update the tilde version specifier warning to include more context (#…

43f67a4

…14335) Follows #14008

zanieb mentioned this pull request Jul 2, 2025

Revert warnings for tilde version specifiers without a patch component (e.g., ~=X.y) #14422

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Warn users on `~=` python version specifier#14008

Warn users on `~=` python version specifier#14008
zanieb merged 3 commits intoastral-sh:mainfrom
aaron-ang:compat-version

aaron-ang commented Jun 12, 2025 •

edited

Loading

Uh oh!

aaron-ang Jun 13, 2025 •

edited

Loading

Uh oh!

zanieb Jun 13, 2025

Uh oh!

zanieb Jun 13, 2025 •

edited

Loading

Uh oh!

aaron-ang Jun 13, 2025

Uh oh!

aaron-ang commented Jun 13, 2025

Uh oh!

aaron-ang commented Jun 23, 2025

Uh oh!

zanieb commented Jun 27, 2025

Uh oh!

Uh oh!

ashb commented Jul 2, 2025

Uh oh!

zanieb commented Jul 2, 2025

Uh oh!

notatallshaw commented Jul 2, 2025 •

edited

Loading

Uh oh!

potiuk commented Jul 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	if version.patch().is_none() {
	filters.push((
	format!(r"({})\.\d+", regex::escape(version.to_string().as_str())),
	"$1.[X]".to_string(),
	));
	}

Comments

Conversation

aaron-ang commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

aaron-ang Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaron-ang Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

aaron-ang commented Jun 13, 2025

Uh oh!

aaron-ang commented Jun 23, 2025

Uh oh!

zanieb commented Jun 27, 2025

Uh oh!

Uh oh!

ashb commented Jul 2, 2025

Uh oh!

zanieb commented Jul 2, 2025

Uh oh!

notatallshaw commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

potiuk commented Jul 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aaron-ang commented Jun 12, 2025 •

edited

Loading

aaron-ang Jun 13, 2025 •

edited

Loading

zanieb Jun 13, 2025 •

edited

Loading

notatallshaw commented Jul 2, 2025 •

edited

Loading