In a similar way that #19860 needs to add a top-level script node to
represent dependencies of the script, it's been an outstanding issue
that we lack a top-level workspace node to represent dependency-groups
that are exclusive to the workspace.
Like other `--script` commands this tells uv to ignore the current
workspace and only handle the PEP 723 script at the given path, with its
own lock and venv.
This is a field of particular interest to `ty`, especially if
`--isolated` or `--script` stuff is going on. Possibly also enables a
future where we don't necessarily store the workspace venv in the
project dir.
Adding it here first to establish it in the schema, further integrations
will be in followups.
## Summary
This expands `uv workspace metadata` with many of the fields that are
found in `uv.lock` so that we have a format with information about the
dependency graph/resolution that we're willing to call stable and have
people rely upon (rather than `uv.lock` which we'd rather you don't try
to interpret).
To a first approximation you can think of this as "uv.lock but
serialized to json" but with the fields a bit more limited for now (easy
to add later).
The biggest intentional divergence with uv.lock is that we favour
encoding the dependency graph in a form that looks more like our
internal "resolve" graph, in that hopes that it will simplify the work
of anyone doing analysis on the graph (we structure our internal graph
like this for a reason).
Specifically, the `resolve` field contains the entire dependency graph,
with packages desugarred into several different nodes. There are 4 kinds
of nodes (really 3, the build nodes will only be introduced when we
establish build-dependency locking):
* packages: `mypackage==1.0.0 @ registry+https://pypi.org/simple`
* extras: `mypackage[myextra]==1.0.0 @ registry+https://pypi.org/simple`
* groups: `mypackage:mygroup==1.0.0 @ registry+https://pypi.org/simple`
* build: `mypackage(build)==1.0.0 @ registry+https://pypi.org/simple`
package nodes hold additional metadata about the package itself, and ids
of the associated extra/group/build nodes.
---
A package like this:
```toml
[project]
name = "mypackage"
version = "1.0.0"
dependencies = ["httpx"]
[project.optional-dependencies]
cli = ["rich"]
[dependency-groups]
dev = ["typing-extensions"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```
will get 4 nodes with the following edges (Version and Source omitted
here for brevity):
* `mypackage`
* `httpx`
* `mypackage(build)`
* `hatchling`
* `mypackage[cli]`
* `mypackage`
* `rich`
* `mypackage:dev`
* `typing-extensions`
Note that `mypackage[cli]` has a dependency edge on `mypackage` while
`mypackage:dev` does not. This is because
`mypackage[cli]` is fundamentally an augmentation of `mypackage` while
`mypackage:dev` is just a list of packages that happens to be defined by
`mypackage`'s pyproject.toml.
The resulting nodes for `mypackage` will look something like:
<details>
<summary>json blob</summary>
```json
{
"resolve": {
"mypackage==1.0.0 @ editable+.": {
"name": "mypackage",
"version": "1.0.0",
"source": {
"editable": "."
},
"kind": "package",
"dependencies": [
{
"id": "httpx==3.6 @ registry+https://pypi.org/simple"
"marker": "sys_platform == 'linux'"
},
],
"optional_dependencies": [
{
"name": "cli",
"id": "mypackage[cli]==1.0.0 @ editable+."
},
],
"dependency_groups": [
{
"name": "dev",
"id": "mypackage:dev==1.0.0 @ editable+."
}
]
"build_system": {
"build_backend": "hatchling.build",
"id": "mypackage(build)==1.0.0 @ editable+."
}
"sdist": { ... },
"wheels": [ ... ]
},
"mypackage:dev==1.0.0 @ editable+.": {
"name": "mypackage",
"version": "1.0.0",
"source": {
"editable": "."
},
"kind": {
"group": "dev"
},
"dependencies": [
{
"id": "typing-extensions==1.2.3 @ registry+https://pypi.org/simple"
},
]
},
}
"mypackage[cli]==1.0.0 @ editable+.": {
"name": "mypackage",
"version": "1.0.0",
"source": {
"editable": "."
},
"kind": {
"extra": "cli"
},
"dependencies": [
{
"id": "rich==2.2.3 @ registry+https://pypi.org/simple"
},
{
"id": "mypackage==1.0.0 @ editable+."
},
]
},
"mypackage(build)==1.0.0 @ editable+.": {
"name": "mypackage",
"version": "1.0.0",
"source": {
"editable": "."
},
"kind": "build",
"dependencies": [
{
"id": "hatchling==3.2.3 @ registry+https://pypi.org/simple"
},
]
}
}
}
```
</details>
## Test Plan
Snapshots
An opinionated write-up on why Python packaging needs metadata
consistency, and that we need to extend metadata to accommodate ML and
scientific users.
I didn't add a paragraph related to CUDA or accelerators in general and
wheel variants, as this is currently support neither by wheel tags nor
by PEP 508 markers, so it's not a strict metadata consistency concern,
plus this would get outdated quickly as wheel variants progress.
We're regularly get questions about this. The DPO thread is the best
ressource, but it's also a long read, so I summarized some points for
uv's decision.
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
Move the Resolver reference into a new Internals section in the
reference. Add the new nav item, fix internal linking to the new path,
fix server side redirect to the new path for external traffic via
redirect_maps, fix non existent anchor in
"docs/concepts/projects/dependencies.md"
Closes#15412
Aria Desires