Scope default xbuildenv caches per pyodide-build installation

[Copilot]

The default xbuildenv cache layout currently drops versioned directories directly into the user cache, which leaves stray top-level folders behind and causes different pyodide-build installations to reuse the same cache root. This change moves xbuildenvs under a dedicated pyodide-build cache directory and scopes the default root to the active installation.

• Cache layout

  • Switch the default root from:
    • platformdirs.user_cache_dir() / ".pyodide-xbuildenv-<version>"
  • To:
    • platformdirs.user_cache_dir("pyodide-build") / ".pyodide-xbuildenv-<install-id>"
  • Keep downloaded xbuildenv versions nested under that root, so the on-disk layout becomes a single per-installation cache directory containing multiple version directories.

• Installation scoping

  • Replace the version-based default directory name with a stable installation-scoped identifier.
  • The identifier is derived from the current Python environment and the installed pyodide_build package location, so separate virtual environments and separate source installs do not share the same default xbuildenv root.
  • This avoids the persistence problem a random UUID would introduce while still isolating installations.

• Docs and tests

  • Update path expectations in the xbuildenv path tests.
  • Add coverage for stable installation scoping.
  • Refresh the xbuildenv docs to describe the new default cache layout.

Example default layout:

from pathlib import Path
import platformdirs

cache_root = Path(platformdirs.user_cache_dir("pyodide-build"))
default_xbuildenv_root = cache_root / ".pyodide-xbuildenv-<install-id>"

# downloaded versions live under the per-installation root
# e.g.
# ~/.cache/pyodide-build/.pyodide-xbuildenv-<install-id>/0.29.4

[agriyakhetarpal]

@copilot, fix the linting issues in https://results.pre-commit.ci/run/github/809763431/1780948591.EoyxRmlGR2CFBmvU-bNhBg

[Copilot]

@copilot, fix the linting issues in https://results.pre-commit.ci/run/github/809763431/1780948591.EoyxRmlGR2CFBmvU-bNhBg

Fixed in 3d85404.

[agriyakhetarpal]

@copilot, could you confirm whether it is also necessary to include the Pyodide Python version and Pyodide ABI version in the hash, or whether they are not necessary?

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[Copilot]

@agriyakhetarpal Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 6344d112-6bcf-4723-af00-1795be1cde04

Sorry for the inconvenience!

[agriyakhetarpal]

I wonder if I just used up whatever credits are available on the free plan or something 😅

[Copilot]

@copilot, could you confirm whether it is also necessary to include the Pyodide Python version and Pyodide ABI version in the hash, or whether they are not necessary?

I don’t think they need to be part of the install-id hash.

The hash is only for scoping the cache root to a specific pyodide-build installation (sys.prefix + installed package location in pyodide_build/common.py), and the actual xbuildenv payloads are already isolated by version subdirectories under that root. Python compatibility is already enforced when selecting a release (CrossBuildEnvReleaseSpec.is_compatible in pyodide_build/xbuildenv_releases.py) and again when reusing an installed env via the .build-python-version marker (version_marker_matches in pyodide_build/xbuildenv.py).

The Pyodide ABI is a property of the chosen xbuildenv version/config inside those versioned directories, not of the cache root itself, so including it in the hash would mostly just split one installation’s cache unnecessarily.

[agriyakhetarpal]

Since Copilot was tripping up, I also checked manually locally (so much for a brain these days! 😂) and confirmed that xbuildenvs will not clobber over each other with differences in ABI versions, both through code and testing with a few variations of venvs.

[ryanking13]

Sounds okay to me. Thanks!