From 8341d810b2eea7da1b7fc00467e0759e3c06b0a0 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sat, 7 Sep 2024 21:16:12 +0200 Subject: [PATCH] docs: list supported sdist formats (#7168) ## Summary Explicitly list the formats and extensions that uv supports, based on [this list](https://github.com/astral-sh/uv/blob/86ee8d2c0134692dec85901bf2a7f459ea01bbd6/crates/distribution-filename/src/extension.rs#L70-L77). Not a huge fan of adding the section in `concepts/resolution.md`, but I did not find a better place. Alternatively we could maybe add a dedicated page that shortly explains Python package types (wheels, sdists), where such a section could live? ## Test Plan Local run of the documentation. --- README.md | 4 ++-- 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 ++-- 9 files changed, 46 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3975d146e..8962db512 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 diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 7e4a72101..c6e9d3e42 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 (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 7e3b1649e..84fcfec22 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 (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 (`.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/concepts/dependencies.md b/docs/concepts/dependencies.md index d65e586f6..e45ea9dcd 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 (typically 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 +(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 65e361e7f..16063d97f 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 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. `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 0df0ce80f..e5827b563 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. While less common, other formats are also supported 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 214e13b0e..3aeef064e 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 (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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 (.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 0fe5287a1..0d24a32b0 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 (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 (`.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 07867fe9e..2047d1934 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 (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 (`.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"