11use std:: ffi:: OsString ;
22use std:: fmt:: { self , Display , Formatter } ;
33use std:: ops:: { Deref , DerefMut } ;
4- use std:: path:: PathBuf ;
4+ use std:: path:: { Path , PathBuf } ;
55use std:: str:: FromStr ;
66
77use anyhow:: { Result , anyhow} ;
@@ -19,12 +19,12 @@ use uv_configuration::{
1919 ProjectBuildBackend , TargetTriple , TrustedHost , TrustedPublishing , VersionControlSystem ,
2020} ;
2121use 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} ;
2525use 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 } ;
2828use uv_pypi_types:: VerbatimParsedUrl ;
2929use uv_python:: { PythonDownloads , PythonPreference , PythonVersion } ;
3030use uv_redacted:: DisplaySafeUrl ;
@@ -35,6 +35,7 @@ use uv_resolver::{
3535use uv_settings:: PythonInstallMirrors ;
3636use uv_static:: EnvVars ;
3737use uv_torch:: TorchMode ;
38+ use uv_warnings:: warn_user_once;
3839use uv_workspace:: pyproject_mut:: AddBoundsKind ;
3940
4041pub 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 ) ]
66276725pub 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