Release: merge release into main

tools/check_guide.py → .github/scripts/check_guide.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Checks the bilingual GitHub Pages guide in docs/guide/.
 
-    python3 tools/check_guide.py [guide-dir]
+    python3 .github/scripts/check_guide.py [guide-dir]
 
 Fails (exit 1) when:
   1. an HTML file does not parse into balanced elements;
@@ -153,7 +153,7 @@ def check(guide):
 
 def main():
     here = os.path.dirname(os.path.abspath(__file__))
-    guide = sys.argv[1] if len(sys.argv) > 1 else os.path.join(here, "..", "docs", "guide")
+    guide = sys.argv[1] if len(sys.argv) > 1 else os.path.join(here, "..", "..", "docs", "guide")
     failures = check(guide)
     for f in failures:
         print("FAIL", f)

.github/scripts/ft-mobile/build-android.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Build free-threaded CPython (--disable-gil) for aarch64-linux-android with
+# CPython's own tooling (Platforms/Android). Usage: build-android.sh [VERSION]
+# Needs ANDROID_HOME (SDK with cmdline-tools/latest) and a JDK 17, 21 or 25.
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$here/common.sh"
+
+PY_VERSION="${1:-3.15.0}"
+HOST=aarch64-linux-android
+: "${ANDROID_HOME:?ANDROID_HOME must point at the Android SDK}"
+
+src="$(fetch_source "$PY_VERSION")"
+cd "$src"
+
+# `Platforms/Android package` lists the files to ship with `git ls-files`, so
+# the unpacked tarball needs an index that tracks Platforms/Android.
+if [ ! -d .git ]; then
+    git init -q .
+    git add Platforms/Android
+fi
+
+# Install the NDK version the tooling pins (android-env.sh would do it on first
+# use; doing it here makes a missing cmdline-tools fail early and visibly).
+ndk_version="$(sed -n 's/^ndk_version=//p' Platforms/Android/android-env.sh)"
+[ -n "$ndk_version" ] || die "no ndk_version in Platforms/Android/android-env.sh"
+log "NDK required by CPython $PY_VERSION: $ndk_version"
+if [ ! -e "$ANDROID_HOME/ndk/$ndk_version/package.xml" ]; then
+    yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "ndk;$ndk_version" >/dev/null || true
+fi
+[ -e "$ANDROID_HOME/ndk/$ndk_version/package.xml" ] || die "NDK $ndk_version not installed"
+
+# --disable-gil goes to configure after `--`, for the build Python and the host.
+python3 Platforms/Android configure-build -- --disable-gil
+python3 Platforms/Android make-build
+python3 Platforms/Android pythoninfo-build
+python3 Platforms/Android configure-host "$HOST" -- --disable-gil
+python3 Platforms/Android make-host "$HOST"
+python3 Platforms/Android package "$HOST"
+
+# ---- verification -------------------------------------------------------
+minor="$(py_minor "$PY_VERSION")"
+archive="$(ls cross-build/$HOST/dist/python-*-$HOST.tar.gz)"
+log "package: $archive"
+
+# The build Python must itself be free-threaded.
+cross-build/build/python -c 'import sys, sysconfig; assert sysconfig.get_config_var("Py_GIL_DISABLED") == 1; print("build python free-threaded:", sys.version)'
+
+check="$FT_WORK/android-check"
+rm -rf "$check"; mkdir -p "$check"
+tar -xzf "$archive" -C "$check"
+
+require_gil_disabled "$check/prefix/include/python${minor}t/pyconfig.h"
+lib="$(ls "$check"/prefix/lib/libpython${minor}t*.so* 2>/dev/null | head -n 1 || true)"
+[ -n "$lib" ] || die "no libpython${minor}t*.so in the package"
+log "ok: $lib"
+file "$lib" | tee /dev/stderr | grep -q 'ARM aarch64' || die "$lib is not an aarch64 ELF"
+[ -d "$check/prefix/lib/python${minor}t" ] || die "no lib/python${minor}t in the package"
+
+cp "$archive" "$FT_OUT/"
+echo "Android archive:" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+record_sha256 "$FT_OUT/$(basename "$archive")"

