Skip to content

feat: add GraalPy, partial Python versions and py.exe registration - #51

Merged
linghengqian merged 13 commits into
mainfrom
feat/graalpy-support
Nov 13, 2026
Merged

linghengqian merged 13 commits into
mainfrom
feat/graalpy-support

Conversation

@linghengqian

@linghengqian linghengqian commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR makes GraalPy a first-class distribution, makes partial Python versions such as python@3.12 work for install and use, and registers Windows installs with the Python launcher (py.exe) by default. It also moves the E2E suites into Go and adds Linux and Windows container tests.

What changed

GraalPy

  • Installs GraalPy built on Oracle GraalVM and GraalPy Community from Oracle's official archives on Linux (amd64, arm64), macOS (amd64, arm64) and Windows (amd64).
  • On Windows, releases come from the GitHub API, with a constructed asset URL when the API is rate limited. Archives are checked against Oracle's .sha256 file.
  • On Unix, the archive's bundled ensurepip runs and the pip launcher is created. bin and Scripts are added to PATH.
  • vfox link --detect python adopts existing GraalPy installs as graalpy[-community][<python>]-<release>-<source>. .python-version accepts GraalPy names, and uv-build mode rejects GraalPy with a clear message.

Partial versions

  • python@3.12 resolves in vfox install and vfox use in every mode. Install picks the newest stable release that the mode lists (pyenv, python.org or the uv-build index). Use picks the newest installed match. The rules live in lib/python_version.lua.
  • A plain request never picks a free-threaded (t) or pre-release build. 3.13t picks only free-threaded builds.
  • uv-build installs are recorded under their full version.

Windows

  • Installs are registered with py.exe through PEP 514, under HKCU\Software\Python\VersionFox. Set VFOX_PYTHON_REGISTER_PY_LAUNCHER=0 to opt out. The plugin never writes PythonCore.
  • MSI installs create the same python3 aliases as EXE installs. The MSI pip step captures the interpreter's output and prints it, with diagnostics when the step fails.
  • Old MSI releases such as 3.4.4 need the Visual C++ 2010 runtime (msvcr100.dll). docs/platforms.md has the install command.

E2E and docs

  • The E2E suites moved from workflow shell into Go, in tests/e2e (common, linux, windows). .github/workflows/e2e.yml only installs Go and runs go test.
  • The Linux container suite runs a bare Ubuntu 24.04 image: uv-build without build packages, plus GraalPy 24.2.0 and Community 24.2.0. The Windows container suite runs a Server Core image with GraalPy 25.5.5 Community. It drives the docker CLI directly, because testcontainers creates a bridge network that Windows engines do not have.
  • English and Chinese docs cover platforms, versions, uv, E2E, changes and the Windows launcher, and the READMEs are updated.
  • .licenserc.yaml ignores go.sum, since Go does not allow comments in it. The unused .github/select-uv-version.py is removed.

Behavior changes

  • Windows installs are registered with py.exe by default. On main this was opt-in.
  • python@3.12-style requests now resolve in install and use. Exact versions behave as before.
  • MSI installs now create python3 aliases.

Testing

CI passes on 46e0051:

  • E2E on Linux: the native suite (source build, mirror, uv-build, GraalPy, vfox link --detect, .python-version) and the container suite.
  • E2E on Windows: the native suite (python.org EXE installer, MSI 3.4.4, mirror, uv-build, GraalPy with its py -0p entry, .python-version) and the Server Core container.
  • Lua format and diagnostics, plugin tests on Ubuntu and Windows, Windows installer layout tests and paths, license headers, and check.

Local checks: gofmt, go vet for Linux and Windows, stylua --check, vfox plugin test ., LuaLS (no problems), and actionlint.

Notes for reviewers

  • Old MSI releases install only when the Visual C++ 2010 runtime is present. The MSI subtest installs it on CI and skips with a reason elsewhere.
  • Linux source builds need the apt packages listed under "Linux build dependencies" in docs/platforms.md. uv-build needs none.
  • Oracle does not publish GraalPy for Windows arm64 or 386, and uv-build stays CPython-only.

Fixes #25

- install Oracle GraalVM and Community GraalPy builds from Oracle's
  release archives on Linux, macOS and Windows amd64
- list GraalPy versions on Windows from the GitHub releases API, with a
  constructed-URL fallback when the API is rate-limited
- bootstrap pip from the bundled ensurepip and add the pip launcher
- register Windows GraalPy installs with PEP 514 and expose the correct
  PATH entries
- detect existing GraalPy installations in `vfox link --detect`
- reject GraalPy in uv-build mode with a clear message
- add offline tests and Linux/Windows E2E coverage
- document GraalPy versions, platform limits, licensing and link support

Refs #25
- add tests/e2e/linux with an Ubuntu 24.04 image that installs vfox
  and the plugin, downloads GraalPy, and checks python, pip and
  .python-version
- add tests/e2e/windows with a Windows Server Core image, PowerShell 7,
  vfox and the same GraalPy checks
- run the Linux image for Oracle and Community GraalPy 24.2.0 and the
  Windows image for graalpy3.13-community-25.5.5
- retry transient GitHub release download failures
- document the container suite in docs/e2e.md and update the development
  and changes pages
- refresh the pwsh/bash environment with `vfox env` after selecting the
  GraalPy version, so python resolves to the vfox shim instead of the
  runner's preinstalled CPython
