Add PyPy finder (#5337)

## Summary

This PR adds PyPy finder and adds PyPy to uv managed Python versions.

## Test Plan

```console
$ cargo run -- python install
```

.github/workflows/ci.yml

@@ -579,10 +579,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "pypy3.9"
-
       - name: "Download binary"
         uses: actions/download-artifact@v4
         with:
@@ -591,12 +587,12 @@ jobs:
       - name: "Prepare binary"
         run: chmod +x ./uv
 
-      - name: PyPy info
+      - name: "Install PyPy"
-        run: which pypy
+        run: ./uv python install pypy3.9
 
       - name: "Create a virtual environment"
         run: |
-          ./uv venv -p $(which pypy)
+          ./uv venv -p pypy3.9 --python-preference only-managed
 
       - name: "Check for executables"
         run: |
@@ -645,22 +641,17 @@ jobs:
     runs-on: windows-latest
 
     steps:
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "pypy3.9"
-
       - name: "Download binary"
         uses: actions/download-artifact@v4
         with:
           name: uv-windows-${{ github.sha }}
 
-      - name: PyPy info
+      - name: "Install PyPy"
-        run: Get-Command pypy
+        run: .\uv.exe python install pypy3.9
 
       - name: "Create a virtual environment"
         run: |
-          $pypy = (Get-Command pypy).source
+          .\uv.exe venv -p pypy3.9 --python-preference only-managed
-          .\uv.exe venv -p $pypy
 
       - name: "Check for executables"
         shell: python

crates/uv-python/fetch-download-metadata.py

@@ -322,6 +322,96 @@ class CPythonFinder(Finder):
         return pref
 
 
+class PyPyFinder(Finder):
+    implementation = ImplementationName.PYPY
+
+    RELEASE_URL = "https://raw.githubusercontent.com/pypy/pypy/main/pypy/tool/release/versions.json"
+    CHECKSUM_URL = (
+        "https://raw.githubusercontent.com/pypy/pypy.org/main/pages/checksums.rst"
+    )
+
+    _checksum_re = re.compile(
+        r"^\s*(?P<checksum>\w{64})\s+(?P<filename>pypy.+)$", re.MULTILINE
+    )
+
+    ARCH_MAPPING = {
+        "x64": "x86_64",
+        "x86": "i686",
+        "i686": "i686",
+        "aarch64": "aarch64",
+        "arm64": "aarch64",
+        "s390x": "s390x",
+    }
+
+    PLATFORM_MAPPING = {
+        "win32": "windows",
+        "win64": "windows",
+        "linux": "linux",
+        "darwin": "darwin",
+    }
+
+    def __init__(self, client: httpx.AsyncClient):
+        self.client = client
+
+    async def find(self) -> list[PythonDownload]:
+        downloads = await self._fetch_downloads()
+        await self._fetch_checksums(downloads)
+        return downloads
+
+    async def _fetch_downloads(self) -> list[PythonDownload]:
+        resp = await self.client.get(self.RELEASE_URL)
+        resp.raise_for_status()
+        versions = resp.json()
+
+        results = {}
+        for version in versions:
+            if not version["stable"]:
+                continue
+            python_version = Version.from_str(version["python_version"])
+            if python_version < (3, 7, 0):
+                continue
+            for file in version["files"]:
+                arch = self._normalize_arch(file["arch"])
+                platform = self._normalize_os(file["platform"])
+                libc = "gnu" if platform == "linux" else "none"
+                download = PythonDownload(
+                    version=python_version,
+                    triple=PlatformTriple(
+                        arch=arch,
+                        platform=platform,
+                        libc=libc,
+                    ),
+                    flavor="",
+                    implementation=self.implementation,
+                    filename=file["filename"],
+                    url=file["download_url"],
+                )
+                # Only keep the latest pypy version of each arch/platform
+                if (python_version, arch, platform) not in results:
+                    results[(python_version, arch, platform)] = download
+
+        return list(results.values())
+
+    def _normalize_arch(self, arch: str) -> str:
+        return self.ARCH_MAPPING.get(arch, arch)
+
+    def _normalize_os(self, os: str) -> str:
+        return self.PLATFORM_MAPPING.get(os, os)
+
+    async def _fetch_checksums(self, downloads: list[PythonDownload]) -> None:
+        logging.info("Fetching PyPy checksums")
+        resp = await self.client.get(self.CHECKSUM_URL)
+        resp.raise_for_status()
+        text = resp.text
+
+        checksums = {}
+        for match in self._checksum_re.finditer(text):
+            checksums[match.group("filename")] = match.group("checksum")
+
+        for download in downloads:
+            download.sha256 = checksums.get(download.filename)
+
+
 def render(downloads: list[PythonDownload]) -> None:
     """Render `download-metadata.json`."""
 
@@ -371,9 +461,9 @@ async def find() -> None:
         headers["Authorization"] = "Bearer " + token
     client = httpx.AsyncClient(follow_redirects=True, headers=headers, timeout=15)
 
-    # TODO: Add PyPyFinder
     finders = [
         CPythonFinder(client),
+        PyPyFinder(client),
     ]
     downloads = []
 

crates/uv-python/src/managed.rs

@@ -314,15 +314,23 @@ impl ManagedPythonInstallation {
     /// standard `EXTERNALLY-MANAGED` file.
     pub fn ensure_externally_managed(&self) -> Result<(), Error> {
         // Construct the path to the `stdlib` directory.
-        let stdlib = if cfg!(windows) {
+        let stdlib = if matches!(self.key.os, Os(target_lexicon::OperatingSystem::Windows)) {
             self.python_dir().join("Lib")
         } else {
-            self.python_dir()
+            let python = if matches!(
-                .join("lib")
+                self.key.implementation,
-                .join(format!("python{}", self.key.version().python_version()))
+                LenientImplementationName::Known(ImplementationName::PyPy)
+            ) {
+                format!("pypy{}", self.key.version().python_version())
+            } else {
+                format!("python{}", self.key.version().python_version())
+            };
+            self.python_dir().join("lib").join(python)
         };
+
         let file = stdlib.join("EXTERNALLY-MANAGED");
         fs_err::write(file, EXTERNALLY_MANAGED)?;
+
         Ok(())
     }
 }

crates/uv-python/template-download-metadata.py

@@ -35,6 +35,8 @@ def prepare_name(name: str) -> str:
     match name:
         case "cpython":
             return "CPython"
+        case "pypy":
+            return "PyPy"
         case _:
             raise ValueError(f"Unknown implementation name: {name}")
 

docs/python-versions.md

@@ -24,12 +24,12 @@ Many Python version request formats are supported:
 - `<implementation><version-specifier>` e.g. `cpython>=3.12,<3.13`
 - `<implementation>-<version>-<os>-<arch>-<libc>` e.g. `cpython-3.12.3-macos-aarch64-none`
 
-At this time, only CPython downloads are supported. However, PyPy support is planned.
-
 ## Installing a Python version
 
 Sometimes it is preferable to install the Python versions before they are needed.
 
+uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.
+
 To install a Python version at a specific version:
 
 ```bash
@@ -122,8 +122,10 @@ If a specific Python version is requested, e.g. `--python 3.7`, additional execu
 
 ## Python distributions
 
-Python does not publish official distributable binaries, uv uses third-party standalone distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects.
+Python does not publish official distributable CPython binaries, uv uses third-party standalone distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects.
 
 The Python distributions are self-contained and highly-portable. Additionally, these distributions have various build-time optimizations enabled to ensure they are performant.
 
 These distributions have some behavior quirks, generally as a consequence of portability. See the [`python-build-standalone` quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for details. 
+
+PyPy distributions are provided by the PyPy project.