feat(uv): Add a clean-sheet dependency implementation (#650)

[Design doc](https://docs.google.com/document/d/1UFessu8_BwmfMJXDvhyhaASrNMo7_3-gO1lTVASbJbs)

An implementation of pip based on consuming PEP-751 [1] like lockfiles.
Specifically uv lockfiles, which contain internal dependency graph
information that the PEP-751 specification labels optional.

Follows in the footsteps of rules_js's pnpm support by consuming a
lockfile which contains enough information to produce materialize
dependencies without performing _any_ repository time operations which
could be platform dependent.

## Features

- Supports cross-platform builds of wheels
- Supports hermetic source builds of wheels
- Automatically handles dependency cycles
- Creates unified pip hubs which span virtualenv/dependency solution
boundaries
- Pip library targets from deactivated venvs are _incompatible_
- Platform constraints on pip libraries do not prevent the creation of a
library target
- Allows for `--editable`-like workflows
- Supports `console_scripts` entrypoints*

## Example

```
# MODULE.bazel content
uv = use_extensioin("@aspect_rules_py//uv:extesion.bzl", "uv")
uv.declare_hub(hub_name = "pip")
    
uv.declare_venv(hub_name = "pip", venv_name = "a")
uv.lockfile(hub_name = "pip", venv_name = "a", src = "third_party/py/venvs/uv-a.lock")

uv.declare_venv(hub_name = "pip", venv_name = "b")
uv.lockfile(hub_name = "pip", venv_name = "b", src = "third_party/py/venvs/uv-b.toml")

use_repo(pip, "pip")
```

```
# BUILD.bazel content

py_venv_binary(
  name = "foo",
  srcs = [
    "foo.py",
  ],
  main = "foo.py",
  deps = [
    "@pip//cowsay", # Pull cowsay from the configured venv
  ],
  venv = "a", # Configure the default venv to be "a"; may be overriden at the CLI
)
```

The active venv state can be overriden at the cli by specifying
`--'@pip//venv=b'` here for instance, or by using transitions to(re) set
that same flag.

## Appendix

[1] https://peps.python.org/pep-0751/
[2] https://peps.python.org/pep-0751/#locking-build-requirements-for-sdists

### Changes are visible to end-users: yes

- Searched for relevant documentation and updated as needed: no
- Breaking change (forces users to change their own code or config): no
- Suggested release notes appear below: yes

`aspect_rules_py//uv` is now available as an alternative to `pip.parse`

### To do list
- ~[x] Audit the comments/FIXMEs for accuracy~ fast-follow
- ~[x] Go over zbarsky's nits~ mostly rejected for pythonstyle
- ~[x] Create a quick and dirty `uv_lock` rule~ fast-follow
- [x] Document the extension
- [x] Document that we consider the extension is unstable
- [x] Replace `pip.parse` internally entirely
- [x] Add support for annotating _replacement_ of pip deps with internal
builds (`--editable` / vendoring)
- [x] Implement an "all deps for all venvs" data source comparable to
the `rules_python` equivalent
- [x] Go back over the interpreter compatibility machinery and align it
with `rules_python`'s config settings for now
- [x] Go back over the interpreter feature flags and align it with
`rules_python`'s config settings for now
bazel-contrib/rules_python#3314
- ~Investigate implementing a `dist_info` target comparable to that
which `rules_python` generates~ There isn't a great way to do this
because dist-info is in our world part of the installed package, so any
such target is just ignoring the PyInfo details on the fileset.
- [x] Provide a pattern for implementing/activating venv entrypoints 
- [x] Implement conditional activation of deps
- [x] Implement an "all active deps" target comparable to the
`rules_python` all list
- [x] Look into platform conditional deps & how they get represented
- [x] Flatten the git log
- [x] Ensure `python_version` transition consistency with `rules_python`
- [x] Consider a feature flag to turn on `rules_python`'s [package name
normalization](https://github.com/bazel-contrib/rules_python/blob/main/python/private/normalize_name.bzl)
so that migration is easier.
- [x] Implement extra activation
- [x] Match the `rules_python` `@hub//package[:package]` syntax?
- [X] Get a `toml.bzl` working
- [X] Toolchainize the `uv` dependency

### Test plan

- [X] Manually test flipping the venv command line flag
- [X] Manually test flipping the venv transition attr
- [x] Create `py_venv_test`s covering that different versions of the
same package can be concurrently configured via different venvs
- [x] Create a `py_venv_test` covering that Airflow or another package
with dependency cycles can be provisioned
- [x] Create a `py_venv_binary` embedded in and transitioned for a Linux
OCI container across arch boundaries
- [x] Create a `py_venv_test` covering overriding a pip dep with a
1stparty target

---------

Co-authored-by: aspect-marvin[bot] <[email protected]>

Author: arrdem

.bazelrc

@@ -2,15 +2,14 @@ import %workspace%/bazel/defaults.bazelrc
 
 common --enable_bzlmod
 
-# Ignore slow manual and release targets
-# Prevents materializing crossbuild
-common --build_tag_filters=-manual,-release
-
 common --test_output=errors
 
 # Define value used by tests
 common --define=SOME_VAR=SOME_VALUE
 
+# Set the default virtualenv to 'default'
+common --@pypi//venv=default
+
 common --incompatible_enable_cc_toolchain_resolution
 
 # TODO(bzlmod): Don't break proto

.bcr/patches/remove_dev_deps.patch

@@ -1,8 +1,8 @@
---- a/MODULE.bazel	2025-11-04 23:45:40.547616185 +0000
-+++ b/MODULE.bazel	2025-11-04 23:45:40.547616185 +0000
-@@ -24,554 +24,3 @@
-     "@aspect_rules_py//py/private/toolchain/shim/...",
- )
+--- a/MODULE.bazel	2025-11-06 12:48:12
++++ b/MODULE.bazel	2025-11-06 12:48:12
+@@ -40,558 +40,5 @@
+ # HACK: In prod the includer's patch inserts the use_repo for multitool. This
+ # solves the problem of needing a use_repo here in prod and below in dev.
 
 -################################################################################
 -# Dev deps
@@ -29,7 +29,7 @@
 -# include("//bazel/include:release.MODULE.bazel")
 -# include("//bazel/include:multitool.MODULE.bazel")
 -# include("//bazel/include:tools.MODULE.bazel")
--
+ 
 -################################################################################
 -# Begin included content
 -
@@ -169,15 +169,7 @@
 -# from bazel/include/rust.MODULE.bazel
 -# Rust configuration
 -
--bazel_dep(name = "rules_rust", version = "0.66.0")
--single_version_override(
--    module_name = "rules_rust",
--    patch_strip = 1,
--    patches = [
--        "//bazel/patches:rules_rust.patch",
--    ],
--)
--
+-bazel_dep(name = "rules_rust", version = "0.67.0")
 -bazel_dep(name = "openssl", version = "3.3.1.bcr.6")
 -
 -RUST_EDITION = "2024"
@@ -493,23 +485,35 @@
 -    python_version = "3.12",
 -)
 -