- move vfox.exe out of the zip's top-level directory in the Windows
  container image
- compare only sys.implementation.name on the Windows runner; GraalPy's
  sys.version contains a newline, so the previous wildcard check saw an
  array
- set TEMP/TMP in the Server Core image for GraalPy's ensurepip
- retry ensurepip through cmd when the PowerShell wrapper fails, and print
  an interpreter/TEMP diagnostic if it still fails
The Python launcher reads the install path and executable from the
InstallPath subkey, not from values on the company/tag key. Move the
default path, ExecutablePath and WindowedExecutablePath there and keep
DisplayName, SysVersion, SysArchitecture and VfoxManaged on the tag key.
Uninstall reads the new subkey and falls back to the old layout.
GraalPy's native launcher loads pythonvm.dll, which depends on the Visual
C++ runtime. Server Core does not include it, so python.exe fails with
"Could not load VM library" before ensurepip can run.
`py -0p` returns one line per installation. PowerShell treats the output
as an array, and -notmatch then returns every line that does not match,
so the GraalPy tag was reported missing even when it was listed. Join the
lines first.
@linghengqian linghengqian added the enhancement New feature or request label Nov 13, 2026
Move the E2E scenarios into tests/e2e as Go tests: a native suite and a
container suite for Linux and for Windows. The E2E workflow now only
installs Go and runs go test in each package.

- Windows installs are registered under HKCU\Software\Python\VersionFox
  by default. VFOX_PYTHON_REGISTER_PY_LAUNCHER=0 (or false, no, off)
  turns registration off; uninstall still removes existing entries.
- The Linux container suite installs uv-build in a bare Ubuntu 24.04
  image with no build packages and imports the stdlib modules that need
  them, so uv-build is checked to need no apt packages. The GraalPy
  containers check that .python-version selects the uv-build CPython
  over the global GraalPy.
- The .python-version subtests select the installed uv-build CPython
  instead of a source build that the runner may not have.
- The Windows installer subtest asserts that python.org's EXE is used.
- Document the EXE and MSI choice with python.org examples, the Linux
  build packages for each install path, and py.exe selection rules and
  use cases.
- Remove .github/select-uv-version.py; the Go suite picks the version.
A partial version such as python@3.12 reached PreInstall and PreUse as the
literal "3.12", so vfox install and vfox use failed in every mode, although
the docs promise the newest matching release. Resolve it in one place:

- PreInstall resolves a partial request against the version list of the
  active mode: pyenv, python.org on Windows, or the uv-build index. An exact
  name is not looked up.
- PreUse resolves it against the installed names, so vfox use python@3.12
  selects the newest installed 3.12.x. A bare name beats the same release
  with a source suffix such as -system.
- A partial request never selects a pre-release, a plain request never
  selects a free-threaded build (3.13 is not 3.13t), and the request must end
  at a dot (3.1 does not match 3.10).

Windows MSI installs now create the same python3 aliases as the EXE route.

The E2E suites install and use the uv-build release by its minor version,
and the Windows suite installs python.org's MSI-only 3.4.4. Offline tests
cover the matcher and the PreInstall and PreUse hooks, and the Windows layout
test covers the MSI commands and the installer choice.
- The Windows container suite sets DOCKER_HOST to the runner's Docker named
  pipe. testcontainers otherwise reports every Windows host as rootless and
  refuses to start, so the container test never ran in CI.
- The MSI route runs ensurepip with its output written to files, so a
  failure prints the interpreter's own error text. The MSI-only 3.4.4 failed
  there with no visible output.
- license-eye ignores go.sum, which Go does not allow to carry comments.
- The Windows container suite asks the docker CLI for its engine endpoint
  and passes it to testcontainers. The runner's engine is not on the default
  named pipe, so testcontainers could not connect and the container suite
  never ran.
- The MSI route runs ensurepip with its output written to files. A failure
  prints the interpreter's exit code and what the install root holds. The
  MSI-only 3.4.4 failed there with no visible output before this change.
- The layout test decodes long PowerShell scripts in chunks.
…VC++ 2010 runtime

- The Windows container suite calls docker build, run, cp and exec directly.
  testcontainers-go creates a bridge network for every container, and a
  Windows engine has no bridge driver, so the suite could not start.
- The MSI subtest installs the Visual C++ 2010 x64 redistributable on CI when
  msvcr100.dll is missing. The admin install of CPython 3.4.4 does not put
  that runtime in System32, so python.exe exits with 0xC0000135 without it.
- The MSI pip step prints a hint when the interpreter exits with -1073741515.
- The docs describe the runtime requirement and the docker CLI route.
- The Windows container's init command was a bare `powershell`, which the
  runner could not start ("The system cannot find the file specified"). The
  image's CMD and the docker exec process now name pwsh by its full path, as
  the earlier Windows container entrypoint did.
- The image's PATH names System32 explicitly, so the tools inside the container
  resolve even when the base image's PATH is not expanded.
@linghengqian linghengqian changed the title feat: support GraalPy distributions feat: add GraalPy, partial Python versions and py.exe registration Nov 13, 2026
@linghengqian
linghengqian merged commit 209f7ba into main Nov 13, 2026
10 checks passed
@linghengqian
linghengqian deleted the feat/graalpy-support branch November 13, 2026 14:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Providing distributions of GraalPy Community and GraalPy built on Oracle GraalVM like pyenv

1 participant