## Summary
Documentation steps resulted in errors due to single quotes when adding
project dependencies:
``` shell
>uv add 'httpx>0.1.0'
error: Failed to parse: `'httpx`
Caused by: Expected package name starting with an alphanumeric character, found `'`
'httpx
^
```
``` shell
>uv add 'PyQt5; sys_platform == "windows"
error: Failed to parse: `'PyQt5;`
Caused by: Expected package name starting with an alphanumeric character, found `'`
'PyQt5;
^
```
## Testing Steps
- Follow new documentation steps
Tested on:
- [x] Windows
Just a small note to say that dependencies between workspace members are
editable as shown in #9362
(This might be obvious since if dependencies between workspaces members
are not editable then every time a workspace member is update it has to
be manually reinstalled but since it's in the concepts documentation and
since I see a lot of issues about workspaces, that little note might
help newcomers a little bit)
## Summary
This PR fixes name of `--refresh-package` flag in cache docs. It's
misspelled as `--refresh-dependency`.
## Test Plan
Deployed docs locally.
This is a first-pass at updating the "Managing dependencies" page after
moving some of the project concept documentation into it. I want to do
more things, like improve visibility into upgrading packages and
reordering some sections, but will tackle those separately for review.
The primary goals here were to consolidate redundant information on
dependency tables and improve the consistency of examples.
The snippet out of context looks like a valid minimal pyproject.toml
which it is not without name and version. The line worked in layout.md
before when it was just under the minimal config.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
- Adds a collapsible section for the project concept
- Splits the project concept document into several child documents.
- Moves the workspace and dependencies documents to under the project
section
- Adds a mkdocs plugin for redirects, so links to the moved documents
still work
I attempted to make the minimum required changes to the contents of the
documents here. There is a lot of room for improvement on the content of
each new child document. For review purposes, I want to do that work
separately. I'd prefer if the review focused on this structure and idea
rather than the content of the files.
I expect to do this to other documentation pages that would otherwise be
very nested.
The project concept landing page and nav (collapsed by default) looks
like this now:
<img width="1507" alt="Screenshot 2024-11-14 at 11 28 45 AM"
src="https://github.com/user-attachments/assets/88288b09-8463-49d4-84ba-ee27144b62a5">
## Summary
This PR enables something like the "final boss" of PyTorch setups --
explicit support for CPU vs. GPU-enabled variants via extras:
```toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.13.0"
dependencies = []
[project.optional-dependencies]
cpu = [
"torch==2.5.1+cpu",
]
gpu = [
"torch==2.5.1",
]
[tool.uv.sources]
torch = [
{ index = "torch-cpu", extra = "cpu" },
{ index = "torch-gpu", extra = "gpu" },
]
[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
[tool.uv]
conflicts = [
[
{ extra = "cpu" },
{ extra = "gpu" },
],
]
```
It builds atop the conflicting extras work to allow sources to be marked
as specific to a dedicated extra being enabled or disabled.
As part of this work, sources now have an `extra` field. If a source has
an `extra`, it means that the source is only applied to the requirement
when defined within that optional group. For example, `{ index =
"torch-cpu", extra = "cpu" }` above only applies to
`"torch==2.5.1+cpu"`.
The `extra` field does _not_ mean that the source is "enabled" when the
extra is activated. For example, this wouldn't work:
```toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.13.0"
dependencies = ["torch"]
[tool.uv.sources]
torch = [
{ index = "torch-cpu", extra = "cpu" },
{ index = "torch-gpu", extra = "gpu" },
]
[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu124"
explicit = true
```
In this case, the sources would effectively be ignored. Extras are
really confusing... but I think this is correct? We don't want enabling
or disabling extras to affect resolution information that's _outside_ of
the relevant optional group.
This doesn't cover the optional `package` key since I wasn't quite sure
how to articulate its utility in a digestible way.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Update `resolution` to `--resolution`, so it's aligned with the rest of
the resolution documentation, and copy-pastable for usage.
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
The example in the docs for adding a git source with `--branch` fails
because `main` doesn't exist.
```sh
uv add git+https://github.com/encode/httpx --branch main
# error: Git operation failed
# Caused by: failed to fetch into: /Users/manzt/.cache/uv/git-v0/db/4c0b1441d92956e1
# Caused by: failed to fetch branch `main`
# Caused by: process didn't exit successfully: `/usr/bin/git fetch --force --update-head-ok 'https://github.com/encode/httpx' '+refs/heads/main:refs/remotes/origin/main'` (exit status: 128)
```
This PR changes the example to the default branch for httpx, `master`.
<!-- What's the purpose of the change? What does it do, and why? -->
## Test Plan
N/A
<!-- How was it tested? -->
This adds the minimal documentation I think we need to release PEP 735
support.
I want to add documentation on `include-group` and such but that can
come after.
I also want to restructure some of the project dependency documentation,
but that will be easier once this all lands in `main`.
## Summary
Historically, we haven't enforced schema versions. This PR adds a
versioning policy such that, if a uv version writes schema v2, then...
- It will always reject lockfiles with schema v3 or later.
- It _may_ reject lockfiles with schema v1, but can also choose to read
them, if possible.
(For example, the change we proposed to rename `dev-dependencies` to
`dependency-groups` would've been backwards-compatible: newer versions
of uv could still read lockfiles that used the `dev-dependencies` field
name, but older versions should reject lockfiles that use the
`dependency-groups` field name.)
Closes https://github.com/astral-sh/uv/issues/8465.
Closes#8490 by improving the documentation to make it more obvious how
to manually edit the `pyproject.toml` if you want to explicitly set the
branch, rev (commit), or tag.
---------
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
This is part of making
https://github.com/astral-sh/uv/issues/7299#issuecomment-2385286341
better. You can now use `tool.uv.dependency-metadata` for direct URL
requirements. Unfortunately, you _must_ include a version, since we need
one to perform resolution.
## Summary
Going forward, we're going to provide better versioning guarantees
around using the same cache across multiple uv versions, so this PR
updates the docs to reflect that. It also bumps the `sdists-` version to
fix the inconvenience demonstrated in
https://github.com/astral-sh/uv/issues/8367.
Closes https://github.com/astral-sh/uv/issues/8367.
