Skip to content

Commit 7e6caa4

Browse files
authored
Support referencing indexes by name via --index and --default-index (#17455)
## Summary Implement #13974. This PR makes `uv ... --index name` attempt to look up the index by name in filesystem configuration (workspace `pyproject.toml` or adjacent `uv.toml` (for project commands), then user config, then system config). The only difference is that the index will be passed with `explicit` and `default` set to `false` for that invocation. Additionally, `uv ... --default-index name` acts in the same way, except the `default` setting is forcibly set to `true`. This will work for `uv add --index name package...` pinning, with the same caveats that already apply when doing `uv add --index name=<location> package...`. Without `--preview-features index-by-name`, named index references will prefer a directory of the same name, it will continue to warn about the potential ambiguity (now with all invocations, not just `uv add`). In case no index or directory of that name exists, the existing error will be emitted. Lastly, if only an index of that name exists, it will be resolved with a preview warning. With `--preview-features index-by-name`, named index references will prefer an index of that name over any directory, but will continue to resolve to directories (with a warning as usual). In case no index or directory of that name exists, a new `index name` focused error will be emitted. There are fundamental quirks with how `--index` and `--default-index` interact with `uv add` which mean this feature doesn't fully work as we would like. Expect some changes before it stabilises. ## Test Plan A number of relevant tests have been added. They're trying to strike a balance between abstraction and simplicity. I found it was easier to keep track of what was actually being tested if you didn't have to dig through a haystack of setup code and snapshot every time you glanced at the tests.
1 parent 298dda4 commit 7e6caa4

12 files changed

Lines changed: 748 additions & 111 deletions

File tree

‎crates/uv-cli/src/lib.rs‎

Lines changed: 132 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
use std::ffi::OsString;
22
use std::fmt::{self, Display, Formatter};
33
use std::ops::{Deref, DerefMut};
4-
use std::path::PathBuf;
4+
use std::path::{Path, PathBuf};
55
use std::str::FromStr;
66

77
use anyhow::{Result, anyhow};
@@ -19,12 +19,12 @@ use uv_configuration::{
1919
ProjectBuildBackend, TargetTriple, TrustedHost, TrustedPublishing, VersionControlSystem,
2020
};
2121
use uv_distribution_types::{
22-
ConfigSettingEntry, ConfigSettingPackageEntry, Index, IndexUrl, Origin, PipExtraIndex,
23-
PipFindLinks, PipIndex,
22+
ConfigSettingEntry, ConfigSettingPackageEntry, Index, IndexName, IndexSourceError, IndexUrl,
23+
Origin, PipExtraIndex, PipFindLinks, PipIndex,
2424
};
2525
use uv_normalize::{ExtraName, GroupName, PackageName, PipGroupName};
26-
use uv_pep508::{MarkerTree, Requirement};
27-
use uv_preview::MaybePreviewFeature;
26+
use uv_pep508::{MarkerTree, Requirement, VerbatimUrl};
27+
use uv_preview::{MaybePreviewFeature, PreviewFeature};
2828
use uv_pypi_types::VerbatimParsedUrl;
2929
use uv_python::{PythonDownloads, PythonPreference, PythonVersion};
3030
use uv_redacted::DisplaySafeUrl;
@@ -35,6 +35,7 @@ use uv_resolver::{
3535
use uv_settings::PythonInstallMirrors;
3636
use uv_static::EnvVars;
3737
use uv_torch::TorchMode;
38+
use uv_warnings::warn_user_once;
3839
use uv_workspace::pyproject_mut::AddBoundsKind;
3940

4041
pub mod comma;
@@ -1346,40 +1347,137 @@ fn parse_find_links(input: &str) -> Result<Maybe<PipFindLinks>, String> {
13461347
}
13471348
}
13481349

1349-
/// Parse an `--index` argument into a [`Vec<Index>`], mapping the empty string to an empty Vec.
1350+
/// An unresolved index passed by the user by its name.
1351+
#[derive(Debug, Clone, PartialEq, Eq)]
1352+
pub struct UnresolvedIndex {
1353+
name: IndexName,
1354+
default: bool,
1355+
}
1356+
1357+
impl UnresolvedIndex {
1358+
/// Resolve an index name against the effective filesystem configuration.
1359+
fn resolve(self, indexes: &[Index], preview_enabled: bool) -> Result<Index> {
1360+
let Self { name, default } = self;
1361+
let path_exists = Path::new(name.as_ref()).exists();
1362+
1363+
// Outside preview, an existing path retains its current interpretation.
1364+
if preview_enabled || !path_exists {
1365+
if let Some(index) = indexes
1366+
.iter()
1367+
.find(|index| index.name.as_ref() == Some(&name))
1368+
{
1369+
if !preview_enabled {
1370+
warn_user_once!(
1371+
"Referencing an index by name is experimental and may change without warning. Pass `--preview-features {}` to disable this warning.",
1372+
PreviewFeature::IndexByName
1373+
);
1374+
}
1375+
1376+
let mut index = index.clone();
1377+
// Keep relative paths anchored to their configuration file without marking them
1378+
// as absolute when CLI settings are rebased or written back to a project.
1379+
if let IndexUrl::Path(url) = index.url()
1380+
&& !url.was_given_absolute()
1381+
{
1382+
index.url = IndexUrl::from(VerbatimUrl::from_url(index.raw_url().clone()));
1383+
}
1384+
1385+
return Ok(Index {
1386+
default,
1387+
explicit: false,
1388+
origin: Some(Origin::Cli),
1389+
..index
1390+
});
1391+
}
1392+
1393+
if preview_enabled && !path_exists {
1394+
return Err(anyhow!("Could not find an index named `{name}`"));
1395+
}
1396+
}
1397+
1398+
Ok(Index {
1399+
default,
1400+
origin: Some(Origin::Cli),
1401+
..Index::from_str(name.as_ref())?
1402+
})
1403+
}
1404+
}
1405+
1406+
/// A potentially unresolved index.
1407+
#[expect(clippy::large_enum_variant)]
1408+
#[derive(Debug, Clone, PartialEq, Eq)]
1409+
pub enum IndexArg {
1410+
/// A usable index with a URL.
1411+
Resolved(Index),
1412+
/// An unresolved index specification.
1413+
Unresolved(UnresolvedIndex),
1414+
}
1415+
1416+
impl IndexArg {
1417+
fn new(value: &str, default: bool) -> Result<Self, IndexSourceError> {
1418+
if let Ok(name) = IndexName::from_str(value) {
1419+
return Ok(Self::Unresolved(UnresolvedIndex { name, default }));
1420+
}
1421+
1422+
let index = Index::from_str(value)?;
1423+
Ok(Self::Resolved(Index {
1424+
default,
1425+
origin: Some(Origin::Cli),
1426+
..index
1427+
}))
1428+
}
1429+
1430+
/// Parse an index passed via `--index`.
1431+
fn from_index(value: &str) -> Result<Self, IndexSourceError> {
1432+
Self::new(value, false)
1433+
}
1434+
1435+
/// Parse an index passed via `--default-index`.
1436+
fn from_default_index(value: &str) -> Result<Self, IndexSourceError> {
1437+
Self::new(value, true)
1438+
}
1439+
1440+
/// Resolve the argument against indexes from the effective configuration.
1441+
fn resolve(self, indexes: &[Index]) -> Result<Index> {
1442+
let index = match self {
1443+
Self::Resolved(index) => index,
1444+
Self::Unresolved(index) => {
1445+
index.resolve(indexes, uv_preview::is_enabled(PreviewFeature::IndexByName))?
1446+
}
1447+
};
1448+
1449+
index.url().warn_on_disambiguated_relative_path();
1450+
1451+
Ok(index)
1452+
}
1453+
}
1454+
1455+
/// Parse an `--index` argument into a [`Vec<IndexArg>`], mapping the empty string to an empty Vec.
13501456
///
13511457
/// This function splits the input on all whitespace characters rather than a single delimiter,
13521458
/// which is necessary to parse environment variables like `PIP_EXTRA_INDEX_URL`.
13531459
/// The standard `clap::Args` `value_delimiter` only supports single-character delimiters.
1354-
fn parse_indices(input: &str) -> Result<Vec<Maybe<Index>>, String> {
1460+
fn parse_indices(input: &str) -> Result<Vec<Maybe<IndexArg>>, String> {
13551461
if input.trim().is_empty() {
13561462
return Ok(Vec::new());
13571463
}
13581464
let mut indices = Vec::new();
13591465
for token in input.split_whitespace() {
1360-
match Index::from_str(token) {
1361-
Ok(index) => indices.push(Maybe::Some(Index {
1362-
default: false,
1363-
origin: Some(Origin::Cli),
1364-
..index
1365-
})),
1466+
match IndexArg::from_index(token) {
1467+
Ok(index) => indices.push(Maybe::Some(index)),
13661468
Err(e) => return Err(e.to_string()),
13671469
}
13681470
}
13691471
Ok(indices)
13701472
}
13711473

1372-
/// Parse a `--default-index` argument into an [`Index`], mapping the empty string to `None`.
1373-
fn parse_default_index(input: &str) -> Result<Maybe<Index>, String> {
1474+
/// Parse a `--default-index` argument into an [`IndexArg`], mapping the empty string to `None`.
1475+
fn parse_default_index(input: &str) -> Result<Maybe<IndexArg>, String> {
13741476
if input.is_empty() {
13751477
Ok(Maybe::None)
13761478
} else {
1377-
match Index::from_str(input) {
1378-
Ok(index) => Ok(Maybe::Some(Index {
1379-
default: true,
1380-
origin: Some(Origin::Cli),
1381-
..index
1382-
})),
1479+
match IndexArg::from_default_index(input) {
1480+
Ok(index) => Ok(Maybe::Some(index)),
13831481
Err(err) => Err(err.to_string()),
13841482
}
13851483
}
@@ -6625,7 +6723,7 @@ pub struct GenerateShellCompletionArgs {
66256723

66266724
#[derive(Args)]
66276725
pub struct IndexArgs {
6628-
/// The URLs to use when resolving dependencies, in addition to the default index.
6726+
/// The indexes to use when resolving dependencies, in addition to the default index.
66296727
///
66306728
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
66316729
/// directory laid out in the same format.
@@ -6634,10 +6732,13 @@ pub struct IndexArgs {
66346732
/// `--default-index` (which defaults to PyPI). When multiple `--index` flags are provided,
66356733
/// earlier values take priority.
66366734
///
6637-
/// Index names are not supported as values. Relative paths must be disambiguated from index
6638-
/// names with `./` or `../` on Unix or `.\\`, `..\\`, `./` or `../` on Windows.
6735+
/// Indexes configured in `uv.toml` or `pyproject.toml` may be selected by name. Enable the
6736+
/// `index-by-name` preview feature to prefer index names over relative paths.
6737+
///
6738+
/// Relative paths can be disambiguated from index names with `./` or `../` on Unix or `.\\`,
6739+
/// `..\\`, `./` or `../` on Windows.
66396740
//
6640-
// The nested Vec structure (`Vec<Vec<Maybe<Index>>>`) is required for clap's
6741+
// The nested Vec structure (`Vec<Vec<Maybe<IndexArg>>>`) is required for clap's
66416742
// value parsing mechanism, which processes one value at a time, in order to handle
66426743
// `UV_INDEX` the same way pip handles `PIP_EXTRA_INDEX_URL`.
66436744
#[arg(
@@ -6647,23 +6748,26 @@ pub struct IndexArgs {
66476748
value_parser = parse_indices,
66486749
help_heading = "Index options"
66496750
)]
6650-
pub index: Option<Vec<Vec<Maybe<Index>>>>,
6751+
pub index: Option<Vec<Vec<Maybe<IndexArg>>>>,
66516752

6652-
/// The URL of the default package index (by default: <https://pypi.org/simple>).
6753+
/// The default package index (by default: <https://pypi.org/simple>).
66536754
///
66546755
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
66556756
/// directory laid out in the same format.
66566757
///
66576758
/// The index given by this flag is given lower priority than all other indexes specified via
66586759
/// the `--index` flag.
6760+
///
6761+
/// Indexes configured in `uv.toml` or `pyproject.toml` may be selected by name. Enable the
6762+
/// `index-by-name` preview feature to prefer index names over relative paths.
66596763
#[arg(
66606764
long,
66616765
env = EnvVars::UV_DEFAULT_INDEX,
66626766
hide_env_values = true,
66636767
value_parser = parse_default_index,
66646768
help_heading = "Index options"
66656769
)]
6666-
pub default_index: Option<Maybe<Index>>,
6770+
pub default_index: Option<Maybe<IndexArg>>,
66676771

66686772
/// (Deprecated: use `--default-index` instead) The URL of the Python package index (by default:
66696773
/// <https://pypi.org/simple>).

0 commit comments

Comments
 (0)