Skip to content

Commit

Permalink
Document the effect of ordering on package priority (#6211)
Browse files Browse the repository at this point in the history
Closes #6209
Closes #5474
  • Loading branch information
zanieb authored Aug 19, 2024
1 parent 6bc8639 commit c817f41
Show file tree
Hide file tree
Showing 4 changed files with 28 additions and 3 deletions.
8 changes: 8 additions & 0 deletions PIP_COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,3 +447,11 @@ is omitted.
While this is not strictly compliant with [PEP 440](https://peps.python.org/pep-0440/), it _is_
consistent with
[pip](https://github.com/pypa/pip/blob/24.1.1/src/pip/_internal/resolution/resolvelib/candidates.py#L540).

## Package priority

There are usually many possible solutions given a set of requirements — a resolver must choose
between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
the default priority. This means that uv's resolution can differ based on the order of the packages.
For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.
9 changes: 7 additions & 2 deletions crates/uv-cli/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -692,10 +692,13 @@ fn parse_maybe_file_path(input: &str) -> Result<Maybe<PathBuf>, String> {
pub struct PipCompileArgs {
/// Include all packages listed in the given `requirements.in` files.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
/// extract the requirements for the relevant project.
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will extract the
/// requirements for the relevant project.
///
/// If `-` is provided, then requirements will be read from stdin.
///
/// The order of the requirements files and the requirements in them is used to determine
/// priority during resolution.
#[arg(required(true), value_parser = parse_file_path)]
pub src_file: Vec<PathBuf>,

Expand Down Expand Up @@ -1245,6 +1248,8 @@ pub struct PipSyncArgs {
#[allow(clippy::struct_excessive_bools)]
pub struct PipInstallArgs {
/// Install all listed packages.
///
/// The order of the packages is used to determine priority during resolution.
#[arg(group = "sources")]
pub package: Vec<String>,

Expand Down
8 changes: 8 additions & 0 deletions docs/pip/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -395,3 +395,11 @@ will include all index URLs when `--emit-index-url` is passed, including the def
By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike
`pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to
`uv pip compile`.

## Package priority

There are usually many possible solutions given a set of requirements — a resolver must choose
between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
the default priority. This means that uv's resolution can differ based on the order of the packages.
For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.
6 changes: 5 additions & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -3546,6 +3546,8 @@ uv pip compile [OPTIONS] <SRC_FILE>...

<p>If <code>-</code> is provided, then requirements will be read from stdin.</p>

<p>The order of the requirements files and the requirements in them is used to determine priority during resolution.</p>

</dd></dl>

<h3 class="cli-reference">Options</h3>
Expand Down Expand Up @@ -4191,7 +4193,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB

<h3 class="cli-reference">Arguments</h3>

<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages</p>
<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages.</p>

<p>The order of the packages is used to determine priority during resolution.</p>

</dd></dl>

Expand Down

0 comments on commit c817f41

Please sign in to comment.