Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions .github/scripts/check_docs_parity.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Copyright 2026 Han Li and contributors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Checks that the Chinese documents keep the structure of the English ones.

The sentences are translated, so they are not compared. The checks are the ones a
reader trips over when the two languages drift apart:

- every English page has a Chinese page, and every Chinese page has an English one;
- both pages name the same VFOX_* environment variables;
- both pages have the same number of fenced code blocks;
- every relative link resolves from the folder of the page that holds it.

Run it from the repository root:

python3 -I .github/scripts/check_docs_parity.py .
"""

import pathlib
import re
import sys

FENCE = re.compile(r"^[ \t]*```[^\n]*\n(.*?)^[ \t]*```[ \t]*$", re.S | re.M)
ENV_NAME = re.compile(r"\bVFOX_[A-Z0-9_]+\b")
LINK = re.compile(r"\]\(([^)\s]+)")
SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")


def read(path):
return path.read_text(encoding="utf-8")


def page_pairs(root):
pairs = [(root / "README.md", root / "README_CN.md")]
for english in sorted((root / "docs").glob("*.md")):
pairs.append((english, root / "docs" / "zh-CN" / english.name))
return pairs


def relative_links(text):
# Code blocks can hold anything that looks like a link, so they are skipped.
for target in LINK.findall(FENCE.sub("", text)):
if SCHEME.match(target) or target.startswith("#"):
continue
yield target.split("#", 1)[0]


def check_pair(root, english, chinese, problems):
name = english.relative_to(root)
if not chinese.is_file():
problems.append(f"{name}: no Chinese page at {chinese.relative_to(root)}")
return 0

en_text = read(english)
zh_text = read(chinese)
en_env = set(ENV_NAME.findall(en_text))
zh_env = set(ENV_NAME.findall(zh_text))
for variable in sorted(en_env - zh_env):
problems.append(f"{name}: {variable} appears in the English page only")
for variable in sorted(zh_env - en_env):
problems.append(f"{name}: {variable} appears in the Chinese page only")

en_blocks = len(FENCE.findall(en_text))
zh_blocks = len(FENCE.findall(zh_text))
if en_blocks != zh_blocks:
problems.append(f"{name}: {en_blocks} code blocks in English, {zh_blocks} in Chinese")

for page in (english, chinese):
for target in relative_links(read(page)):
if not (page.parent / target).exists():
problems.append(f"{page.relative_to(root)}: the link to {target} does not exist")
return 1


def main(argv):
root = pathlib.Path(argv[1] if len(argv) > 1 else ".").resolve()
problems = []
checked = 0
for english, chinese in page_pairs(root):
checked += check_pair(root, english, chinese, problems)
for chinese in sorted((root / "docs" / "zh-CN").glob("*.md")):
if not (root / "docs" / chinese.name).is_file():
problems.append(f"{chinese.relative_to(root)}: no English page for it")

for problem in problems:
print(problem)
if problems:
return 1
print(f"Docs parity: {checked} pages checked, the English and Chinese pages agree.")
return 0


if __name__ == "__main__":
sys.exit(main(sys.argv))
10 changes: 10 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,13 @@ jobs:
run: mise x aqua:LuaLS/lua-language-server@3.19.1 -- lua-language-server --check . --checklevel=Warning
- name: Check workflow files
run: mise x aqua:rhysd/actionlint@1.7.7 -- actionlint

docs:
name: Docs in English and Chinese
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
persist-credentials: false
- name: Check that the Chinese pages match the English ones
run: python3 -I .github/scripts/check_docs_parity.py .
34 changes: 34 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,40 @@ jobs:
# its own and disables os.execute and io.popen until a test stubs them.
- name: Run the offline hook tests
run: vfox plugin test .
# On Windows, VFOX_PYTHON_USE_UV_BUILD=1 reads the uv-build index. A closed proxy
# fails every attempt at once, so the search must wait between attempts (through
# PowerShell), announce each retry, and then fail after three attempts.
- name: Check that index retries wait on Windows
if: runner.os == 'Windows'
shell: pwsh
env:
VFOX_HOME: ${{ runner.temp }}\vfox-retry-home
VFOX_PYTHON_USE_UV_BUILD: '1'
HTTPS_PROXY: 'http://127.0.0.1:1'
run: |
$ErrorActionPreference = 'Continue'
[System.IO.Directory]::CreateDirectory($env:VFOX_HOME) | Out-Null
$archive = Join-Path $env:RUNNER_TEMP 'python-plugin-retry.zip'
Compress-Archive -Path metadata.lua,hooks,lib -DestinationPath $archive
vfox add --source $archive
if ($LASTEXITCODE -ne 0) { throw "vfox add failed: $LASTEXITCODE" }
$watch = [System.Diagnostics.Stopwatch]::StartNew()
$output = vfox search python 2>&1
$exitCode = $LASTEXITCODE
$watch.Stop()
$text = [regex]::Replace(($output | Out-String), "\x1b\[[0-9;]*m", '')
Write-Output $text
if ($exitCode -eq 0) { throw 'vfox search python succeeded through a closed proxy' }
if ($text -notmatch 'Status: none') { throw 'the index failure was not a transport error' }
if ($text -notmatch 'after 3 attempts') { throw 'the index failure does not report three attempts' }
$retries = ([regex]::Matches($text, 'Trying again')).Count
if ($retries -lt 2) { throw "expected at least two retries, saw $retries" }
$seconds = $watch.Elapsed.TotalSeconds
if ($seconds -lt 3) { throw "the retries did not wait: the search took $seconds seconds" }
Write-Output "Index retries waited for $([math]::Round($seconds, 1)) seconds in all"
# The search above is meant to fail. Its exit code stays in $LASTEXITCODE, which
# the runner reads, so the step states its own result once every check holds.
exit 0

layouts:
name: Windows installer command layouts
Expand Down
36 changes: 24 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@

Python plugin for [vfox](https://vfox.dev/).

It installs CPython from python.org, compiles CPython from source on Linux and
macOS, or downloads a prebuilt uv-build archive. GraalPy comes from Oracle's
It installs CPython from python.org on Windows. On Linux and macOS it downloads a
prebuilt uv-build archive when one exists, and compiles CPython from source
otherwise. GraalPy comes from Oracle's
release archives on every supported platform. It also adopts the Pythons
already on the machine — system packages, uv, pyenv, Conda and others — and
reads a project's `.python-version`, so pyenv and uv projects open on the
Expand Down Expand Up @@ -52,14 +53,15 @@ The available versions depend on the platform:

| Platform | Default source | Versions |
| --- | --- | --- |
| Linux | pyenv source build for CPython; Oracle archive for GraalPy | every release pyenv knows, including GraalPy, PyPy and Conda |
| macOS | pyenv source build for CPython; Oracle archive for GraalPy | every release pyenv knows, including GraalPy, PyPy and Conda |
| Linux | uv-build archive for CPython when the index has the version, otherwise a pyenv source build; Oracle archive for GraalPy | every release pyenv knows, including GraalPy, PyPy and Conda, plus CPython releases only uv-build lists |
| macOS | uv-build archive for CPython when the index has the version, otherwise a pyenv source build; Oracle archive for GraalPy | every release pyenv knows, including GraalPy, PyPy and Conda, plus CPython releases only uv-build lists |
| Windows | python.org installer for CPython; Oracle zip for GraalPy | stable CPython installers for the architecture, plus GraalPy amd64 releases |

On Windows, source-only security releases and pre-release or free-threaded
CPython builds are left out because python.org's stable installer names do not
cover them. `VFOX_PYTHON_USE_UV_BUILD=1` switches to prebuilt uv-build archives
on Linux, macOS and Windows; uv-build contains CPython only. See
cover them. `VFOX_PYTHON_USE_UV_BUILD=0` builds every CPython from source on
Linux and macOS, and `VFOX_PYTHON_USE_UV_BUILD=1` uses prebuilt uv-build archives
only, on Linux, macOS and Windows; uv-build contains CPython only. See
[docs/uv.md](docs/uv.md).

`py.exe` does not read `PATH`. Windows installs are registered automatically
Expand Down Expand Up @@ -120,16 +122,26 @@ echo graalpy-24.2.0 > .python-version

## uv

uv-build is the optional prebuilt source. `python@3.12` installs the newest 3.12
release in its index:
On Linux and macOS, a CPython install takes the prebuilt uv-build archive when the
index lists the version, so it needs no compiler or build dependencies. The index
lists only some releases, normally the newest patch of each line, so an older
patch builds from source with pyenv, as does a version the index does not list.
GraalPy comes from Oracle's archive; PyPy and Conda build from source with pyenv.
A partial name such as `python@3.12` picks the newest 3.12 that the index lists, and
installs its archive. Only a line the index does not list falls back to the newest
match in `vfox search python`, which is built from source. To build a newer patch
that the index does not list yet, name its exact version:

```bash
export VFOX_PYTHON_USE_UV_BUILD=1
vfox install python@3.12
vfox install python@3.12 # newest 3.12 in the uv-build index, as an archive
vfox install python@3.12.16 # exactly 3.12.16
```

uv-build needs no compiler or build dependencies. On Linux the libc is
detected automatically; set `VFOX_PYTHON_UV_LIBC=gnu` or
Set `VFOX_PYTHON_USE_UV_BUILD=0` to always build from source, or
`VFOX_PYTHON_USE_UV_BUILD=1` to use uv-build only, which fails for a version the
index does not list. If `VFOX_PYTHON_MIRROR` is set, CPython keeps its source
build on that mirror, unless `VFOX_PYTHON_UV_BUILD_MIRROR` is set too. On Linux the
libc is detected automatically; set `VFOX_PYTHON_UV_LIBC=gnu` or
`VFOX_PYTHON_UV_LIBC=musl` to override it. uv-managed Pythons from
`uv python install` are picked up by `vfox link --detect python` like any other
installation. See [docs/uv.md](docs/uv.md) for the archive and for how to make
Expand Down
25 changes: 14 additions & 11 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

[vfox](https://vfox.dev/) 的 Python 插件。

它可以从 python.org 安装 CPython,在 Linux 和 macOS 上从源码编译 CPython,也
可以下载 uv-build 的预编译包。GraalPy 在所有支持的平台上都来自 Oracle 发布的
它在 Windows 上从 python.org 安装 CPython。在 Linux 和 macOS 上,有对应的 uv-build
预编译包时下载它,否则从源码编译 CPython。GraalPy 在所有支持的平台上都来自 Oracle 发布的
压缩包。它还能纳入本机已有的 Python——系统包管理器、uv、pyenv、Conda 等等——
并读取项目里的 `.python-version`,让为 pyenv 和 uv 写的项目按文件里写的版本
打开。
Expand Down Expand Up @@ -48,14 +48,15 @@ vfox install python@graalpy-24.2.0

| 平台 | 默认来源 | 版本范围 |
| --- | --- | --- |
| Linux | CPython 用 pyenv 从源码编译;GraalPy 用 Oracle 压缩包 | pyenv 收录的全部版本,包括 GraalPy、PyPy 和 Conda |
| macOS | CPython 用 pyenv 从源码编译;GraalPy 用 Oracle 压缩包 | pyenv 收录的全部版本,包括 GraalPy、PyPy 和 Conda |
| Linux | CPython 在 uv-build 索引列出该版本时用 uv-build 预编译包,否则用 pyenv 从源码编译;GraalPy 用 Oracle 压缩包 | pyenv 收录的全部版本,包括 GraalPy、PyPy 和 Conda,以及只有 uv-build 列出的 CPython 版本 |
| macOS | CPython 在 uv-build 索引列出该版本时用 uv-build 预编译包,否则用 pyenv 从源码编译;GraalPy 用 Oracle 压缩包 | pyenv 收录的全部版本,包括 GraalPy、PyPy 和 Conda,以及只有 uv-build 列出的 CPython 版本 |
| Windows | CPython 用 python.org 安装包;GraalPy 用 Oracle 压缩包 | 当前架构的稳定 CPython 安装包,以及 GraalPy 的 amd64 版本 |

Windows 上,python.org 没有为仅提供源码的安全版本发布安装包,稳定的安装包名也
覆盖不了预发布版和自由线程的 CPython 构建,所以这些版本不在列表里。设置
`VFOX_PYTHON_USE_UV_BUILD=1` 后,Linux、macOS 和 Windows 都改为下载 uv-build
的预编译包;uv-build 只包含 CPython。详见
`VFOX_PYTHON_USE_UV_BUILD=0` 后,Linux 和 macOS 上的每个 CPython 都从源码编译;设置
`VFOX_PYTHON_USE_UV_BUILD=1` 后,只使用 uv-build 的预编译包,适用于 Linux、macOS 和
Windows;uv-build 只包含 CPython。详见
[docs/zh-CN/uv.md](docs/zh-CN/uv.md)。

`py.exe` 不读取 `PATH`。Windows 上的安装会自动注册到 vfox 自己的 PEP 514
Expand Down Expand Up @@ -114,15 +115,17 @@ echo graalpy-24.2.0 > .python-version

## uv

uv-build 是可选的预编译来源。`python@3.12` 会安装它的索引里最新的 3.12 版本:
在 Linux 和 macOS 上,CPython 安装在 uv-build 索引列出该版本时使用它的预编译包,因此不需要编译器或构建依赖。
索引只列出部分版本,通常是每个版本线的最新补丁版,所以较旧的补丁版会用 pyenv 从源码编译,索引没有列出的版本也是如此。GraalPy 来自 Oracle 的压缩包;PyPy 和 Conda 用 pyenv 从源码编译。部分版本号(如 `python@3.12`)会先在 uv-build 索引里选出最新的 3.12 版本,并安装它的预编译包。只有索引没有列出的版本系列,才会改为选中 `vfox search python` 列出的、最新的匹配版本,并从源码编译。要编译索引里还没有的较新补丁版,请写出它的精确版本号:

```bash
export VFOX_PYTHON_USE_UV_BUILD=1
vfox install python@3.12
vfox install python@3.12 # uv-build 索引里最新的 3.12,安装预编译包
vfox install python@3.12.16 # 精确的 3.12.16
```

uv-build 不需要编译器或构建依赖。Linux 上会自动识别 libc;要覆盖识别结果,
设置 `VFOX_PYTHON_UV_LIBC=gnu` 或 `VFOX_PYTHON_UV_LIBC=musl`。
设置 `VFOX_PYTHON_USE_UV_BUILD=0` 可以始终从源码编译;设置 `VFOX_PYTHON_USE_UV_BUILD=1` 则只使用 uv-build,索引里没有列出的版本会失败。若设置了 `VFOX_PYTHON_MIRROR`,CPython 的源码构建会继续经由该镜像,除非同时设置了 `VFOX_PYTHON_UV_BUILD_MIRROR`。
Linux 上会自动识别 libc;要覆盖识别结果,设置 `VFOX_PYTHON_UV_LIBC=gnu` 或
`VFOX_PYTHON_UV_LIBC=musl`。
`uv python install` 装的 Python 和别的安装一样,会被
`vfox link --detect python` 找到。预编译包的细节,以及怎样让 uv 使用 vfox
选中的解释器而不是再下载一份,见
Expand Down
26 changes: 26 additions & 0 deletions docs/changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,32 @@

## Unreleased

- Index requests to the uv-build and pyenv indexes are sent again on a network error,
HTTP 429, a 5xx, or a 200 response that is not the index: up to three attempts in
all. The wait follows the server's `Retry-After` in seconds when it is at most ten,
and otherwise one second and then two. A failure that persists still fails the
install; the default mode does not fall back to a source build for it.
- The uv-build index and pyenv version lists are sorted newest first with one
comparator. With `VFOX_PYTHON_USE_UV_BUILD=1`, the list used to keep the order
the index returned, so `latest` depended on that order. The pyenv list compared
a name with a suffix, such as `3.13.18t`, as if it were `3.13.0`. `latest` now
picks the newest standard release and skips free-threaded builds, which are
installed only when named.
- On Linux and macOS, `vfox install python@<version>` now installs a CPython
release from its prebuilt uv-build archive when the uv-build index lists it,
and builds from source only when the index does not. Set
`VFOX_PYTHON_USE_UV_BUILD=0` to keep building every CPython from source, or
`VFOX_PYTHON_USE_UV_BUILD=1` to use uv-build only. GraalPy, PyPy and Conda
installs are unchanged. `vfox search python` lists the pyenv names together
with the CPython releases only uv-build lists. Installs made before this
change are not touched. A `VFOX_PYTHON_MIRROR` setting keeps CPython on the
source path, unless `VFOX_PYTHON_UV_BUILD_MIRROR` is set too.
- In the default mode on Linux and macOS, a partial name such as `python@3.12`
resolves in the uv-build index first, so it installs the newest 3.12 that has an
archive. An exact name still selects any release, including a newer pyenv patch
that the index does not list.
- When the pyenv version index cannot be read, the error names the HTTP status
instead of failing with a Lua concatenation error.
- A partial version such as `python@3.12` now selects a linked install named
with `-opt`, such as `3.12.8-opt`, and `python@3.13t` selects a linked
free-threaded install, such as `3.13.1t-uv`. The source suffix is no longer
Expand Down
Loading
Loading