.github/scripts/ft-mobile/build-ios.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Build free-threaded CPython (--disable-gil) as an iOS XCframework with
+# CPython's own tooling (Platforms/Apple). Usage: build-ios.sh [VERSION]
+# Needs macOS with a full Xcode and python3 >= 3.10.
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$here/common.sh"
+
+PY_VERSION="${1:-3.15.0}"
+# The XCframework needs every slice Platforms/Apple declares: one device host
+# and two simulator hosts (arm64, x86_64).
+HOSTS=(arm64-apple-ios arm64-apple-ios-simulator x86_64-apple-ios-simulator)
+
+src="$(fetch_source "$PY_VERSION")"
+cd "$src"
+xcodebuild -version
+
+# Platforms/Apple names the standard library directory "python<major.minor>"
+# when it packages and in the Xcode build helper, but a free-threaded build
+# installs "python<major.minor>t" (LIBDEST has $(ABI_THREAD)). Without these two
+# edits `package` fails copying the xcprivacy files and the helper script would
+# not find the standard library. Each edit is asserted so a changed upstream
+# script fails loudly instead of silently skipping the patch.
+python3 -I - <<'PY'
+import pathlib
+def patch(path, old, new):
+    p = pathlib.Path(path)
+    s = p.read_text()
+    assert s.count(old) == 1, f"{path}: expected exactly one {old!r}"
+    p.write_text(s.replace(old, new))
+patch("Platforms/Apple/__main__.py",
+      'version_tag = ".".join(version.split(".")[:2])',
+      'version_tag = ".".join(version.split(".")[:2]) + "t"')
+patch("Platforms/Apple/testbed/Python.xcframework/build/utils.sh",
+      'grep -E "^python3\\.\\d+$"',
+      'grep -E "^python3\\.[0-9]+t?$"')
+PY
+
+# --disable-gil goes to configure after `--`, for the build Python and each host.
+python3 Platforms/Apple configure-build -- --disable-gil
+python3 Platforms/Apple make-build
+python3 Platforms/Apple pythoninfo-build
+for host in "${HOSTS[@]}"; do
+    python3 Platforms/Apple configure-host iOS "$host" -- --disable-gil
+    python3 Platforms/Apple make-host iOS "$host"
+done
+python3 Platforms/Apple package iOS
+
+# ---- verification -------------------------------------------------------
+minor="$(py_minor "$PY_VERSION")"
+archive="$(ls cross-build/dist/python-*-iOS-XCframework.tar.gz)"
+log "package: $archive"
+
+# On macOS the build interpreter is python.exe (cross-build/build/python is a directory).
+build_py=cross-build/build/python.exe; [ -x "$build_py" ] || build_py=cross-build/build/python
+"$build_py" -c 'import sys, sysconfig; assert sysconfig.get_config_var("Py_GIL_DISABLED") == 1; print("build python free-threaded:", sys.version)'
+
+check="$FT_WORK/ios-check"
+rm -rf "$check"; mkdir -p "$check"
+tar -xzf "$archive" -C "$check"
+xcf="$check/Python.xcframework"
+[ -d "$xcf" ] || die "no Python.xcframework in the package"
+
+[ -d "$xcf/lib/python${minor}t" ] || die "no lib/python${minor}t in the XCframework"
+slices=0
+for slice in "$xcf"/ios-*; do
+    slices=$((slices + 1))
+    # Headers/pyconfig.h is a wrapper that includes pyconfig-<arch>.h.
+    found=0
+    for h in "$slice"/Python.framework/Headers/pyconfig-*.h; do
+        require_gil_disabled "$h"; found=$((found + 1))
+    done
+    [ "$found" -gt 0 ] || die "no pyconfig-<arch>.h in $slice"
+    [ -e "$slice/lib/libpython${minor}t.dylib" ] || die "no libpython${minor}t.dylib in $slice"
+    lipo -info "$slice/Python.framework/Python"
+done
+[ "$slices" -eq 2 ] || die "expected 2 slices (device, simulator), found $slices"
+
+cp "$archive" "$FT_OUT/"
+echo "iOS archive:" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+record_sha256 "$FT_OUT/$(basename "$archive")"

