From 3f80bfe80e148e1c3e9a7d808d9d9ded68b15328 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 7 Sep 2024 16:17:52 +0200 Subject: [PATCH 1/5] docs: list supported sdist formats --- crates/uv-cli/src/lib.rs | 2 +- crates/uv-settings/src/settings.rs | 4 ++-- docs/concepts/dependencies.md | 12 +++++++----- docs/concepts/projects.md | 6 +++--- docs/concepts/resolution.md | 12 ++++++++++++ docs/reference/cli.md | 30 +++++++++++++++--------------- docs/reference/settings.md | 4 ++-- uv.schema.json | 4 ++-- 8 files changed, 44 insertions(+), 30 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 7e4a7210104b..3a6424094bdc 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3562,7 +3562,7 @@ pub struct IndexArgs { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 7e3b1649ed07..893164d9def4 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -318,7 +318,7 @@ pub struct ResolverInstallerOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. @@ -705,7 +705,7 @@ pub struct PipOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index d65e586f6041..17775df76a58 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -128,7 +128,8 @@ A `subdirectory` may be specified if the package isn't in the repository root. ### URL To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source -distribution (ending in `.zip` or `.tar.gz`). +distribution (usually ending in `.tar.gz` or `.zip`, see +[here](../concepts/resolution.md#source-distribution) for all supported formats). For example: @@ -149,13 +150,14 @@ httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b280 ``` URL dependencies can also be manually added or edited in the `pyproject.toml` with the -`{ url = }` syntax. A `subdirectory` may be specified if the if the source distribution isn't -in the archive root. +`{ url = }` syntax. A `subdirectory` may be specified if the source distribution isn't in the +archive root. ### Path -To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending -in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. +To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (usually +ending in `.tar.gz` or `.zip`, see [here](../concepts/resolution.md#source-distribution) for all +supported formats), or a directory containing a `pyproject.toml`. For example: diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index 65e361e7fa0f..735c569166d0 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -560,9 +560,9 @@ To distribute your project to others (e.g., to upload it to an index like PyPI), build it into a distributable format. Python projects are typically distributed as both source distributions (sdists) and binary -distributions (wheels). The former is a `.tar.gz` file containing the project's source code along -with some additional metadata, while the latter is a `.whl` file containing pre-built artifacts that -can be installed directly. +distributions (wheels). The former is usually a `.tar.gz` or `.zip` file containing the project's +source code along with some additional metadata, while the latter is a `.whl` file containing +pre-built artifacts that can be installed directly. `uv build` can be used to build both source distributions and binary distributions for your project. By default, `uv build` will build the project in the current directory, and place the built diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 0df0ce80f07c..6f47e96da18d 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -296,6 +296,18 @@ To ensure reproducibility, messages for unsatisfiable resolutions will not menti distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated as if they do not exist. +## Source distribution + +Most packages publish their source distributions as gzip tarball (`.tar.gz`) or zip (`.zip`) +archives, but while less common, other formats exist. uv supports the following formats and +extensions when reading and extracting source distributions: + +- bzip2 tarball (`.tar.bz2`) +- gzip tarball (`.tar.gz`) +- xz tarball (`.tar.xz`) +- zip (`.zip`) +- zstd tarball (`.tar.zst`) + ## Learn more For more details about the internals of the resolver, see the diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 214e13b0e760..2f03a9f8c57a 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -136,7 +136,7 @@ uv run [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -610,7 +610,7 @@ uv add [OPTIONS] >

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -910,7 +910,7 @@ uv remove [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1198,7 +1198,7 @@ uv sync [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1479,7 +1479,7 @@ uv lock [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1742,7 +1742,7 @@ uv export [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2028,7 +2028,7 @@ uv tree [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2383,7 +2383,7 @@ uv tool run [OPTIONS] [COMMAND]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2651,7 +2651,7 @@ uv tool install [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2919,7 +2919,7 @@ uv tool upgrade [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4302,7 +4302,7 @@ uv pip compile [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4674,7 +4674,7 @@ uv pip sync [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -5000,7 +5000,7 @@ uv pip install [OPTIONS] |--editable May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6057,7 +6057,7 @@ uv venv [OPTIONS] [PATH]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6282,7 +6282,7 @@ uv build [OPTIONS] [SRC]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 0fe5287a153d..e39d6ecfc893 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -370,7 +370,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (`.tar.gz` or `.zip`) at the top level. +source distributions (usually `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. @@ -1662,7 +1662,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (`.tar.gz` or `.zip`) at the top level. +source distributions (usually `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. diff --git a/uv.schema.json b/uv.schema.json index 07867fe9ee75..7c813bfef67d 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -118,7 +118,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (`.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" @@ -698,7 +698,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (`.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" From 43aab74376d577a011ef83fad742369438227809 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 7 Sep 2024 16:41:29 +0200 Subject: [PATCH 2/5] docs(README): fix a wrong link --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3975d146eebc..8962db51203b 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,8 @@ An extremely fast Python package and project manager, written in Rust. [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies). - 🗂️ Provides [comprehensive project management](#project-management), with a [universal lockfile](https://docs.astral.sh/uv/concepts/projects#project-lockfile). -- 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a - familiar CLI. +- 🔩 Includes a [pip-compatible interface](#a-pip-compatible-interface) for a performance boost with + a familiar CLI. - 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/workspaces) for scalable projects. - 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for From b4883cd5fa5f245059d1eff4f22d27cd11a6627c Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 7 Sep 2024 17:57:36 +0200 Subject: [PATCH 3/5] docs: use `e.g.` --- crates/uv-cli/src/lib.rs | 2 +- crates/uv-settings/src/settings.rs | 4 ++-- docs/reference/cli.md | 30 +++++++++++++++--------------- docs/reference/settings.md | 4 ++-- uv.schema.json | 4 ++-- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 3a6424094bdc..2911c9be8027 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3562,7 +3562,7 @@ pub struct IndexArgs { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (usually `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 893164d9def4..065be7e02fed 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -318,7 +318,7 @@ pub struct ResolverInstallerOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (usually `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. @@ -705,7 +705,7 @@ pub struct PipOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (usually `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 2f03a9f8c57a..7050f168ac26 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -136,7 +136,7 @@ uv run [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -610,7 +610,7 @@ uv add [OPTIONS] >

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -910,7 +910,7 @@ uv remove [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1198,7 +1198,7 @@ uv sync [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1479,7 +1479,7 @@ uv lock [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1742,7 +1742,7 @@ uv export [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2028,7 +2028,7 @@ uv tree [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2383,7 +2383,7 @@ uv tool run [OPTIONS] [COMMAND]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2651,7 +2651,7 @@ uv tool install [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2919,7 +2919,7 @@ uv tool upgrade [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4302,7 +4302,7 @@ uv pip compile [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4674,7 +4674,7 @@ uv pip sync [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -5000,7 +5000,7 @@ uv pip install [OPTIONS] |--editable May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6057,7 +6057,7 @@ uv venv [OPTIONS] [PATH]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6282,7 +6282,7 @@ uv build [OPTIONS] [SRC]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index e39d6ecfc893..3fab747cec69 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -370,7 +370,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (usually `.tar.gz` or `.zip`) at the top level. +source distributions (e.g. `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. @@ -1662,7 +1662,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (usually `.tar.gz` or `.zip`) at the top level. +source distributions (e.g. `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. diff --git a/uv.schema.json b/uv.schema.json index 7c813bfef67d..054a61159fb4 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -118,7 +118,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g. `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" @@ -698,7 +698,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g. `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" From fcf6a94b617d8b8a5fbf97e4055efe54f9ede22a Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 7 Sep 2024 18:18:32 +0200 Subject: [PATCH 4/5] docs: respect style guide --- crates/uv-cli/src/lib.rs | 2 +- crates/uv-settings/src/settings.rs | 4 ++-- docs/reference/cli.md | 30 +++++++++++++++--------------- docs/reference/settings.md | 4 ++-- uv.schema.json | 4 ++-- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 2911c9be8027..c6e9d3e429c2 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3562,7 +3562,7 @@ pub struct IndexArgs { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g., `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 065be7e02fed..84fcfec22fd6 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -318,7 +318,7 @@ pub struct ResolverInstallerOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g., `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. @@ -705,7 +705,7 @@ pub struct PipOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (e.g. `.tar.gz` or `.zip`) at the top level. + /// source distributions (e.g., `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7050f168ac26..3aeef064e7ae 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -136,7 +136,7 @@ uv run [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -610,7 +610,7 @@ uv add [OPTIONS] >

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -910,7 +910,7 @@ uv remove [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1198,7 +1198,7 @@ uv sync [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1479,7 +1479,7 @@ uv lock [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1742,7 +1742,7 @@ uv export [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2028,7 +2028,7 @@ uv tree [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2383,7 +2383,7 @@ uv tool run [OPTIONS] [COMMAND]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2651,7 +2651,7 @@ uv tool install [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2919,7 +2919,7 @@ uv tool upgrade [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4302,7 +4302,7 @@ uv pip compile [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4674,7 +4674,7 @@ uv pip sync [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -5000,7 +5000,7 @@ uv pip install [OPTIONS] |--editable May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6057,7 +6057,7 @@ uv venv [OPTIONS] [PATH]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6282,7 +6282,7 @@ uv build [OPTIONS] [SRC]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g. .tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 3fab747cec69..0d24a32b07e8 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -370,7 +370,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (e.g. `.tar.gz` or `.zip`) at the top level. +source distributions (e.g., `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. @@ -1662,7 +1662,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (e.g. `.tar.gz` or `.zip`) at the top level. +source distributions (e.g., `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. diff --git a/uv.schema.json b/uv.schema.json index 054a61159fb4..2047d19346e9 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -118,7 +118,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g. `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g., `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" @@ -698,7 +698,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g. `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g., `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" From 2bc8fd9bba95b4e7e5f13786646890235d455c72 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Sat, 7 Sep 2024 15:09:50 -0400 Subject: [PATCH 5/5] usually -> typically --- docs/concepts/dependencies.md | 8 ++++---- docs/concepts/projects.md | 2 +- docs/concepts/resolution.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index 17775df76a58..e45ea9dcdbeb 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -128,7 +128,7 @@ A `subdirectory` may be specified if the package isn't in the repository root. ### URL To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source -distribution (usually ending in `.tar.gz` or `.zip`, see +distribution (typically ending in `.tar.gz` or `.zip`; see [here](../concepts/resolution.md#source-distribution) for all supported formats). For example: @@ -155,9 +155,9 @@ archive root. ### Path -To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (usually -ending in `.tar.gz` or `.zip`, see [here](../concepts/resolution.md#source-distribution) for all -supported formats), or a directory containing a `pyproject.toml`. +To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution +(typically ending in `.tar.gz` or `.zip`; see [here](../concepts/resolution.md#source-distribution) +for all supported formats), or a directory containing a `pyproject.toml`. For example: diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index 735c569166d0..16063d97f2b7 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -560,7 +560,7 @@ To distribute your project to others (e.g., to upload it to an index like PyPI), build it into a distributable format. Python projects are typically distributed as both source distributions (sdists) and binary -distributions (wheels). The former is usually a `.tar.gz` or `.zip` file containing the project's +distributions (wheels). The former is typically a `.tar.gz` or `.zip` file containing the project's source code along with some additional metadata, while the latter is a `.whl` file containing pre-built artifacts that can be installed directly. diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 6f47e96da18d..e5827b563644 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -299,8 +299,8 @@ as if they do not exist. ## Source distribution Most packages publish their source distributions as gzip tarball (`.tar.gz`) or zip (`.zip`) -archives, but while less common, other formats exist. uv supports the following formats and -extensions when reading and extracting source distributions: +archives. While less common, other formats are also supported when reading and extracting source +distributions: - bzip2 tarball (`.tar.bz2`) - gzip tarball (`.tar.gz`)