From 43dbdba578179d8e6ced763916b658dcfb9c53c6 Mon Sep 17 00:00:00 2001 From: Noam Teyssier <22600644+noamteyssier@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:50:50 -0700 Subject: [PATCH] feature: shorthand for --with (-w) in uvx and uv tool run (#14530) ## Summary This is a small quality of life feature that adds a shorthand (`-w`) to the `--with` flag for minimizing keystrokes. Pretty minor, but I didn't see any conflicts with `-w` and thought this could be a nice place for it. ```bash # proposed addition (short) uvx -w numpy ipython # original (long) uvx --with numpy ipython ``` ## Test Plan Added testing already in the P.R. - just copied over tests from the `--with` flag --- crates/uv-cli/src/lib.rs | 6 ++-- crates/uv/tests/it/tool_run.rs | 64 ++++++++++++++++++++++++++++++++++ docs/concepts/tools.md | 6 ++++ docs/reference/cli.md | 6 ++-- 4 files changed, 76 insertions(+), 6 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 3e9aba123..39dac54ba 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3045,7 +3045,7 @@ pub struct RunArgs { /// When used in a project, these dependencies will be layered on top of the project environment /// in a separate, ephemeral environment. These dependencies are allowed to conflict with those /// specified by the project. - #[arg(long)] + #[arg(short = 'w', long)] pub with: Vec, /// Run with the given packages installed in editable mode. @@ -4256,7 +4256,7 @@ pub struct ToolRunArgs { pub from: Option, /// Run with the given packages installed. - #[arg(long)] + #[arg(short = 'w', long)] pub with: Vec, /// Run with the given packages installed in editable mode @@ -4371,7 +4371,7 @@ pub struct ToolInstallArgs { pub from: Option, /// Include the following additional requirements. - #[arg(long)] + #[arg(short = 'w', long)] pub with: Vec, /// Include all requirements listed in the given `requirements.txt` files. diff --git a/crates/uv/tests/it/tool_run.rs b/crates/uv/tests/it/tool_run.rs index 153adeb51..fb6287454 100644 --- a/crates/uv/tests/it/tool_run.rs +++ b/crates/uv/tests/it/tool_run.rs @@ -1125,6 +1125,70 @@ fn tool_run_without_output() { "###); } +#[test] +#[cfg(not(windows))] +fn tool_run_csv_with_shorthand() -> anyhow::Result<()> { + let context = TestContext::new("3.12").with_filtered_counts(); + let tool_dir = context.temp_dir.child("tools"); + let bin_dir = context.temp_dir.child("bin"); + + let anyio_local = context.temp_dir.child("src").child("anyio_local"); + copy_dir_all( + context.workspace_root.join("scripts/packages/anyio_local"), + &anyio_local, + )?; + + let black_editable = context.temp_dir.child("src").child("black_editable"); + copy_dir_all( + context + .workspace_root + .join("scripts/packages/black_editable"), + &black_editable, + )?; + + let pyproject_toml = context.temp_dir.child("pyproject.toml"); + pyproject_toml.write_str(indoc! { r#" + [project] + name = "foo" + version = "1.0.0" + requires-python = ">=3.8" + dependencies = ["anyio", "sniffio==1.3.1"] + "# + })?; + + let test_script = context.temp_dir.child("main.py"); + test_script.write_str(indoc! { r" + import sniffio + " + })?; + + // Performs a tool run with a comma-separated `--with` flag. + uv_snapshot!(context.filters(), context.tool_run() + .arg("-w") + .arg("iniconfig,typing-extensions") + .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 [N] packages in [TIME] + Prepared [N] packages in [TIME] + Installed [N] packages in [TIME] + + iniconfig==2.0.0 + + packaging==24.0 + + pluggy==1.4.0 + + pytest==8.1.1 + + typing-extensions==4.10.0 + "###); + + Ok(()) +} + #[test] #[cfg(not(windows))] fn tool_run_csv_with() -> anyhow::Result<()> { diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md index d5069e725..7c5eb9564 100644 --- a/docs/concepts/tools.md +++ b/docs/concepts/tools.md @@ -200,6 +200,12 @@ The `--with` option supports package specifications, so a specific version can b $ uvx --with == ``` +The `-w` shorthand can be used in place of the `--with` option: + +```console +$ uvx -w +``` + If the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index bd828acda..f20bcf7ec 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -246,7 +246,7 @@ used.

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

-
--with with

Run with the given packages installed.

+
--with, -w with

Run with the given packages installed.

When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

--with-editable with-editable

Run with the given packages installed in editable mode.

When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

@@ -1935,7 +1935,7 @@ uv tool run [OPTIONS] [COMMAND]
--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

-
--with with

Run with the given packages installed

+
--with, -w with

Run with the given packages installed

--with-editable with-editable

Run with the given packages installed in editable mode

When used in a project, these dependencies will be layered on top of the uv tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.

--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files

@@ -2104,7 +2104,7 @@ uv tool install [OPTIONS]
--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

-
--with with

Include the following additional requirements

+
--with, -w with

Include the following additional requirements

--with-editable with-editable

Include the given packages in editable mode

--with-requirements with-requirements

Include all requirements listed in the given requirements.txt files