.github/scripts/ft-mobile/common.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Helpers shared by build-android.sh and build-ios.sh. Source this file, do not run it.
+
+# FT_WORK: scratch directory (source tree and cross-build output).
+# FT_OUT : directory that receives the archives the workflow uploads.
+FT_WORK="${FT_WORK:-$PWD/.tmp/ft-mobile}"
+FT_OUT="${FT_OUT:-$PWD/.tmp/ft-mobile-out}"
+
+log() { echo "[ft-mobile] $*" >&2; }
+die() { echo "[ft-mobile] ERROR: $*" >&2; exit 1; }
+
+# "3.15.0" -> "3.15" (also "3.15.0rc1" -> "3.15").
+py_minor() { echo "$1" | sed -E 's/^([0-9]+\.[0-9]+).*/\1/'; }
+
+# Download and unpack the CPython source tarball; print the source directory.
+# CPython's mobile tooling needs the directory to be a git work tree only for
+# `Platforms/Android package` (it runs `git ls-files` there), so the caller
+# decides whether to `git init`.
+fetch_source() {
+    local version="$1"
+    local dirver="${version%%[a-z]*}"   # the ftp directory has no rc/alpha suffix
+    local tgz="$FT_WORK/Python-$version.tgz"
+    mkdir -p "$FT_WORK" "$FT_OUT"
+    if [ ! -f "$tgz" ]; then
+        log "downloading CPython $version"
+        curl -fL --retry 5 --retry-all-errors -o "$tgz" \
+            "https://www.python.org/ftp/python/$dirver/Python-$version.tgz"
+    fi
+    if [ ! -d "$FT_WORK/Python-$version" ]; then
+        tar -xzf "$tgz" -C "$FT_WORK"
+    fi
+    echo "$FT_WORK/Python-$version"
+}
+
+# Fail unless FILE contains a line matching `#define Py_GIL_DISABLED 1`.
+require_gil_disabled() {
+    local file="$1"
+    grep -Eq '^#define Py_GIL_DISABLED 1$' "$file" \
+        || die "$file does not define Py_GIL_DISABLED 1"
+    log "ok: Py_GIL_DISABLED 1 in $file"
+}
+
+# Print "sha256  name" lines for the given files, to stdout and the job summary.
+record_sha256() {
+    local f line
+    for f in "$@"; do
+        line="$(cd "$(dirname "$f")" && shasum -a 256 "$(basename "$f")")"
+        echo "$line"
+        if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+            echo "$line" >> "$GITHUB_STEP_SUMMARY"
+        fi
+    done
+}

tools/release/README.md → .github/scripts/release/README.md

