pioduino/uv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Support transparent Python patch version upgrades (#13954)

Browse Source 
> NOTE: The PRs that were merged into this feature branch have all been
independently reviewed. But it's also useful to see all of the changes
in their final form. I've added comments to significant changes
throughout the PR to aid discussion.

This PR introduces transparent Python version upgrades to uv, allowing
for a smoother experience when upgrading to new patch versions.
Previously, upgrading Python patch versions required manual updates to
each virtual environment. Now, virtual environments can transparently
upgrade to newer patch versions.

Due to significant changes in how uv installs and executes managed
Python executables, this functionality is initially available behind a
`--preview` flag. Once an installation has been made upgradeable through
`--preview`, subsequent operations (like `uv venv -p 3.10` or patch
upgrades) will work without requiring the flag again. This is
accomplished by checking for the existence of a minor version symlink
directory (or junction on Windows).

### Features

* New `uv python upgrade` command to upgrade installed Python versions
to the latest available patch release:
``` 
# Upgrade specific minor version 
uv python upgrade 3.12 --preview
# Upgrade all installed minor versions
uv python upgrade --preview
```
* Transparent upgrades also occur when installing newer patch versions: 
```
uv python install 3.10.8 --preview
# Automatically upgrades existing 3.10 environments
uv python install 3.10.18
```
* Support for transparently upgradeable Python `bin` installations via
`--preview` flag
```
uv python install 3.13 --preview
# Automatically upgrades the `bin` installation if there is a newer patch version available
uv python upgrade 3.13 --preview
```
* Virtual environments can still be tied to a patch version if desired
(ignoring patch upgrades):
```
uv venv -p 3.10.8
```

### Implementation

Transparent upgrades are implemented using:
* Minor version symlink directories (Unix) or junctions (Windows)
* On Windows, trampolines simulate paths with junctions
* Symlink directory naming follows Python build standalone format: e.g.,
`cpython-3.10-macos-aarch64-none`
* Upgrades are scoped to the minor version key (as represented in the
naming format: implementation-minor version+variant-os-arch-libc)
* If the context does not provide a patch version request and the
interpreter is from a managed CPython installation, the `Interpreter`
used by `uv python run` will use the full symlink directory executable
path when available, enabling transparently upgradeable environments
created with the `venv` module (`uv run python -m venv`)

New types:
* `PythonMinorVersionLink`: in a sense, the core type for this PR, this
is a representation of a minor version symlink directory (or junction on
Windows) that points to the highest installed managed CPython patch
version for a minor version key.
* `PythonInstallationMinorVersionKey`: provides a view into a
`PythonInstallationKey` that excludes the patch and prerelease. This is
used for grouping installations by minor version key (e.g., to find the
highest available patch installation for that minor version key) and for
minor version directory naming.

### Compatibility

* Supports virtual environments created with:
  * `uv venv`
* `uv run python -m venv` (using managed Python that was installed or
upgraded with `--preview`)
  * Virtual environments created within these environments
* Existing virtual environments from before these changes continue to
work but aren't transparently upgradeable without being recreated
* Supports both standard Python (`python3.10`) and freethreaded Python
(`python3.10t`)
* Support for transparently upgrades is currently only available for
managed CPython installations

Closes #7287
Closes #7325
Closes #7892
Closes #9031
Closes #12977

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
This commit is contained in:
John Mumm
2025-06-20 10:17:13 -04:00
committed by GitHub
parent 62365d4ec8
commit e9d5780369
73 changed files with 3022 additions and 306 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/uv-python/src/discovery.rs
+89 -22
View File
@@ -8,6 +8,7 @@ use std::{env, io, iter};
use std::{path::Path, path::PathBuf, str::FromStr};
use thiserror::Error;
use tracing::{debug, instrument, trace};
use uv_configuration::PreviewMode;
use which::{which, which_all};
use uv_cache::Cache;
@@ -25,7 +26,7 @@ use crate::implementation::ImplementationName;
use crate::installation::PythonInstallation;
use crate::interpreter::Error as InterpreterError;
use crate::interpreter::{StatusCodeError, UnexpectedResponseError};
use crate::managed::ManagedPythonInstallations;
use crate::managed::{ManagedPythonInstallations, PythonMinorVersionLink};
#[cfg(windows)]
use crate::microsoft_store::find_microsoft_store_pythons;
use crate::virtualenv::Error as VirtualEnvError;
@@ -35,12 +36,12 @@ use crate::virtualenv::{
};
#[cfg(windows)]
use crate::windows_registry::{WindowsPython, registry_pythons};
use crate::{BrokenSymlink, Interpreter, PythonVersion};
use crate::{BrokenSymlink, Interpreter, PythonInstallationKey, PythonVersion};
/// A request to find a Python installation.
///
/// See [`PythonRequest::from_str`].
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[derive(Debug, Clone, PartialEq, Eq, Default, Hash)]
pub enum PythonRequest {
/// An appropriate default Python installation
///
@@ -173,7 +174,7 @@ pub enum PythonVariant {
}
/// A Python discovery version request.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
pub enum VersionRequest {
/// Allow an appropriate default Python version.
#[default]
@@ -334,6 +335,7 @@ fn python_executables_from_installed<'a>(
implementation: Option<&'a ImplementationName>,
platform: PlatformRequest,
preference: PythonPreference,
preview: PreviewMode,
) -> Box<dyn Iterator<Item = Result<(PythonSource, PathBuf), Error>> + 'a> {
let from_managed_installations = iter::once_with(move || {
ManagedPythonInstallations::from_settings(None)
@@ -359,7 +361,29 @@ fn python_executables_from_installed<'a>(
true
})
.inspect(|installation| debug!("Found managed installation `{installation}`"))
.map(|installation| (PythonSource::Managed, installation.executable(false))))
.map(move |installation| {
// If it's not a patch version request, then attempt to read the stable
// minor version link.
let executable = version
.patch()
.is_none()
.then(|| {
PythonMinorVersionLink::from_installation(
&installation,
preview,
)
.filter(PythonMinorVersionLink::exists)
.map(
|minor_version_link| {
minor_version_link.symlink_executable.clone()
},
)
})
.flatten()
.unwrap_or_else(|| installation.executable(false));
(PythonSource::Managed, executable)
})
)
})
})
.flatten_ok();
@@ -452,6 +476,7 @@ fn python_executables<'a>(
platform: PlatformRequest,
environments: EnvironmentPreference,
preference: PythonPreference,
preview: PreviewMode,
) -> Box<dyn Iterator<Item = Result<(PythonSource, PathBuf), Error>> + 'a> {
// Always read from `UV_INTERNAL__PARENT_INTERPRETER` — it could be a system interpreter
let from_parent_interpreter = iter::once_with(|| {
@@ -472,7 +497,7 @@ fn python_executables<'a>(
let from_virtual_environments = python_executables_from_virtual_environments();
let from_installed =
python_executables_from_installed(version, implementation, platform, preference);
python_executables_from_installed(version, implementation, platform, preference, preview);
// Limit the search to the relevant environment preference; this avoids unnecessary work like
// traversal of the file system. Subsequent filtering should be done by the caller with
@@ -671,16 +696,23 @@ fn python_interpreters<'a>(
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &'a Cache,
preview: PreviewMode,
) -> impl Iterator<Item = Result<(PythonSource, Interpreter), Error>> + 'a {
python_interpreters_from_executables(
// Perform filtering on the discovered executables based on their source. This avoids
// unnecessary interpreter queries, which are generally expensive. We'll filter again
// with `interpreter_satisfies_environment_preference` after querying.
python_executables(version, implementation, platform, environments, preference).filter_ok(
move |(source, path)| {
source_satisfies_environment_preference(*source, path, environments)
},
),
python_executables(
version,
implementation,
platform,
environments,
preference,
preview,
)
.filter_ok(move |(source, path)| {
source_satisfies_environment_preference(*source, path, environments)
}),
cache,
)
.filter_ok(move |(source, interpreter)| {
@@ -919,6 +951,7 @@ pub fn find_python_installations<'a>(
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &'a Cache,
preview: PreviewMode,
) -> Box<dyn Iterator<Item = Result<FindPythonResult, Error>> + 'a> {
let sources = DiscoveryPreferences {
python_preference: preference,
@@ -1010,6 +1043,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.map_ok(|tuple| Ok(PythonInstallation::from_tuple(tuple)))
}),
@@ -1022,6 +1056,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.map_ok(|tuple| Ok(PythonInstallation::from_tuple(tuple)))
}),
@@ -1038,6 +1073,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.map_ok(|tuple| Ok(PythonInstallation::from_tuple(tuple)))
})
@@ -1051,6 +1087,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.filter_ok(|(_source, interpreter)| {
interpreter
@@ -1072,6 +1109,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.filter_ok(|(_source, interpreter)| {
interpreter
@@ -1096,6 +1134,7 @@ pub fn find_python_installations<'a>(
environments,
preference,
cache,
preview,
)
.filter_ok(|(_source, interpreter)| request.satisfied_by_interpreter(interpreter))
.map_ok(|tuple| Ok(PythonInstallation::from_tuple(tuple)))
@@ -1113,8 +1152,10 @@ pub(crate) fn find_python_installation(
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &Cache,
preview: PreviewMode,
) -> Result<FindPythonResult, Error> {
let installations = find_python_installations(request, environments, preference, cache);
let installations =
find_python_installations(request, environments, preference, cache, preview);
let mut first_prerelease = None;
let mut first_error = None;
for result in installations {
@@ -1210,12 +1251,13 @@ pub(crate) fn find_best_python_installation(
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &Cache,
preview: PreviewMode,
) -> Result<FindPythonResult, Error> {
debug!("Starting Python discovery for {}", request);
// First, check for an exact match (or the first available version if no Python version was provided)
debug!("Looking for exact match for request {request}");
let result = find_python_installation(request, environments, preference, cache);
let result = find_python_installation(request, environments, preference, cache, preview);
match result {
Ok(Ok(installation)) => {
warn_on_unsupported_python(installation.interpreter());
@@ -1243,7 +1285,7 @@ pub(crate) fn find_best_python_installation(
_ => None,
} {
debug!("Looking for relaxed patch version {request}");
let result = find_python_installation(&request, environments, preference, cache);
let result = find_python_installation(&request, environments, preference, cache, preview);
match result {
Ok(Ok(installation)) => {
warn_on_unsupported_python(installation.interpreter());
@@ -1260,14 +1302,16 @@ pub(crate) fn find_best_python_installation(
debug!("Looking for a default Python installation");
let request = PythonRequest::Default;
Ok(
find_python_installation(&request, environments, preference, cache)?.map_err(|err| {
// Use a more general error in this case since we looked for multiple versions
PythonNotFound {
request,
python_preference: err.python_preference,
environment_preference: err.environment_preference,
}
}),
find_python_installation(&request, environments, preference, cache, preview)?.map_err(
|err| {
// Use a more general error in this case since we looked for multiple versions
PythonNotFound {
request,
python_preference: err.python_preference,
environment_preference: err.environment_preference,
}
},
),
)
}
@@ -1645,6 +1689,24 @@ impl PythonRequest {
Ok(rest.parse().ok())
}
/// Check if this request includes a specific patch version.
pub fn includes_patch(&self) -> bool {
match self {
PythonRequest::Default => false,
PythonRequest::Any => false,
PythonRequest::Version(version_request) => version_request.patch().is_some(),
PythonRequest::Directory(..) => false,
PythonRequest::File(..) => false,
PythonRequest::ExecutableName(..) => false,
PythonRequest::Implementation(..) => false,
PythonRequest::ImplementationVersion(_, version) => version.patch().is_some(),
PythonRequest::Key(request) => request
.version
.as_ref()
.is_some_and(|request| request.patch().is_some()),
}
}
/// Check if a given interpreter satisfies the interpreter request.
pub fn satisfied(&self, interpreter: &Interpreter, cache: &Cache) -> bool {
/// Returns `true` if the two paths refer to the same interpreter executable.
@@ -2086,6 +2148,11 @@ impl fmt::Display for ExecutableName {
}
impl VersionRequest {
/// Derive a [`VersionRequest::MajorMinor`] from a [`PythonInstallationKey`]
pub fn major_minor_request_from_key(key: &PythonInstallationKey) -> Self {
Self::MajorMinor(key.major, key.minor, key.variant)
}
/// Return possible executable names for the given version request.
pub(crate) fn executable_names(
&self,
crates/uv-python/src/downloads.rs
+3 -3
View File
@@ -111,14 +111,14 @@ pub enum Error {
},
}
#[derive(Debug, PartialEq, Clone)]
#[derive(Debug, PartialEq, Eq, Clone, Hash)]
pub struct ManagedPythonDownload {
key: PythonInstallationKey,
url: &'static str,
sha256: Option<&'static str>,
}
#[derive(Debug, Clone, Default, Eq, PartialEq)]
#[derive(Debug, Clone, Default, Eq, PartialEq, Hash)]
pub struct PythonDownloadRequest {
pub(crate) version: Option<VersionRequest>,
pub(crate) implementation: Option<ImplementationName>,
@@ -131,7 +131,7 @@ pub struct PythonDownloadRequest {
pub(crate) prereleases: Option<bool>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ArchRequest {
Explicit(Arch),
Environment(Arch),
crates/uv-python/src/environment.rs
+3
View File
@@ -7,6 +7,7 @@ use owo_colors::OwoColorize;
use tracing::debug;
use uv_cache::Cache;
use uv_configuration::PreviewMode;
use uv_fs::{LockedFile, Simplified};
use uv_pep440::Version;
@@ -152,6 +153,7 @@ impl PythonEnvironment {
request: &PythonRequest,
preference: EnvironmentPreference,
cache: &Cache,
preview: PreviewMode,
) -> Result<Self, Error> {
let installation = match find_python_installation(
request,
@@ -159,6 +161,7 @@ impl PythonEnvironment {
// Ignore managed installations when looking for environments
PythonPreference::OnlySystem,
cache,
preview,
)? {
Ok(installation) => installation,
Err(err) => return Err(EnvironmentNotFound::from(err).into()),
crates/uv-python/src/installation.rs
+145 -2
View File
@@ -1,10 +1,14 @@
use std::fmt;
use std::hash::{Hash, Hasher};
use std::str::FromStr;
use indexmap::IndexMap;
use ref_cast::RefCast;
use tracing::{debug, info};
use uv_cache::Cache;
use uv_client::BaseClientBuilder;
use uv_configuration::PreviewMode;
use uv_pep440::{Prerelease, Version};
use crate::discovery::{
@@ -54,8 +58,10 @@ impl PythonInstallation {
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &Cache,
preview: PreviewMode,
) -> Result<Self, Error> {
let installation = find_python_installation(request, environments, preference, cache)??;
let installation =
find_python_installation(request, environments, preference, cache, preview)??;
Ok(installation)
}
@@ -66,12 +72,14 @@ impl PythonInstallation {
environments: EnvironmentPreference,
preference: PythonPreference,
cache: &Cache,
preview: PreviewMode,
) -> Result<Self, Error> {
Ok(find_best_python_installation(
request,
environments,
preference,
cache,
preview,
)??)
}
@@ -89,11 +97,12 @@ impl PythonInstallation {
python_install_mirror: Option<&str>,
pypy_install_mirror: Option<&str>,
python_downloads_json_url: Option<&str>,
preview: PreviewMode,
) -> Result<Self, Error> {
let request = request.unwrap_or(&PythonRequest::Default);
// Search for the installation
let err = match Self::find(request, environments, preference, cache) {
let err = match Self::find(request, environments, preference, cache, preview) {
Ok(installation) => return Ok(installation),
Err(err) => err,
};
@@ -129,6 +138,7 @@ impl PythonInstallation {
python_install_mirror,
pypy_install_mirror,
python_downloads_json_url,
preview,
)
.await
{
@@ -149,6 +159,7 @@ impl PythonInstallation {
python_install_mirror: Option<&str>,
pypy_install_mirror: Option<&str>,
python_downloads_json_url: Option<&str>,
preview: PreviewMode,
) -> Result<Self, Error> {
let installations = ManagedPythonInstallations::from_settings(None)?.init()?;
let installations_dir = installations.root();
@@ -180,6 +191,21 @@ impl PythonInstallation {
installed.ensure_externally_managed()?;
installed.ensure_sysconfig_patched()?;
installed.ensure_canonical_executables()?;
let minor_version = installed.minor_version_key();
let highest_patch = installations
.find_all()?
.filter(|installation| installation.minor_version_key() == minor_version)
.filter_map(|installation| installation.version().patch())
.fold(0, std::cmp::max);
if installed
.version()
.patch()
.is_some_and(|p| p >= highest_patch)
{
installed.ensure_minor_version_link(preview)?;
}
if let Err(e) = installed.ensure_dylib_patched() {
e.warn_user(&installed);
}
@@ -340,6 +366,14 @@ impl PythonInstallationKey {
format!("{}.{}.{}", self.major, self.minor, self.patch)
}
pub fn major(&self) -> u8 {
self.major
}
pub fn minor(&self) -> u8 {
self.minor
}
pub fn arch(&self) -> &Arch {
&self.arch
}
@@ -490,3 +524,112 @@ impl Ord for PythonInstallationKey {
.then_with(|| self.variant.cmp(&other.variant).reverse())
}
}
/// A view into a [`PythonInstallationKey`] that excludes the patch and prerelease versions.
#[derive(Clone, Eq, Ord, PartialOrd, RefCast)]
#[repr(transparent)]
pub struct PythonInstallationMinorVersionKey(PythonInstallationKey);
impl PythonInstallationMinorVersionKey {
/// Cast a `&PythonInstallationKey` to a `&PythonInstallationMinorVersionKey` using ref-cast.
#[inline]
pub fn ref_cast(key: &PythonInstallationKey) -> &Self {
RefCast::ref_cast(key)
}
/// Takes an [`IntoIterator`] of [`ManagedPythonInstallation`]s and returns an [`FxHashMap`] from
/// [`PythonInstallationMinorVersionKey`] to the installation with highest [`PythonInstallationKey`]
/// for that minor version key.
#[inline]
pub fn highest_installations_by_minor_version_key<'a, I>(
installations: I,
) -> IndexMap<Self, ManagedPythonInstallation>
where
I: IntoIterator<Item = &'a ManagedPythonInstallation>,
{
let mut minor_versions = IndexMap::default();
for installation in installations {
minor_versions
.entry(installation.minor_version_key().clone())
.and_modify(|high_installation: &mut ManagedPythonInstallation| {
if installation.key() >= high_installation.key() {
*high_installation = installation.clone();
}
})
.or_insert_with(|| installation.clone());
}
minor_versions
}
}
impl fmt::Display for PythonInstallationMinorVersionKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Display every field on the wrapped key except the patch
// and prerelease (with special formatting for the variant).
let variant = match self.0.variant {
PythonVariant::Default => String::new(),
PythonVariant::Freethreaded => format!("+{}", self.0.variant),
};
write!(
f,
"{}-{}.{}{}-{}-{}-{}",
self.0.implementation,
self.0.major,
self.0.minor,
variant,
self.0.os,
self.0.arch,
self.0.libc,
)
}
}
impl fmt::Debug for PythonInstallationMinorVersionKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Display every field on the wrapped key except the patch
// and prerelease.
f.debug_struct("PythonInstallationMinorVersionKey")
.field("implementation", &self.0.implementation)
.field("major", &self.0.major)
.field("minor", &self.0.minor)
.field("variant", &self.0.variant)
.field("os", &self.0.os)
.field("arch", &self.0.arch)
.field("libc", &self.0.libc)
.finish()
}
}
impl PartialEq for PythonInstallationMinorVersionKey {
fn eq(&self, other: &Self) -> bool {
// Compare every field on the wrapped key except the patch
// and prerelease.
self.0.implementation == other.0.implementation
&& self.0.major == other.0.major
&& self.0.minor == other.0.minor
&& self.0.os == other.0.os
&& self.0.arch == other.0.arch
&& self.0.libc == other.0.libc
&& self.0.variant == other.0.variant
}
}
impl Hash for PythonInstallationMinorVersionKey {
fn hash<H: Hasher>(&self, state: &mut H) {
// Hash every field on the wrapped key except the patch
// and prerelease.
self.0.implementation.hash(state);
self.0.major.hash(state);
self.0.minor.hash(state);
self.0.os.hash(state);
self.0.arch.hash(state);
self.0.libc.hash(state);
self.0.variant.hash(state);
}
}
impl From<PythonInstallationKey> for PythonInstallationMinorVersionKey {
fn from(key: PythonInstallationKey) -> Self {
PythonInstallationMinorVersionKey(key)
}
}
crates/uv-python/src/interpreter.rs
+50 -2
View File
@@ -26,6 +26,7 @@ use uv_platform_tags::{Tags, TagsError};
use uv_pypi_types::{ResolverMarkerEnvironment, Scheme};
use crate::implementation::LenientImplementationName;
use crate::managed::ManagedPythonInstallations;
use crate::platform::{Arch, Libc, Os};
use crate::pointer_size::PointerSize;
use crate::{
@@ -168,7 +169,7 @@ impl Interpreter {
Ok(path) => path,
Err(err) => {
warn!("Failed to find base Python executable: {err}");
uv_fs::canonicalize_executable(base_executable)?
canonicalize_executable(base_executable)?
}
};
Ok(base_python)
@@ -263,6 +264,21 @@ impl Interpreter {
self.prefix.is_some()
}
/// Returns `true` if this interpreter is managed by uv.
///
/// Returns `false` if we cannot determine the path of the uv managed Python interpreters.
pub fn is_managed(&self) -> bool {
let Ok(installations) = ManagedPythonInstallations::from_settings(None) else {
return false;
};
installations
.find_all()
.into_iter()
.flatten()
.any(|install| install.path() == self.sys_base_prefix)
}
/// Returns `Some` if the environment is externally managed, optionally including an error
/// message from the `EXTERNALLY-MANAGED` file.
///
@@ -483,10 +499,19 @@ impl Interpreter {
/// `python-build-standalone`.
///
/// See: <https://github.com/astral-sh/python-build-standalone/issues/382>
#[cfg(unix)]
pub fn is_standalone(&self) -> bool {
self.standalone
}
/// Returns `true` if an [`Interpreter`] may be a `python-build-standalone` interpreter.
// TODO(john): Replace this approach with patching sysconfig on Windows to
// set `PYTHON_BUILD_STANDALONE=1`.`
#[cfg(windows)]
pub fn is_standalone(&self) -> bool {
self.standalone || (self.is_managed() && self.markers().implementation_name() == "cpython")
}
/// Return the [`Layout`] environment used to install wheels into this interpreter.
pub fn layout(&self) -> Layout {
Layout {
@@ -608,6 +633,29 @@ impl Interpreter {
}
}
/// Calls `fs_err::canonicalize` on Unix. On Windows, avoids attempting to resolve symlinks
/// but will resolve junctions if they are part of a trampoline target.
pub fn canonicalize_executable(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
let path = path.as_ref();
debug_assert!(
path.is_absolute(),
"path must be absolute: {}",
path.display()
);
#[cfg(windows)]
{
if let Ok(Some(launcher)) = uv_trampoline_builder::Launcher::try_from_path(path) {
Ok(dunce::canonicalize(launcher.python_path)?)
} else {
Ok(path.to_path_buf())
}
}
#[cfg(unix)]
fs_err::canonicalize(path)
}
/// The `EXTERNALLY-MANAGED` file in a Python installation.
///
/// See: <https://packaging.python.org/en/latest/specifications/externally-managed-environments/>
@@ -935,7 +983,7 @@ impl InterpreterInfo {
// We check the timestamp of the canonicalized executable to check if an underlying
// interpreter has been modified.
let modified = uv_fs::canonicalize_executable(&absolute)
let modified = canonicalize_executable(&absolute)
.and_then(Timestamp::from_path)
.map_err(|err| {
if err.kind() == io::ErrorKind::NotFound {
crates/uv-python/src/lib.rs
+91 -3
View File
@@ -11,9 +11,13 @@ pub use crate::discovery::{
};
pub use crate::downloads::PlatformRequest;
pub use crate::environment::{InvalidEnvironmentKind, PythonEnvironment};
pub use crate::implementation::ImplementationName;
pub use crate::installation::{PythonInstallation, PythonInstallationKey};
pub use crate::interpreter::{BrokenSymlink, Error as InterpreterError, Interpreter};
pub use crate::implementation::{ImplementationName, LenientImplementationName};
pub use crate::installation::{
PythonInstallation, PythonInstallationKey, PythonInstallationMinorVersionKey,
};
pub use crate::interpreter::{
BrokenSymlink, Error as InterpreterError, Interpreter, canonicalize_executable,
};
pub use crate::pointer_size::PointerSize;
pub use crate::prefix::Prefix;
pub use crate::python_version::PythonVersion;
@@ -115,6 +119,7 @@ mod tests {
use indoc::{formatdoc, indoc};
use temp_env::with_vars;
use test_log::test;
use uv_configuration::PreviewMode;
use uv_static::EnvVars;
use uv_cache::Cache;
@@ -447,6 +452,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
});
assert!(
@@ -461,6 +467,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
});
assert!(
@@ -485,6 +492,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
});
assert!(
@@ -506,6 +514,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
})??;
assert!(
@@ -567,6 +576,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
})??;
assert!(
@@ -598,6 +608,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
});
assert!(
@@ -634,6 +645,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::default(),
&context.cache,
PreviewMode::Disabled,
)
})??;
assert!(
@@ -665,6 +677,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -686,6 +699,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -711,6 +725,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -736,6 +751,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -758,6 +774,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -791,6 +808,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -824,6 +842,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -845,6 +864,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -866,6 +886,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -899,6 +920,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -935,6 +957,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert!(
@@ -965,6 +988,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert!(
@@ -999,6 +1023,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1024,6 +1049,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1050,6 +1076,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1074,6 +1101,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)?;
@@ -1095,6 +1123,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1117,6 +1146,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1149,6 +1179,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1169,6 +1200,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1195,6 +1227,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -1212,6 +1245,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -1240,6 +1274,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1277,6 +1312,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1304,6 +1340,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1328,6 +1365,7 @@ mod tests {
EnvironmentPreference::ExplicitSystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1352,6 +1390,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1376,6 +1415,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1413,6 +1453,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1440,6 +1481,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1456,6 +1498,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1472,6 +1515,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1493,6 +1537,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1509,6 +1554,7 @@ mod tests {
EnvironmentPreference::OnlySystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)?;
@@ -1530,6 +1576,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1544,6 +1591,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1557,6 +1605,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1585,6 +1634,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1600,6 +1650,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1629,6 +1680,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1644,6 +1696,7 @@ mod tests {
EnvironmentPreference::ExplicitSystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1659,6 +1712,7 @@ mod tests {
EnvironmentPreference::OnlyVirtual,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1674,6 +1728,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1697,6 +1752,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1711,6 +1767,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1734,6 +1791,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1753,6 +1811,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
},
)??;
@@ -1781,6 +1840,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1802,6 +1862,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1831,6 +1892,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1846,6 +1908,7 @@ mod tests {
EnvironmentPreference::ExplicitSystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1872,6 +1935,7 @@ mod tests {
EnvironmentPreference::ExplicitSystem,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -1896,6 +1960,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -1912,6 +1977,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1926,6 +1992,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1951,6 +2018,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1965,6 +2033,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -1990,6 +2059,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2016,6 +2086,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2042,6 +2113,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2068,6 +2140,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2094,6 +2167,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2121,6 +2195,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})?;
assert!(
@@ -2142,6 +2217,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2156,6 +2232,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2181,6 +2258,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2195,6 +2273,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
assert_eq!(
@@ -2232,6 +2311,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2249,6 +2329,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2290,6 +2371,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2307,6 +2389,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2343,6 +2426,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2365,6 +2449,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2387,6 +2472,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})
.unwrap()
@@ -2425,6 +2511,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
@@ -2477,6 +2564,7 @@ mod tests {
EnvironmentPreference::Any,
PythonPreference::OnlySystem,
&context.cache,
PreviewMode::Disabled,
)
})??;
crates/uv-python/src/managed.rs
+281 -58
View File
@@ -2,6 +2,8 @@ use core::fmt;
use std::cmp::Reverse;
use std::ffi::OsStr;
use std::io::{self, Write};
#[cfg(windows)]
use std::os::windows::fs::MetadataExt;
use std::path::{Path, PathBuf};
use std::str::FromStr;
@@ -10,8 +12,11 @@ use itertools::Itertools;
use same_file::is_same_file;
use thiserror::Error;
use tracing::{debug, warn};
use uv_configuration::PreviewMode;
#[cfg(windows)]
use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT;
use uv_fs::{LockedFile, Simplified, symlink_or_copy_file};
use uv_fs::{LockedFile, Simplified, replace_symlink, symlink_or_copy_file};
use uv_state::{StateBucket, StateStore};
use uv_static::EnvVars;
use uv_trampoline_builder::{Launcher, windows_python_launcher};
@@ -25,7 +30,9 @@ use crate::libc::LibcDetectionError;
use crate::platform::Error as PlatformError;
use crate::platform::{Arch, Libc, Os};
use crate::python_version::PythonVersion;
use crate::{PythonRequest, PythonVariant, macos_dylib, sysconfig};
use crate::{
PythonInstallationMinorVersionKey, PythonRequest, PythonVariant, macos_dylib, sysconfig,
};
#[derive(Error, Debug)]
pub enum Error {
@@ -51,6 +58,8 @@ pub enum Error {
},
#[error("Missing expected Python executable at {}", _0.user_display())]
MissingExecutable(PathBuf),
#[error("Missing expected target directory for Python minor version link at {}", _0.user_display())]
MissingPythonMinorVersionLinkTargetDirectory(PathBuf),
#[error("Failed to create canonical Python executable at {} from {}", to.user_display(), from.user_display())]
CanonicalizeExecutable {
from: PathBuf,
@@ -65,6 +74,13 @@ pub enum Error {
#[source]
err: io::Error,
},
#[error("Failed to create Python minor version link directory at {} from {}", to.user_display(), from.user_display())]
PythonMinorVersionLinkDirectory {
from: PathBuf,
to: PathBuf,
#[source]
err: io::Error,
},
#[error("Failed to create directory for Python executable link at {}", to.user_display())]
ExecutableDirectory {
to: PathBuf,
@@ -339,7 +355,7 @@ impl ManagedPythonInstallation {
/// The path to this managed installation's Python executable.
///
/// If the installation has multiple execututables i.e., `python`, `python3`, etc., this will
/// If the installation has multiple executables i.e., `python`, `python3`, etc., this will
/// return the _canonical_ executable name which the other names link to. On Unix, this is
/// `python{major}.{minor}{variant}` and on Windows, this is `python{exe}`.
///
@@ -383,13 +399,11 @@ impl ManagedPythonInstallation {
exe = std::env::consts::EXE_SUFFIX
);
let executable = if cfg!(unix) || *self.implementation() == ImplementationName::GraalPy {
self.python_dir().join("bin").join(name)
} else if cfg!(windows) {
self.python_dir().join(name)
} else {
unimplemented!("Only Windows and Unix systems are supported.")
};
let executable = executable_path_from_base(
self.python_dir().as_path(),
&name,
&LenientImplementationName::from(*self.implementation()),
);
// Workaround for python-build-standalone v20241016 which is missing the standard
// `python.exe` executable in free-threaded distributions on Windows.
@@ -442,6 +456,10 @@ impl ManagedPythonInstallation {
&self.key
}
pub fn minor_version_key(&self) -> &PythonInstallationMinorVersionKey {
PythonInstallationMinorVersionKey::ref_cast(&self.key)
}
pub fn satisfies(&self, request: &PythonRequest) -> bool {
match request {
PythonRequest::File(path) => self.executable(false) == *path,
@@ -503,6 +521,30 @@ impl ManagedPythonInstallation {
Ok(())
}
/// Ensure the environment contains the symlink directory (or junction on Windows)
/// pointing to the patch directory for this minor version.
pub fn ensure_minor_version_link(&self, preview: PreviewMode) -> Result<(), Error> {
if let Some(minor_version_link) = PythonMinorVersionLink::from_installation(self, preview) {
minor_version_link.create_directory()?;
}
Ok(())
}
/// If the environment contains a symlink directory (or junction on Windows),
/// update it to the latest patch directory for this minor version.
///
/// Unlike [`ensure_minor_version_link`], will not create a new symlink directory
/// if one doesn't already exist,
pub fn update_minor_version_link(&self, preview: PreviewMode) -> Result<(), Error> {
if let Some(minor_version_link) = PythonMinorVersionLink::from_installation(self, preview) {
if !minor_version_link.exists() {
return Ok(());
}
minor_version_link.create_directory()?;
}
Ok(())
}
/// Ensure the environment is marked as externally managed with the
/// standard `EXTERNALLY-MANAGED` file.
pub fn ensure_externally_managed(&self) -> Result<(), Error> {
@@ -567,54 +609,8 @@ impl ManagedPythonInstallation {
Ok(())
}
/// Create a link to the managed Python executable.
///
/// If the file already exists at the target path, an error will be returned.
pub fn create_bin_link(&self, target: &Path) -> Result<(), Error> {
let python = self.executable(false);
let bin = target.parent().ok_or(Error::NoExecutableDirectory)?;
fs_err::create_dir_all(bin).map_err(|err| Error::ExecutableDirectory {
to: bin.to_path_buf(),
err,
})?;
if cfg!(unix) {
// Note this will never copy on Unix — we use it here to allow compilation on Windows
match symlink_or_copy_file(&python, target) {
Ok(()) => Ok(()),
Err(err) if err.kind() == io::ErrorKind::NotFound => {
Err(Error::MissingExecutable(python.clone()))
}
Err(err) => Err(Error::LinkExecutable {
from: python,
to: target.to_path_buf(),
err,
}),
}
} else if cfg!(windows) {
// TODO(zanieb): Install GUI launchers as well
let launcher = windows_python_launcher(&python, false)?;
// OK to use `std::fs` here, `fs_err` does not support `File::create_new` and we attach
// error context anyway
#[allow(clippy::disallowed_types)]
{
std::fs::File::create_new(target)
.and_then(|mut file| file.write_all(launcher.as_ref()))
.map_err(|err| Error::LinkExecutable {
from: python,
to: target.to_path_buf(),
err,
})
}
} else {
unimplemented!("Only Windows and Unix systems are supported.")
}
}
/// Returns `true` if the path is a link to this installation's binary, e.g., as created by
/// [`ManagedPythonInstallation::create_bin_link`].
/// [`create_bin_link`].
pub fn is_bin_link(&self, path: &Path) -> bool {
if cfg!(unix) {
is_same_file(path, self.executable(false)).unwrap_or_default()
@@ -625,7 +621,11 @@ impl ManagedPythonInstallation {
if !matches!(launcher.kind, uv_trampoline_builder::LauncherKind::Python) {
return false;
}
launcher.python_path == self.executable(false)
// We canonicalize the target path of the launcher in case it includes a minor version
// junction directory. If canonicalization fails, we check against the launcher path
// directly.
dunce::canonicalize(&launcher.python_path).unwrap_or(launcher.python_path)
== self.executable(false)
} else {
unreachable!("Only Windows and Unix are supported")
}
@@ -669,6 +669,229 @@ impl ManagedPythonInstallation {
}
}
/// A representation of a minor version symlink directory (or junction on Windows)
/// linking to the home directory of a Python installation.
#[derive(Clone, Debug)]
pub struct PythonMinorVersionLink {
/// The symlink directory (or junction on Windows).
pub symlink_directory: PathBuf,
/// The full path to the executable including the symlink directory
/// (or junction on Windows).
pub symlink_executable: PathBuf,
/// The target directory for the symlink. This is the home directory for
/// a Python installation.
pub target_directory: PathBuf,
}
impl PythonMinorVersionLink {
/// Attempt to derive a path from an executable path that substitutes a minor
/// version symlink directory (or junction on Windows) for the patch version
/// directory.
///
/// The implementation is expected to be CPython and, on Unix, the base Python is
/// expected to be in `<home>/bin/` on Unix. If either condition isn't true,
/// return [`None`].
///
/// # Examples
///
/// ## Unix
/// For a Python 3.10.8 installation in `/path/to/uv/python/cpython-3.10.8-macos-aarch64-none/bin/python3.10`,
/// the symlink directory would be `/path/to/uv/python/cpython-3.10-macos-aarch64-none` and the executable path including the
/// symlink directory would be `/path/to/uv/python/cpython-3.10-macos-aarch64-none/bin/python3.10`.
///
/// ## Windows
/// For a Python 3.10.8 installation in `C:\path\to\uv\python\cpython-3.10.8-windows-x86_64-none\python.exe`,
/// the junction would be `C:\path\to\uv\python\cpython-3.10-windows-x86_64-none` and the executable path including the
/// junction would be `C:\path\to\uv\python\cpython-3.10-windows-x86_64-none\python.exe`.
pub fn from_executable(
executable: &Path,
key: &PythonInstallationKey,
preview: PreviewMode,
) -> Option<Self> {
let implementation = key.implementation();
if !matches!(
implementation,
LenientImplementationName::Known(ImplementationName::CPython)
) {
// We don't currently support transparent upgrades for PyPy or GraalPy.
return None;
}
let executable_name = executable
.file_name()
.expect("Executable file name should exist");
let symlink_directory_name = PythonInstallationMinorVersionKey::ref_cast(key).to_string();
let parent = executable
.parent()
.expect("Executable should have parent directory");
// The home directory of the Python installation
let target_directory = if cfg!(unix) {
if parent
.components()
.next_back()
.is_some_and(|c| c.as_os_str() == "bin")
{
parent.parent()?.to_path_buf()
} else {
return None;
}
} else if cfg!(windows) {
parent.to_path_buf()
} else {
unimplemented!("Only Windows and Unix systems are supported.")
};
let symlink_directory = target_directory.with_file_name(symlink_directory_name);
// If this would create a circular link, return `None`.
if target_directory == symlink_directory {
return None;
}
// The full executable path including the symlink directory (or junction).
let symlink_executable = executable_path_from_base(
symlink_directory.as_path(),
&executable_name.to_string_lossy(),
implementation,
);
let minor_version_link = Self {
symlink_directory,
symlink_executable,
target_directory,
};
// If preview mode is disabled, still return a `MinorVersionSymlink` for
// existing symlinks, allowing continued operations without the `--preview`
// flag after initial symlink directory installation.
if preview.is_disabled() && !minor_version_link.exists() {
return None;
}
Some(minor_version_link)
}
pub fn from_installation(
installation: &ManagedPythonInstallation,
preview: PreviewMode,
) -> Option<Self> {
PythonMinorVersionLink::from_executable(
installation.executable(false).as_path(),
installation.key(),
preview,
)
}
pub fn create_directory(&self) -> Result<(), Error> {
match replace_symlink(
self.target_directory.as_path(),
self.symlink_directory.as_path(),
) {
Ok(()) => {
debug!(
"Created link {} -> {}",
&self.symlink_directory.user_display(),
&self.target_directory.user_display(),
);
}
Err(err) if err.kind() == io::ErrorKind::NotFound => {
return Err(Error::MissingPythonMinorVersionLinkTargetDirectory(
self.target_directory.clone(),
));
}
Err(err) if err.kind() == io::ErrorKind::AlreadyExists => {}
Err(err) => {
return Err(Error::PythonMinorVersionLinkDirectory {
from: self.symlink_directory.clone(),
to: self.target_directory.clone(),
err,
});
}
}
Ok(())
}
pub fn exists(&self) -> bool {
#[cfg(unix)]
{
self.symlink_directory
.symlink_metadata()
.map(|metadata| metadata.file_type().is_symlink())
.unwrap_or(false)
}
#[cfg(windows)]
{
self.symlink_directory
.symlink_metadata()
.is_ok_and(|metadata| {
// Check that this is a reparse point, which indicates this
// is a symlink or junction.
(metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT) != 0
})
}
}
}
/// Derive the full path to an executable from the given base path and executable
/// name. On Unix, this is, e.g., `<base>/bin/python3.10`. On Windows, this is,
/// e.g., `<base>\python.exe`.
fn executable_path_from_base(
base: &Path,
executable_name: &str,
implementation: &LenientImplementationName,
) -> PathBuf {
if cfg!(unix)
|| matches!(
implementation,
&LenientImplementationName::Known(ImplementationName::GraalPy)
)
{
base.join("bin").join(executable_name)
} else if cfg!(windows) {
base.join(executable_name)
} else {
unimplemented!("Only Windows and Unix systems are supported.")
}
}
/// Create a link to a managed Python executable.
///
/// If the file already exists at the link path, an error will be returned.
pub fn create_link_to_executable(link: &Path, executable: PathBuf) -> Result<(), Error> {
let link_parent = link.parent().ok_or(Error::NoExecutableDirectory)?;
fs_err::create_dir_all(link_parent).map_err(|err| Error::ExecutableDirectory {
to: link_parent.to_path_buf(),
err,
})?;
if cfg!(unix) {
// Note this will never copy on Unix — we use it here to allow compilation on Windows
match symlink_or_copy_file(&executable, link) {
Ok(()) => Ok(()),
Err(err) if err.kind() == io::ErrorKind::NotFound => {
Err(Error::MissingExecutable(executable.clone()))
}
Err(err) => Err(Error::LinkExecutable {
from: executable,
to: link.to_path_buf(),
err,
}),
}
} else if cfg!(windows) {
// TODO(zanieb): Install GUI launchers as well
let launcher = windows_python_launcher(&executable, false)?;
// OK to use `std::fs` here, `fs_err` does not support `File::create_new` and we attach
// error context anyway
#[allow(clippy::disallowed_types)]
{
std::fs::File::create_new(link)
.and_then(|mut file| file.write_all(launcher.as_ref()))
.map_err(|err| Error::LinkExecutable {
from: executable,
to: link.to_path_buf(),
err,
})
}
} else {
unimplemented!("Only Windows and Unix systems are supported.")
}
}
// TODO(zanieb): Only used in tests now.
/// Generate a platform portion of a key from the environment.
pub fn platform_key_from_env() -> Result<String, Error> {
crates/uv-python/src/python_version.rs
+1 -1
View File
@@ -5,7 +5,7 @@ use std::str::FromStr;
use uv_pep440::Version;
use uv_pep508::{MarkerEnvironment, StringVersion};
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct PythonVersion(StringVersion);
impl From<StringVersion> for PythonVersion {