+-# We still use pip for testing the virtual deps machinery
 -pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip", dev_dependency = True)
 -pip.parse(
 -    hub_name = "django",
 -    python_version = "3.9",
 -    requirements_lock = "//py/tests/virtual/django:requirements.txt",
 -)
--pip.parse(
+-use_repo(pip, "django")
+-
+-# For everything else, we use our own uv machinery
+-uv = use_extension("//uv/unstable:extension.bzl", "uv", dev_dependency = True)
+-uv.declare_hub(
 -    hub_name = "pypi",
--    python_version = "3.9",
--    requirements_lock = "//:requirements.txt",
 -)
--pip.parse(
+-uv.declare_venv(
 -    hub_name = "pypi",
--    python_version = "3.12",
--    requirements_lock = "//:requirements.txt",
+-    venv_name = "default",
+-)
+-uv.lockfile(
+-    src = "//:uv.lock",
+-    hub_name = "pypi",
+-    venv_name = "default",
+-)
+-uv.unstable_annotate_requirements(
+-    src = "//:annotations.toml",
+-    hub_name = "pypi",
+-    venv_name = "default",
 -)
--use_repo(pip, "django", "pypi")
+-use_repo(uv, "pypi")
 -
 -http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
 -
@@ -536,18 +540,18 @@
 -
 -########################################
 -# from bazel/include/release.MODULE.bazel
--bazel_dep(name = "with_cfg.bzl", version = "0.11.0")
 -bazel_dep(name = "rules_pkg", version = "1.1.0")
 -
 -########################################
 -# from bazel/include/multitool.MODULE.bazel
 -# Multitool configuration
 -
+-# Multitool is a prod dep (for now) so we don't need this
 -bazel_dep(name = "rules_multitool", version = "1.9.0")
 -
 -multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
 -multitool.hub(lockfile = "//tools:tools.lock.json")
--use_repo(multitool, "multitool")
+ use_repo(multitool, "multitool")
 -
 -########################################
 -# from bazel/include/tools.MODULE.bazel

BUILD.bazel

@@ -1,8 +1,6 @@
 load("@gazelle//:def.bzl", "gazelle")
-load("@pypi//:requirements.bzl", "all_whl_requirements")
 load("@rules_python//python/pip_install:requirements.bzl", "compile_pip_requirements")
-load("@rules_python_gazelle_plugin//manifest:defs.bzl", "gazelle_python_manifest")
-load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")
+load("//uv/private/manifest:defs.bzl", "gazelle_python_manifest")
 
 # gazelle:exclude internal_python_deps.bzl
 # gazelle:exclude internal_deps.bzl
@@ -12,9 +10,10 @@ load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")
 
 gazelle_python_manifest(
     name = "gazelle_python_manifest",
-    modules_mapping = ":modules_map",
-    pip_repository_name = "pypi",
-    requirements = "requirements.txt",
+    hub = "pypi",
+    venvs = [
+        "default",
+    ],
 )
 
 gazelle(
@@ -28,8 +27,3 @@ compile_pip_requirements(
     requirements_in = "requirements.in",
     requirements_txt = "requirements.txt",
 )
-
-modules_mapping(
-    name = "modules_map",
-    wheels = all_whl_requirements,
-)

MODULE.bazel

@@ -11,6 +11,7 @@ bazel_dep(name = "bazel_lib", version = "3.0.0")
 bazel_dep(name = "bazel_skylib", version = "1.4.2")
 bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "rules_python", version = "1.0.0")
+bazel_dep(name = "with_cfg.bzl", version = "0.11.0")
 
 tools = use_extension("//py:extensions.bzl", "py_tools")
 tools.rules_py_tools()
@@ -24,6 +25,21 @@ register_toolchains(
     "@aspect_rules_py//py/private/toolchain/shim/...",
 )
 
+toml = use_extension("//uv/private/tomltool:extension.bzl", "tomltool")
+use_repo(
+    toml,
+    "toml2json_aarch64_linux_gnu",
+    "toml2json_aarch64_osx_libsystem",
+    "toml2json_x86_64_linux_gnu",
+    "toml2json_x86_64_osx_libsystem",
+)
+
+host = use_extension("//uv/private/host:extension.bzl", "host_platform")
+use_repo(host, "aspect_rules_py_uv_host")
+
+# HACK: In prod the includer's patch inserts the use_repo for multitool. This
+# solves the problem of needing a use_repo here in prod and below in dev.
+
 ################################################################################
 # Dev deps
 #
@@ -189,15 +205,7 @@ platforms = [
 # from bazel/include/rust.MODULE.bazel
 # Rust configuration
 
-bazel_dep(name = "rules_rust", version = "0.66.0")
-single_version_override(
-    module_name = "rules_rust",
-    patch_strip = 1,
-    patches = [
-        "//bazel/patches:rules_rust.patch",
-    ],
-)
-
+bazel_dep(name = "rules_rust", version = "0.67.0")
 bazel_dep(name = "openssl", version = "3.3.1.bcr.6")
 
 RUST_EDITION = "2024"
@@ -513,23 +521,35 @@ python.toolchain(
     python_version = "3.12",
 )
 
+# We still use pip for testing the virtual deps machinery
 pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip", dev_dependency = True)
 pip.parse(
     hub_name = "django",
     python_version = "3.9",
     requirements_lock = "//py/tests/virtual/django:requirements.txt",
 )
-pip.parse(
+use_repo(pip, "django")
+
+# For everything else, we use our own uv machinery
+uv = use_extension("//uv/unstable:extension.bzl", "uv", dev_dependency = True)
+uv.declare_hub(
     hub_name = "pypi",
-    python_version = "3.9",
-    requirements_lock = "//:requirements.txt",
 )
-pip.parse(
+uv.declare_venv(
     hub_name = "pypi",
-    python_version = "3.12",
-    requirements_lock = "//:requirements.txt",
+    venv_name = "default",
 )
-use_repo(pip, "django", "pypi")
+uv.lockfile(
+    src = "//:uv.lock",
+    hub_name = "pypi",
+    venv_name = "default",
+)
+uv.unstable_annotate_requirements(
+    src = "//:annotations.toml",
+    hub_name = "pypi",
+    venv_name = "default",
+)
+use_repo(uv, "pypi")
 
 http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
 
@@ -556,13 +576,13 @@ http_file(
 
 ########################################
 # from bazel/include/release.MODULE.bazel
-bazel_dep(name = "with_cfg.bzl", version = "0.11.0")
 bazel_dep(name = "rules_pkg", version = "1.1.0")
 
 ########################################
 # from bazel/include/multitool.MODULE.bazel
 # Multitool configuration
 
+# Multitool is a prod dep (for now) so we don't need this
 bazel_dep(name = "rules_multitool", version = "1.9.0")
 
 multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")

README.md

@@ -1,20 +1,20 @@
 # Aspect's Bazel rules for Python
 
-`aspect_rules_py` is a layer on top of `rules_python`, the standard Python ruleset hosted at
-https://github.com/bazelbuild/rules_python.
-The lower layer of `rules_python` is currently reused, dealing with the toolchain and dependencies.
+`aspect_rules_py` is a layer on top of [rules_python](https://github.com/bazel-contrib/rules_python), the reference Python ruleset.
 
-However, this ruleset introduces a new implementation of `py_library`, `py_binary`, and `py_test`.
+The lower layer of `rules_python` is currently reused, dealing with interpreter toolchains and other details.
+
+However, this ruleset introduces new implementations of `py_library`, `py_binary`, `py_test` and now `uv`.
 Our philosophy is to behave more like idiomatic python ecosystem tools, where rules_python is closely
 tied to the way Google does Python development in their internal monorepo, google3.
 However we try to maintain compatibility with rules_python's rules for most use cases.
 
-| Layer                                       | Legacy       | Recommended          |
-| ------------------------------------------- | ------------ | -------------------- |
-| toolchain: fetch hermetic interpreter       | rules_python | rules_python         |
-| pip.parse: fetch and install deps from pypi | rules_python | rules_python         |
-| gazelle: generate BUILD files               | rules_python | [`aspect configure`] |
-| rules: user-facing implementations          | rules_python | **rules_py**         |
+| Layer                                 | Legacy       | Recommended             |
+| ------------------------------------- | ------------ | ----------------------- |
+| toolchain: fetch hermetic interpreter | rules_python | rules_python            |
+| deps: fetch and install from pypi     | rules_python | **aspect_rules_py//uv** |
+| rules: user-facing implementations    | rules_python | **aspect_rules_py//py** |
+| gazelle: generate BUILD files         | rules_python | [`aspect configure`]    |
 
 [`aspect configure`]: https://docs.aspect.build/cli/commands/aspect_configure
 

annotations.toml

@@ -0,0 +1,42 @@
+## Annotations.toml
+#
+# This is an aspect_rules_py//uv specific configuration file which allows
+# packages to be annotated with their build time dependencies. This fills a gap in
+# both the pylock and uv lockfile formats, neither of which allow for build
+# requirements to be specified.
+#
+# For instance if a package requires cython be available, this is how you can
+# configure it to be delivered.
+#
+# Takes the place of giant MODULE.bazel annotation tables.
+#
+# In future this machinery may allow for annotating requirements with
+# Bazel-managed dependencies (C libraries, etc.) by label. The exact semantics
+# there are TBD.
+
+# We version lockfiles and support semver semantics here
+version = "0.0.0"
+
+# Bravado doesn't have bdists, need to build it. Mark explicitly that we need
+# wheel setuptools and build in order to do so; build being the standard build
+# tool driver.
+[[package]]
+name = "bravado-core"
+build-dependencies = [
+   { name = "build" },
+   { name = "setuptools" },
+]
+
+# We can also annotate packages as providing console scripts we care about.
+# Declared console scripts will have Bazel targets generated for them.
+#
+# Unlike `rules_python` which sees post-install package contents,
+# `aspect_rules_py//uv` doesn't and so can't discover entrypoints to generate
+# Bazel targets ahead of time. They have to be predeclared if you want to
+# reference them as targets.
+[[package]]
+name = "pytest"
+
+[package.entry-points.console-scripts]
+pytest = "pytest:console_main"
+"py.test" = "pytest:console_main"

bazel/include/multitool.MODULE.bazel

@@ -1,5 +1,6 @@
 # Multitool configuration
 
+# Multitool is a prod dep (for now) so we don't need this
 bazel_dep(name = "rules_multitool", version = "1.9.0")
 
 multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")

bazel/include/python.MODULE.bazel

@@ -12,23 +12,35 @@ python.toolchain(
     python_version = "3.12",
 )
 
+# We still use pip for testing the virtual deps machinery
 pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip", dev_dependency = True)
 pip.parse(
     hub_name = "django",
     python_version = "3.9",
     requirements_lock = "//py/tests/virtual/django:requirements.txt",
 )
-pip.parse(
+use_repo(pip, "django")
+
+# For everything else, we use our own uv machinery
+uv = use_extension("//uv/unstable:extension.bzl", "uv", dev_dependency = True)
+uv.declare_hub(
     hub_name = "pypi",
-    python_version = "3.9",
-    requirements_lock = "//:requirements.txt",
 )
-pip.parse(
+uv.declare_venv(
     hub_name = "pypi",
-    python_version = "3.12",
-    requirements_lock = "//:requirements.txt",
+    venv_name = "default",
+)
+uv.lockfile(
+    src = "//:uv.lock",
+    hub_name = "pypi",
+    venv_name = "default",
+)
+uv.unstable_annotate_requirements(
+    src = "//:annotations.toml",
+    hub_name = "pypi",
+    venv_name = "default",
 )
-use_repo(pip, "django", "pypi")
+use_repo(uv, "pypi")
 
 http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
 

bazel/include/release.MODULE.bazel

@@ -1,2 +1 @@
-bazel_dep(name = "with_cfg.bzl", version = "0.11.0")
 bazel_dep(name = "rules_pkg", version = "1.1.0")