forked from astral-sh/uv
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add support for named and explicit indexes (astral-sh#7481)
## Summary This PR adds a first-class API for defining registry indexes, beyond our existing `--index-url` and `--extra-index-url` setup. Specifically, you now define indexes like so in a `uv.toml` or `pyproject.toml` file: ```toml [[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121" ``` You can also provide indexes via `--index` and `UV_INDEX`, and override the default index with `--default-index` and `UV_DEFAULT_INDEX`. ### Index priority Indexes are prioritized in the order in which they're defined, such that the first-defined index has highest priority. Indexes are also inherited from parent configuration (e.g., the user-level `uv.toml`), but are placed after any indexes in the current project, matching our semantics for other array-based configuration values. You can mix `--index` and `--default-index` with the legacy `--index-url` and `--extra-index-url` settings; the latter two are merely treated as unnamed `[[tool.uv.index]]` entries. ### Index pinning If an index includes a name (which is optional), it can then be referenced via `tool.uv.sources`: ```toml [[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121" [tool.uv.sources] torch = { index = "pytorch" } ``` If an index is marked as `explicit = true`, it can _only_ be used via such references, and will never be searched implicitly: ```toml [[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121" explicit = true [tool.uv.sources] torch = { index = "pytorch" } ``` Indexes defined outside of the current project (e.g., in the user-level `uv.toml`) can _not_ be explicitly selected. (As of now, we only support using a single index for a given `tool.uv.sources` definition.) ### Default index By default, we include PyPI as the default index. This remains true even if the user defines a `[[tool.uv.index]]` -- PyPI is still used as a fallback. You can mark an index as `default = true` to (1) disable the use of PyPI, and (2) bump it to the bottom of the prioritized list, such that it's used only if a package does not exist on a prior index: ```toml [[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121" default = true ``` ### Name reuse If a name is reused, the higher-priority index with that name is used, while the lower-priority indexes are ignored entirely. For example, given: ```toml [[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121" [[tool.uv.index]] name = "pytorch" url = "https://test.pypi.org/simple" ``` The `https://test.pypi.org/simple` index would be ignored entirely, since it's lower-priority than `https://download.pytorch.org/whl/cu121` but shares the same name. Closes astral-sh#171. ## Future work - Users should be able to provide authentication for named indexes via environment variables. - `uv add` should automatically write `--index` entries to the `pyproject.toml` file. - Users should be able to provide multiple indexes for a given package, stratified by platform: ```toml [tool.uv.sources] torch = [ { index = "cpu", markers = "sys_platform == 'darwin'" }, { index = "gpu", markers = "sys_platform != 'darwin'" }, ] ``` - Users should be able to specify a proxy URL for a given index, to avoid writing user-specific URLs to a lockfile: ```toml [[tool.uv.index]] name = "test" url = "https://private.org/simple" proxy = "http://<omitted>/pypi/simple" ```
- Loading branch information
1 parent
34be3af
commit 5b39177
Showing
51 changed files
with
3,526 additions
and
658 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| use crate::{IndexUrl, IndexUrlError}; | ||
| use std::str::FromStr; | ||
| use thiserror::Error; | ||
| use url::Url; | ||
|
|
||
| #[derive(Debug, Clone, Hash, Eq, PartialEq, serde::Serialize, serde::Deserialize)] | ||
| #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] | ||
| pub struct Index { | ||
| /// The name of the index. | ||
| /// | ||
| /// Index names can be used to reference indexes elsewhere in the configuration. For example, | ||
| /// you can pin a package to a specific index by name: | ||
| /// | ||
| /// ```toml | ||
| /// [[tool.uv.index]] | ||
| /// name = "pytorch" | ||
| /// url = "https://download.pytorch.org/whl/cu121" | ||
| /// | ||
| /// [tool.uv.sources] | ||
| /// torch = { index = "pytorch" } | ||
| /// ``` | ||
| pub name: Option<String>, | ||
| /// The URL of the index. | ||
| /// | ||
| /// Expects to receive a URL (e.g., `https://pypi.org/simple`) or a local path. | ||
| pub url: IndexUrl, | ||
| /// Mark the index as explicit. | ||
| /// | ||
| /// Explicit indexes will _only_ be used when explicitly requested via a `[tool.uv.sources]` | ||
| /// definition, as in: | ||
| /// | ||
| /// ```toml | ||
| /// [[tool.uv.index]] | ||
| /// name = "pytorch" | ||
| /// url = "https://download.pytorch.org/whl/cu121" | ||
| /// explicit = true | ||
| /// | ||
| /// [tool.uv.sources] | ||
| /// torch = { index = "pytorch" } | ||
| /// ``` | ||
| #[serde(default)] | ||
| pub explicit: bool, | ||
| /// Mark the index as the default index. | ||
| /// | ||
| /// By default, uv uses PyPI as the default index, such that even if additional indexes are | ||
| /// defined via `[[tool.uv.index]]`, PyPI will still be used as a fallback for packages that | ||
| /// aren't found elsewhere. To disable the PyPI default, set `default = true` on at least one | ||
| /// other index. | ||
| /// | ||
| /// Marking an index as default will move it to the front of the list of indexes, such that it | ||
| /// is given the highest priority when resolving packages. | ||
| #[serde(default)] | ||
| pub default: bool, | ||
| // /// The type of the index. | ||
| // /// | ||
| // /// Indexes can either be PEP 503-compliant (i.e., a registry implementing the Simple API) or | ||
| // /// structured as a flat list of distributions (e.g., `--find-links`). In both cases, indexes | ||
| // /// can point to either local or remote resources. | ||
| // #[serde(default)] | ||
| // pub r#type: IndexKind, | ||
| } | ||
|
|
||
| // #[derive( | ||
| // Default, Debug, Copy, Clone, Hash, Eq, PartialEq, serde::Serialize, serde::Deserialize, | ||
| // )] | ||
| // #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] | ||
| // pub enum IndexKind { | ||
| // /// A PEP 503 and/or PEP 691-compliant index. | ||
| // #[default] | ||
| // Simple, | ||
| // /// An index containing a list of links to distributions (e.g., `--find-links`). | ||
| // Flat, | ||
| // } | ||
|
|
||
| impl Index { | ||
| /// Initialize an [`Index`] from a pip-style `--index-url`. | ||
| pub fn from_index_url(url: IndexUrl) -> Self { | ||
| Self { | ||
| url, | ||
| name: None, | ||
| explicit: false, | ||
| default: true, | ||
| } | ||
| } | ||
|
|
||
| /// Initialize an [`Index`] from a pip-style `--extra-index-url`. | ||
| pub fn from_extra_index_url(url: IndexUrl) -> Self { | ||
| Self { | ||
| url, | ||
| name: None, | ||
| explicit: false, | ||
| default: false, | ||
| } | ||
| } | ||
|
|
||
| /// Return the [`IndexUrl`] of the index. | ||
| pub fn url(&self) -> &IndexUrl { | ||
| &self.url | ||
| } | ||
|
|
||
| /// Return the raw [`URL`] of the index. | ||
| pub fn raw_url(&self) -> &Url { | ||
| self.url.url() | ||
| } | ||
| } | ||
|
|
||
| impl FromStr for Index { | ||
| type Err = IndexSourceError; | ||
|
|
||
| fn from_str(s: &str) -> Result<Self, Self::Err> { | ||
| // Determine whether the source is prefixed with a name, as in `name=https://pypi.org/simple`. | ||
| if let Some((name, url)) = s.split_once('=') { | ||
| if name.is_empty() { | ||
| return Err(IndexSourceError::EmptyName); | ||
| } | ||
|
|
||
| if name.chars().all(char::is_alphanumeric) { | ||
| let url = IndexUrl::from_str(url)?; | ||
| return Ok(Self { | ||
| name: Some(name.to_string()), | ||
| url, | ||
| explicit: false, | ||
| default: false, | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| // Otherwise, assume the source is a URL. | ||
| let url = IndexUrl::from_str(s)?; | ||
| Ok(Self { | ||
| name: None, | ||
| url, | ||
| explicit: false, | ||
| default: false, | ||
| }) | ||
| } | ||
| } | ||
|
|
||
| /// An error that can occur when parsing an [`Index`]. | ||
| #[derive(Error, Debug)] | ||
| pub enum IndexSourceError { | ||
| #[error(transparent)] | ||
| Url(#[from] IndexUrlError), | ||
| #[error("Index included a name, but the name was empty")] | ||
| EmptyName, | ||
| } |
Oops, something went wrong.