Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Allow `--constraints` and `--overrides` in `uvx` (#10207) 

## Summary

Closes https://github.com/astral-sh/uv/issues/9813.
This commit is contained in:
Charlie Marsh 2025-03-03 18:18:48 -08:00 committed by GitHub
parent 04db70662d
commit b460e51e19
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 245 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
crates/uv-cli/src/lib.rs
View File

@ -3956,6 +3956,28 @@ pub struct ToolRunArgs {
#[arg(long, value_delimiter = ',', value_parser = parse_maybe_file_path)]
pub with_requirements: Vec<Maybe<PathBuf>>,
/// Constrain versions using the given requirements files.
///
/// Constraints files are `requirements.txt`-like files that only control the _version_ of a
/// requirement that's installed. However, including a package in a constraints file will _not_
/// trigger the installation of that package.
///
/// This is equivalent to pip's `--constraint` option.
#[arg(long, short, alias = "constraint", env = EnvVars::UV_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
pub constraints: Vec<Maybe<PathBuf>>,
/// Override versions using the given requirements files.
///
/// Overrides files are `requirements.txt`-like files that force a specific version of a
/// requirement to be installed, regardless of the requirements declared by any constituent
/// package, and regardless of whether this would be considered an invalid resolution.
///
/// While constraints are _additive_, in that they're combined with the requirements of the
/// constituent packages, overrides are _absolute_, in that they completely replace the
/// requirements of the constituent packages.
#[arg(long, alias = "override", env = EnvVars::UV_OVERRIDE, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
pub overrides: Vec<Maybe<PathBuf>>,
/// Run the tool in an isolated virtual environment, ignoring any already-installed tools.
#[arg(long)]
pub isolated: bool,

112
crates/uv/src/commands/tool/run.rs
View File

@ -15,7 +15,9 @@ use uv_cache_info::Timestamp;
use uv_cli::ExternalCommand;
use uv_client::BaseClientBuilder;
use uv_configuration::{Concurrency, PreviewMode};
use uv_distribution_types::{Name, UnresolvedRequirement, UnresolvedRequirementSpecification};
use uv_distribution_types::{
Name, NameRequirementSpecification, UnresolvedRequirement, UnresolvedRequirementSpecification,
};
use uv_installer::{SatisfiesResult, SitePackages};
use uv_normalize::PackageName;
use uv_pep440::{VersionSpecifier, VersionSpecifiers};
@ -27,7 +29,7 @@ use uv_python::{
PythonPreference, PythonRequest,
};
use uv_requirements::{RequirementsSource, RequirementsSpecification};
use uv_settings::PythonInstallMirrors;
use uv_settings::{PythonInstallMirrors, ResolverInstallerOptions, ToolOptions};
use uv_static::EnvVars;
use uv_tool::{entrypoint_paths, InstalledTools};
use uv_warnings::warn_user;
@ -72,9 +74,12 @@ pub(crate) async fn run(
command: Option<ExternalCommand>,
from: Option<String>,
with: &[RequirementsSource],
constraints: &[RequirementsSource],
overrides: &[RequirementsSource],
show_resolution: bool,
python: Option<String>,
install_mirrors: PythonInstallMirrors,
options: ResolverInstallerOptions,
settings: ResolverInstallerSettings,
network_settings: NetworkSettings,
invocation_source: ToolRunCommand,
@ -116,9 +121,12 @@ pub(crate) async fn run(
let result = get_or_create_environment(
&request,
with,
constraints,
overrides,
show_resolution,
python.as_deref(),
install_mirrors,
options,
&settings,
&network_settings,
isolated,
@ -446,9 +454,12 @@ impl std::fmt::Display for ToolRequirement {
async fn get_or_create_environment(
request: &ToolRequest<'_>,
with: &[RequirementsSource],
constraints: &[RequirementsSource],
overrides: &[RequirementsSource],
show_resolution: bool,
python: Option<&str>,
install_mirrors: PythonInstallMirrors,
options: ResolverInstallerOptions,
settings: &ResolverInstallerSettings,
network_settings: &NetworkSettings,
isolated: bool,
@ -631,13 +642,9 @@ async fn get_or_create_environment(
};
// Read the `--with` requirements.
let spec = {
let client_builder = BaseClientBuilder::new()
.connectivity(network_settings.connectivity)
.native_tls(network_settings.native_tls)
.allow_insecure_host(network_settings.allow_insecure_host.clone());
RequirementsSpecification::from_simple_sources(with, &client_builder).await?
};
let spec =
RequirementsSpecification::from_sources(with, constraints, overrides, &client_builder)
.await?;
// Resolve the `--from` and `--with` requirements.
let requirements = {
@ -663,6 +670,28 @@ async fn get_or_create_environment(
requirements
};
// Resolve the constraints.
let constraints = spec
.constraints
.clone()
.into_iter()
.map(|constraint| constraint.requirement)
.collect::<Vec<_>>();
// Resolve the overrides.
let overrides = resolve_names(
spec.overrides.clone(),
&interpreter,
settings,
network_settings,
&state,
concurrency,
cache,
printer,
preview,
)
.await?;
// Check if the tool is already installed in a compatible environment.
if !isolated && !request.is_latest() {
let installed_tools = InstalledTools::from_settings()?.init()?;
@ -676,27 +705,48 @@ async fn get_or_create_environment(
python_request.satisfied(environment.interpreter(), cache)
})
});
// Check if the installed packages meet the requirements.
if let Some(environment) = existing_environment {
// Check if the installed packages meet the requirements.
let site_packages = SitePackages::from_environment(&environment)?;
if let Some(tool_receipt) = installed_tools
.get_tool_receipt(&requirement.name)
.ok()
.flatten()
.filter(|receipt| ToolOptions::from(options) == *receipt.options())
{
if overrides.is_empty() {
// Check if the installed packages meet the requirements.
let site_packages = SitePackages::from_environment(&environment)?;
let requirements = requirements
.iter()
.cloned()
.map(UnresolvedRequirementSpecification::from)
.collect::<Vec<_>>();
let constraints = [];
let requirements = requirements
.iter()
.cloned()
.map(UnresolvedRequirementSpecification::from)
.collect::<Vec<_>>();
let constraints = [];
if matches!(
site_packages.satisfies(
&requirements,
&constraints,
&interpreter.resolver_marker_environment()
),
Ok(SatisfiesResult::Fresh { .. })
) {
debug!("Using existing tool `{}`", requirement.name);
return Ok((from, environment));
if matches!(
site_packages.satisfies(
&requirements,
&constraints,
&interpreter.resolver_marker_environment()
),
Ok(SatisfiesResult::Fresh { .. })
) {
debug!("Using existing tool `{}`", requirement.name);
return Ok((from, environment));
}
} else {
// Check if the installed packages match the requirements.
// TODO(charlie): Support overrides in `SitePackages::satisfies`.
if requirements == tool_receipt.requirements()
&& constraints == tool_receipt.constraints()
&& overrides == tool_receipt.overrides()
{
debug!("Using existing tool `{}`", requirement.name);
return Ok((from, environment));
}
}
}
}
}
@ -708,6 +758,14 @@ async fn get_or_create_environment(
.into_iter()
.map(UnresolvedRequirementSpecification::from)
.collect(),
constraints: constraints
.into_iter()
.map(NameRequirementSpecification::from)
.collect(),
overrides: overrides
.into_iter()
.map(UnresolvedRequirementSpecification::from)
.collect(),
..spec
});

48
crates/uv/src/lib.rs
View File

@ -968,30 +968,46 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
.combine(Refresh::from(args.settings.upgrade.clone())),
);
let mut requirements = Vec::with_capacity(
args.with.len() + args.with_editable.len() + args.with_requirements.len(),
);
for package in args.with {
requirements.push(RequirementsSource::from_with_package(package)?);
}
requirements.extend(
args.with_editable
.into_iter()
.map(RequirementsSource::Editable),
);
requirements.extend(
args.with_requirements
.into_iter()
.map(RequirementsSource::from_requirements_file),
);
let requirements = {
let mut requirements = Vec::with_capacity(
args.with.len() + args.with_editable.len() + args.with_requirements.len(),
);
for package in args.with {
requirements.push(RequirementsSource::from_with_package(package)?);
}
requirements.extend(
args.with_editable
.into_iter()
.map(RequirementsSource::Editable),
);
requirements.extend(
args.with_requirements
.into_iter()
.map(RequirementsSource::from_requirements_file),
);
requirements
};
let constraints = args
.constraints
.into_iter()
.map(RequirementsSource::from_constraints_txt)
.collect::<Vec<_>>();
let overrides = args
.overrides
.into_iter()
.map(RequirementsSource::from_overrides_txt)
.collect::<Vec<_>>();
Box::pin(commands::tool_run(
args.command,
args.from,
&requirements,
&constraints,
&overrides,
args.show_resolution || globals.verbose > 0,
args.python,
args.install_mirrors,
args.options,
args.settings,
globals.network_settings,
invocation_source,

35
crates/uv/src/settings.rs
View File

@ -441,13 +441,16 @@ pub(crate) struct ToolRunSettings {
pub(crate) command: Option<ExternalCommand>,
pub(crate) from: Option<String>,
pub(crate) with: Vec<String>,
pub(crate) with_editable: Vec<String>,
pub(crate) with_requirements: Vec<PathBuf>,
pub(crate) with_editable: Vec<String>,
pub(crate) constraints: Vec<PathBuf>,
pub(crate) overrides: Vec<PathBuf>,
pub(crate) isolated: bool,
pub(crate) show_resolution: bool,
pub(crate) python: Option<String>,
pub(crate) install_mirrors: PythonInstallMirrors,
pub(crate) refresh: Refresh,
pub(crate) options: ResolverInstallerOptions,
pub(crate) settings: ResolverInstallerSettings,
}
@ -465,6 +468,8 @@ impl ToolRunSettings {
with,
with_editable,
with_requirements,
constraints,
overrides,
isolated,
show_resolution,
installer,
@ -492,11 +497,21 @@ impl ToolRunSettings {
}
}
let options = resolver_installer_options(installer, build).combine(
filesystem
.clone()
.map(FilesystemOptions::into_options)
.map(|options| options.top_level)
.unwrap_or_default(),
);
let install_mirrors = filesystem
.clone()
.map(|fs| fs.install_mirrors.clone())
.map(FilesystemOptions::into_options)
.map(|options| options.install_mirrors)
.unwrap_or_default();
let settings = ResolverInstallerSettings::from(options.clone());
Self {
command,
from,
@ -512,14 +527,20 @@ impl ToolRunSettings {
.into_iter()
.filter_map(Maybe::into_option)
.collect(),
constraints: constraints
.into_iter()
.filter_map(Maybe::into_option)
.collect(),
overrides: overrides
.into_iter()
.filter_map(Maybe::into_option)
.collect(),
isolated,
show_resolution,
python: python.and_then(Maybe::into_option),
refresh: Refresh::from(refresh),
settings: ResolverInstallerSettings::combine(
resolver_installer_options(installer, build),
filesystem,
),
settings,
options,
install_mirrors,
}
}

64
crates/uv/tests/it/tool_run.rs
View File

@ -189,6 +189,70 @@ fn tool_run_from_version() {
"###);
}
#[test]
fn tool_run_constraints() {
let context = TestContext::new("3.12");
let tool_dir = context.temp_dir.child("tools");
let bin_dir = context.temp_dir.child("bin");
let constraints_txt = context.temp_dir.child("constraints.txt");
constraints_txt.write_str("pluggy<1.4.0").unwrap();
uv_snapshot!(context.filters(), context.tool_run()
.arg("--constraints")
.arg("constraints.txt")
.arg("pytest")
.arg("--version")
.env(EnvVars::UV_TOOL_DIR, tool_dir.as_os_str())
.env(EnvVars::XDG_BIN_HOME, bin_dir.as_os_str()), @r###"
success: true
exit_code: 0
----- stdout -----
pytest 8.0.2
----- stderr -----
Resolved 4 packages in [TIME]
Prepared 4 packages in [TIME]
Installed 4 packages in [TIME]
+ iniconfig==2.0.0
+ packaging==24.0
+ pluggy==1.3.0
+ pytest==8.0.2
"###);
}
#[test]
fn tool_run_overrides() {
let context = TestContext::new("3.12");
let tool_dir = context.temp_dir.child("tools");
let bin_dir = context.temp_dir.child("bin");
let overrides_txt = context.temp_dir.child("overrides.txt");
overrides_txt.write_str("pluggy<1.4.0").unwrap();
uv_snapshot!(context.filters(), context.tool_run()
.arg("--overrides")
.arg("overrides.txt")
.arg("pytest")
.arg("--version")
.env(EnvVars::UV_TOOL_DIR, tool_dir.as_os_str())
.env(EnvVars::XDG_BIN_HOME, bin_dir.as_os_str()), @r###"
success: true
exit_code: 0
----- stdout -----
pytest 8.1.1
----- stderr -----
Resolved 4 packages in [TIME]
Prepared 4 packages in [TIME]
Installed 4 packages in [TIME]
+ iniconfig==2.0.0
+ packaging==24.0
+ pluggy==1.3.0
+ pytest==8.1.1
"###);
}
#[test]
fn tool_run_suggest_valid_commands() {
let context = TestContext::new("3.12").with_filtered_exe_suffix();

14
docs/reference/cli.md
View File

@ -3150,6 +3150,13 @@ uv tool run [OPTIONS] [COMMAND]
<p>May also be set with the <code>UV_CONFIG_FILE</code> environment variable.</p>
</dd><dt id="uv-tool-run--config-setting"><a href="#uv-tool-run--config-setting"><code>--config-setting</code></a>, <code>-C</code> <i>config-setting</i></dt><dd><p>Settings to pass to the PEP 517 build backend, specified as <code>KEY=VALUE</code> pairs</p>
</dd><dt id="uv-tool-run--constraints"><a href="#uv-tool-run--constraints"><code>--constraints</code></a>, <code>-c</code> <i>constraints</i></dt><dd><p>Constrain versions using the given requirements files.</p>
<p>Constraints files are <code>requirements.txt</code>-like files that only control the <em>version</em> of a requirement that&#8217;s installed. However, including a package in a constraints file will <em>not</em> trigger the installation of that package.</p>
<p>This is equivalent to pip&#8217;s <code>--constraint</code> option.</p>
<p>May also be set with the <code>UV_CONSTRAINT</code> environment variable.</p>
</dd><dt id="uv-tool-run--default-index"><a href="#uv-tool-run--default-index"><code>--default-index</code></a> <i>default-index</i></dt><dd><p>The URL of the default package index (by default: &lt;https://pypi.org/simple&gt;).</p>
<p>Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.</p>
@ -3316,6 +3323,13 @@ uv tool run [OPTIONS] [COMMAND]
<p>When disabled, uv will only use locally cached data and locally available files.</p>
<p>May also be set with the <code>UV_OFFLINE</code> environment variable.</p>
</dd><dt id="uv-tool-run--overrides"><a href="#uv-tool-run--overrides"><code>--overrides</code></a> <i>overrides</i></dt><dd><p>Override versions using the given requirements files.</p>
<p>Overrides files are <code>requirements.txt</code>-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.</p>
<p>While constraints are <em>additive</em>, in that they&#8217;re combined with the requirements of the constituent packages, overrides are <em>absolute</em>, in that they completely replace the requirements of the constituent packages.</p>
<p>May also be set with the <code>UV_OVERRIDE</code> environment variable.</p>
</dd><dt id="uv-tool-run--prerelease"><a href="#uv-tool-run--prerelease"><code>--prerelease</code></a> <i>prerelease</i></dt><dd><p>The strategy to use when considering pre-release versions.</p>
<p>By default, uv will accept pre-releases for packages that <em>only</em> publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (<code>if-necessary-or-explicit</code>).</p>