@@ -7,7 +7,7 @@ between runs, and any existing `release` (e.g. a stale one from an older workflo
 ignored and overwritten.
 
 1. Every push to `develop` triggers `.github/workflows/release-sync.yml`, which runs
-   `tools/release/sync-release.sh --push`. It rebuilds `release` from scratch as exactly
+   `.github/scripts/release/sync-release.sh --push`. It rebuilds `release` from scratch as exactly
    one commit (`Release: sync from develop <sha>`) whose parent is that develop commit and
    whose tree is the develop tree minus the files below. This happens even when nothing
    is dropped. It is a no-op only if `release` already has that tree and that parent.
@@ -31,10 +31,10 @@ Only Markdown is ever dropped.
 
 ## Local use
 
-    tools/release/sync-release.sh --dry-run     # list paths that would be dropped
-    tools/release/sync-release.sh               # regenerate local release branch
-    tools/release/sync-release.sh --push        # also push to origin
-    tools/release/test-sync-release.sh          # tests (throwaway repo in .tmp/)
+    .github/scripts/release/sync-release.sh --dry-run     # list paths that would be dropped
+    .github/scripts/release/sync-release.sh               # regenerate local release branch
+    .github/scripts/release/sync-release.sh --push        # also push to origin
+    .github/scripts/release/test-sync-release.sh          # tests (throwaway repo in .tmp/)
 
 The script uses plumbing and a private index, so your working tree, index and HEAD are untouched.
 It refuses to run while `release` is checked out.

tools/release/test-sync-release.sh → .github/scripts/release/test-sync-release.sh

@@ -2,7 +2,7 @@
 # Tests for sync-release.sh. Builds a throwaway repo under <repo>/.tmp/.
 set -u
 HERE="$(cd "$(dirname "$0")" && pwd)"
-ROOT="$(cd "$HERE/../.." && pwd)"
+ROOT="$(cd "$HERE/../../.." && pwd)"
 SYNC="$HERE/sync-release.sh"
 SCRATCH="$ROOT/.tmp/release-sync-test.$$"
 FAILS=0; PASSES=0

tools/stubs/check-stubs.sh → .github/scripts/stubs/check-stubs.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
-# Type-checks tools/stubs/consumer.py against a directory of generated Kotlin-name stubs (issue #31).
+# Type-checks .github/scripts/stubs/consumer.py against a directory of generated Kotlin-name stubs (issue #31).
 #
-#   tools/stubs/check-stubs.sh <stub-dir> [venv-dir]
+#   .github/scripts/stubs/check-stubs.sh <stub-dir> [venv-dir]
 #
 # <stub-dir> is what `generatePythonStubs` wrote, e.g.
-#   ksp-fixtures/compose/build/generated/pythonStubs/desktopMain
+#   python-multiplatform-compose/fixtures/compose/build/generated/pythonStubs/desktopMain
 # The venv defaults to <repo>/.tmp/stubs-venv (git-ignored) and is created on first use.
 set -euo pipefail
 
-root="$(cd "$(dirname "$0")/../.." && pwd)"
+root="$(cd "$(dirname "$0")/../../.." && pwd)"
 stubs="$(cd "${1:?usage: check-stubs.sh <stub-dir> [venv-dir]}" && pwd)"
 venv="${2:-$root/.tmp/stubs-venv}"
 
@@ -17,10 +17,10 @@ if [ ! -x "$venv/bin/mypy" ]; then
   "$venv/bin/pip" install --quiet mypy
 fi
 
-# tools/stubs/mypy.ini: `strict`, and `warn_unused_ignores` for the consumer so that the lines it
+# .github/scripts/stubs/mypy.ini: `strict`, and `warn_unused_ignores` for the consumer so that the lines it
 # expects to be rejected fail the check when they stop being. Errors inside the stubs themselves are
 # reported too: MYPYPATH modules are checked, not silenced.
 MYPYPATH="$stubs" "$venv/bin/mypy" \
-  --config-file "$root/tools/stubs/mypy.ini" \
+  --config-file "$root/.github/scripts/stubs/mypy.ini" \
   --cache-dir "$root/.tmp/mypy-cache" \
-  "$root/tools/stubs/consumer.py"
+  "$root/.github/scripts/stubs/consumer.py"

tools/stubs/consumer.py → .github/scripts/stubs/consumer.py

@@ -1,29 +1,48 @@
-"""A small consumer of the generated Kotlin-name stubs, type-checked by `check-stubs.sh` (issue #31).
+"""A small consumer of the generated Kotlin-named stubs, type-checked by `check-stubs.sh` (issue #31).
 
-It is the code a user writes against the binder -- Kotlin names, Kotlin parameter names -- and it
-must type-check against the stubs generated for the real Compose jars: a Modifier chain started from
-the class and continued from an instance, `Checkbox`, `Text`, and a container with its trailing
-`content` lambda. The last four lines are **meant** to be rejected; they carry `# type: ignore[...]`
-and mypy runs with `warn_unused_ignores`, so a stub that stopped rejecting one fails the check too.
+It is the code a user writes against the binder, and it must type-check against the stubs generated
+for the real Compose jars: a Modifier chain started from the class and continued from an instance,
+`Checkbox`, `Text`, and a container with its trailing `content` lambda.
+
+Names: a declaration is reachable by its Kotlin name and by its Pythonic (snake_case) alias, and the
+stubs carry both (issue #131), so both spellings are written below. Keywords: a stub can name a
+parameter only once, and it names it the way `inspect.signature` does -- by the Pythonic keyword
+(`on_checked_change`). The Kotlin keyword (`onCheckedChange=`) still works at run time; a checker
+reports it, so it is not written here.
+
+The last four lines are **meant** to be rejected; they carry `# type: ignore[...]` and mypy runs
+with `warn_unused_ignores`, so a stub that stopped rejecting one fails the check too.
 """
 
 from typing import assert_type
 
-from androidx.compose.foundation.layout import Arrangement, Column, Row, fillMaxWidth, padding__Dp
+from androidx.compose.foundation.layout import (
+    Arrangement,
+    Column,
+    Row,
+    fill_max_width,
+    fillMaxWidth,
+    padding__Dp,
+)
 from androidx.compose.material.icons import Icons
 from androidx.compose.material3 import Checkbox, Icon, Text
 from androidx.compose.ui import Modifier
 from androidx.compose.ui.graphics.vector import ImageVector
 
 # A chain started from the class, the way Kotlin writes `Modifier.padding(16.dp)`.
 chain: Modifier = Modifier.fillMaxWidth().padding(16.0).size(24.0)
-# ... and continued from an instance, and with Kotlin parameter names.
+# ... and continued from an instance, with keyword arguments.
 more: Modifier = chain.padding(horizontal=8.0, vertical=4.0).padding(start=1.0, bottom=2.0)
 # The explicit table-key spelling, as an attribute and as a module function.
 explicit: Modifier = chain.padding__Dp(4.0)
 by_function: Modifier = padding__Dp(chain, 4.0)
 by_extension: Modifier = fillMaxWidth(chain, fraction=0.5)
 
+# Issue #131: the Pythonic alias of a module function and of a method is the same declaration.
+by_alias: Modifier = fill_max_width(chain, fraction=0.5)
+assert_type(fill_max_width(chain), Modifier)
+pythonic_chain: Modifier = Modifier.fill_max_width().padding(16.0).fill_max_width(0.5)
+
 checked = True
 
 
@@ -33,7 +52,7 @@ def on_change(value: bool) -> None:
 
 
 Checkbox(checked, on_change, modifier=more, enabled=True)
-Checkbox(checked=False, onCheckedChange=None)
+Checkbox(checked=False, on_checked_change=None)
 Text("hello", modifier=Modifier.padding(8.0))
 
 
@@ -44,18 +63,18 @@ def content() -> None:
 Column(modifier=chain, content=lambda scope: None)
 Row(content=lambda scope: None)
 # `SpaceBetween` is a `HorizontalOrVertical`: a `Vertical` slot and a `Horizontal` slot both take it (#71).
-Column(verticalArrangement=Arrangement.SpaceBetween, content=lambda scope: None)
-Row(horizontalArrangement=Arrangement.SpaceBetween, content=lambda scope: None)
+Column(vertical_arrangement=Arrangement.SpaceBetween, content=lambda scope: None)
+Row(horizontal_arrangement=Arrangement.SpaceBetween, content=lambda scope: None)
 
 # An extension property on a type nested in an object (issue #68): `Icons.Default` is `Icons.Filled`.
 # `assert_type`, not an annotation: an `Any` (the stub before #53/#67) would satisfy an annotation.
 assert_type(Icons.Default.Add, ImageVector)
-Icon(Icons.Default.Add, contentDescription=None)
+Icon(Icons.Default.Add, content_description=None)
 
 # Rejected on purpose. (`padding("sixteen")` is not among them: one `padding` overload takes a
 # `PaddingValues`, a type the stubs cannot name -- `PaddingValues(...)` the factory owns the name -- so
 # it is `Any` and accepts anything.)
-Modifier.fillMaxWidth("wide")  # type: ignore[arg-type]
+Modifier.fill_max_width("wide")  # type: ignore[arg-type]
 Checkbox("not a bool", on_change)  # type: ignore[call-overload]
 Checkbox(checked, on_change, enabled="yes")  # type: ignore[call-overload]
 Column(chain)  # type: ignore[call-arg]

.github/workflows/android-native.yml

@@ -1,15 +1,16 @@
 name: Android Native CI
 
 on:
+  # Checked on develop after merging, not on every pull request (user decision,
+  # 2026-10-17). A red develop is fixed forward by its own pull request.
   push:
     branches: [ "develop", "main" ]
-  pull_request:
-    branches: [ "develop", "main" ]
-
+  workflow_dispatch:
 concurrency:
-  # A newer push to the same ref supersedes this run; frees the shared macOS runners.
+  # A run in progress finishes; a newer push replaces only the queued run (frequent merges
+  # to develop otherwise cancelled every run before it reported).
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 jobs:
   compile: