Skip to content

CLI for SidePulse

Python

Automatically install Python on macOS when needed

Peter Kuharf206fadd320c
diff --git a/README.md b/README.md
index cc428e6..f56a314 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,10 @@ Choose the level that fits how you want to use SidePulse.
curl -fsSL https://sidepulse.io/setup.sh | bash
```
-The command works on macOS and Linux with Python 3.10 or newer. The
+The command works on macOS and Linux. It uses an existing Python 3.10 or newer
+when available. On macOS, if a suitable Python is missing, it automatically
+downloads Python 3.13 using uv into `~/.local/share/sidepulse`, without requiring
+Homebrew or administrator access. On Linux, install Python 3.10 or newer first. The
[setup script](scripts/setup.sh) creates an isolated environment under
`~/.local/share/sidepulse/venv`, installs SidePulse from GitHub, links the CLI
at `~/.local/bin/sidepulse`, and runs `sidepulse setup`. On macOS, setup also
diff --git a/scripts/setup.sh b/scripts/setup.sh
index 216ab26..17253c8 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -3,17 +3,58 @@ set -eu
PYTHON_BIN=${PYTHON_BIN:-python3}
INSTALL_SPEC=${SIDEPULSE_INSTALL_SPEC:-"git+https://github.com/inteliwear/sidepulse.git"}
-VENV=${SIDEPULSE_INSTALL_ROOT:-"$HOME/.local/share/sidepulse"}/venv
+INSTALL_ROOT=${SIDEPULSE_INSTALL_ROOT:-"$HOME/.local/share/sidepulse"}
+VENV=$INSTALL_ROOT/venv
BIN_DIR=${SIDEPULSE_BIN_DIR:-"$HOME/.local/bin"}
-if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
- printf 'SidePulse requires Python 3.10 or newer. Could not find %s.\n' "$PYTHON_BIN" >&2
- exit 1
-fi
+usable_python() {
+ command -v "$1" >/dev/null 2>&1 &&
+ "$1" -c 'import sys; raise SystemExit(sys.version_info < (3, 10))' >/dev/null 2>&1
+}
-if ! "$PYTHON_BIN" -c 'import sys; raise SystemExit(sys.version_info < (3, 10))'; then
- printf 'SidePulse requires Python 3.10 or newer.\n' >&2
- exit 1
+install_macos_python() (
+ # Keep uv and its Python private to SidePulse. The unmanaged installer does
+ # not edit shell profiles, and --no-bin avoids global Python symlinks.
+ uv_bin=$INSTALL_ROOT/uv/uv
+ if [ ! -x "$uv_bin" ]; then
+ bootstrap_dir=$(mktemp -d "${TMPDIR:-/tmp}/sidepulse-python.XXXXXX")
+ trap 'rm -rf "$bootstrap_dir"' EXIT
+ curl -fsSL https://astral.sh/uv/install.sh -o "$bootstrap_dir/install-uv.sh" || exit 1
+ UV_UNMANAGED_INSTALL="$INSTALL_ROOT/uv" sh "$bootstrap_dir/install-uv.sh" >&2 || exit 1
+ fi
+ printf 'Installing Python 3.13 for SidePulse…\n' >&2
+ UV_PYTHON_INSTALL_DIR="$INSTALL_ROOT/python" "$uv_bin" python install \
+ --no-config --no-bin 3.13 >&2 || exit 1
+ UV_PYTHON_INSTALL_DIR="$INSTALL_ROOT/python" "$uv_bin" python find \
+ --no-config --no-project --managed-python 3.13
+)
+
+# Updates use the existing interpreter even if the shell's python3 is older.
+if [ -x "$VENV/bin/python" ]; then
+ if ! usable_python "$VENV/bin/python"; then
+ printf 'The existing SidePulse environment needs Python 3.10 or newer: %s\n' "$VENV" >&2
+ exit 1
+ fi
+ PYTHON_BIN=$VENV/bin/python
+elif ! usable_python "$PYTHON_BIN"; then
+ found_python=
+ for candidate in python3 python3.14 python3.13 python3.12 python3.11 python3.10; do
+ if usable_python "$candidate"; then
+ found_python=$(command -v "$candidate")
+ break
+ fi
+ done
+ if [ -n "$found_python" ]; then
+ PYTHON_BIN=$found_python
+ elif [ "$(uname -s)" = "Darwin" ]; then
+ if ! PYTHON_BIN=$(install_macos_python) || ! usable_python "$PYTHON_BIN"; then
+ printf 'Could not install Python for SidePulse. Check your internet connection and try again.\n' >&2
+ exit 1
+ fi
+ else
+ printf 'SidePulse requires Python 3.10 or newer. Install it and run setup again.\n' >&2
+ exit 1
+ fi
fi
# Reuse a working environment on updates; recreating it can change the Python
diff --git a/tests/test_setup_python.py b/tests/test_setup_python.py
new file mode 100644
index 0000000..356c4b6
--- /dev/null
+++ b/tests/test_setup_python.py
@@ -0,0 +1,139 @@
+"""Exercise Python discovery and bootstrap through the actual setup script."""
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/setup.sh"
+
+
+class SetupPythonTests(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory(prefix="sidepulse-python-test-")
+ self.addCleanup(self.tmp.cleanup)
+ self.root = Path(self.tmp.name)
+ self.bin = self.root / "bin"
+ self.bin.mkdir()
+ self.install_root = self.root / "install with spaces"
+ self.log = self.root / "calls"
+ self.env = {
+ **os.environ,
+ "HOME": str(self.root),
+ "PATH": f"{self.bin}:/usr/bin:/bin",
+ "PYTHON_BIN": "python3",
+ "SIDEPULSE_INSTALL_ROOT": str(self.install_root),
+ "SIDEPULSE_TEST_LOG": str(self.log),
+ }
+ self.stub("uname", 'printf "Darwin\\n"')
+ for name in ("python3", "python3.10", "python3.11", "python3.12", "python3.13", "python3.14"):
+ self.stub(name, "exit 1")
+ self.managed_python = self.root / "managed python"
+ self.good_python(self.managed_python)
+ self.uv_source = self.root / "uv-source"
+ self.stub(self.uv_source, '''
+printf '%s|%s\\n' "$UV_PYTHON_INSTALL_DIR" "$*" >> "$SIDEPULSE_TEST_LOG"
+if [ "$2" = install ]; then
+ exit "${SIDEPULSE_TEST_UV_FAIL:-0}"
+fi
+printf '%s\\n' "$SIDEPULSE_TEST_MANAGED_PYTHON"
+''')
+ self.env["SIDEPULSE_TEST_UV_SOURCE"] = str(self.uv_source)
+ self.env["SIDEPULSE_TEST_MANAGED_PYTHON"] = str(self.managed_python)
+ self.installer = self.root / "installer"
+ self.installer.write_text('''#!/bin/sh
+mkdir -p "$UV_UNMANAGED_INSTALL"
+cp "$SIDEPULSE_TEST_UV_SOURCE" "$UV_UNMANAGED_INSTALL/uv"
+printf 'bootstrap\\n' >> "$SIDEPULSE_TEST_LOG"
+''')
+ self.env["SIDEPULSE_TEST_INSTALLER"] = str(self.installer)
+ self.stub("curl", '''
+printf 'curl\\n' >> "$SIDEPULSE_TEST_LOG"
+[ "${SIDEPULSE_TEST_CURL_FAIL:-0}" = 0 ] || exit 1
+[ "$1" = -fsSL ] && [ "$2" = https://astral.sh/uv/install.sh ] && [ "$3" = -o ] || exit 2
+cp "$SIDEPULSE_TEST_INSTALLER" "$4"
+''')
+
+ def stub(self, name, body):
+ path = self.bin / name
+ path.write_text("#!/bin/sh\nset -eu\n" + body + "\n")
+ path.chmod(0o755)
+ return path
+
+ def good_python(self, path):
+ # Stop at virtualenv creation, after discovery but before package or
+ # service changes. A successful -c models a supported interpreter.
+ return self.stub(path, f'''
+if [ "$1" = -c ]; then exit 0; fi
+printf '%s\\n' {shlex.quote(str(path))} >> "$SIDEPULSE_TEST_LOG"
+[ "$1" = -m ] && [ "$2" = venv ] || exit 2
+exit 42
+''')
+
+ def run_setup(self, **env):
+ return subprocess.run(
+ ["/bin/sh", str(SCRIPT)], env={**self.env, **env},
+ capture_output=True, text=True, timeout=10,
+ )
+
+ def calls(self):
+ return self.log.read_text().splitlines() if self.log.exists() else []
+
+ def test_supported_default_needs_no_download(self):
+ python = self.good_python(self.bin / "python3")
+ self.assertEqual(self.run_setup().returncode, 1)
+ self.assertEqual(self.calls(), [str(python)])
+
+ def test_old_default_finds_versioned_python(self):
+ python = self.good_python(self.bin / "python3.12")
+ self.assertEqual(self.run_setup().returncode, 1)
+ self.assertEqual(self.calls(), [str(python)])
+
+ def test_missing_python_bootstraps_private_uv_and_python_on_macos(self):
+ result = self.run_setup(PYTHON_BIN="missing-python")
+ self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+ self.assertIn("Could not create a Python virtual environment", result.stderr)
+ self.assertEqual(self.calls(), [
+ "curl", "bootstrap",
+ f"{self.install_root}/python|python install --no-config --no-bin 3.13",
+ f"{self.install_root}/python|python find --no-config --no-project --managed-python 3.13",
+ str(self.managed_python),
+ ])
+
+ def test_private_uv_is_reused(self):
+ uv = self.install_root / "uv/uv"
+ uv.parent.mkdir(parents=True)
+ self.stub(uv, self.uv_source.read_text())
+ self.assertEqual(self.run_setup().returncode, 1)
+ self.assertNotIn("curl", self.calls())
+ self.assertEqual(self.calls()[-1], str(self.managed_python))
+
+ def test_download_failure_stops_before_virtualenv_creation(self):
+ result = self.run_setup(SIDEPULSE_TEST_CURL_FAIL="1")
+ self.assertEqual(result.returncode, 1)
+ self.assertIn("Could not install Python", result.stderr)
+ self.assertEqual(self.calls(), ["curl"])
+ self.assertFalse((self.install_root / "venv").exists())
+
+ def test_python_install_failure_stops_before_discovery(self):
+ result = self.run_setup(SIDEPULSE_TEST_UV_FAIL="1")
+ self.assertEqual(result.returncode, 1)
+ self.assertIn("Could not install Python", result.stderr)
+ self.assertFalse(any("python find" in call for call in self.calls()))
+
+ def test_bootstrapped_interpreter_is_checked(self):
+ result = self.run_setup(SIDEPULSE_TEST_MANAGED_PYTHON="missing-python")
+ self.assertEqual(result.returncode, 1)
+ self.assertIn("Could not install Python", result.stderr)
+ self.assertNotIn(str(self.managed_python), self.calls())
+
+ def test_linux_requires_python_without_downloading(self):
+ self.stub("uname", 'printf "Linux\\n"')
+ result = self.run_setup()
+ self.assertEqual(result.returncode, 1)
+ self.assertIn("Install it and run setup again", result.stderr)
+ self.assertEqual(self.calls(), [])
diff --git a/tests/test_setup_update.py b/tests/test_setup_update.py
index 9de8ef1..22822e7 100644
--- a/tests/test_setup_update.py
+++ b/tests/test_setup_update.py
@@ -123,6 +123,13 @@ class SetupUpdateTests(unittest.TestCase):
result = subprocess.run([str(self.bin / 'sidepulse'), '--version'], env=self.env, capture_output=True, text=True)
self.assertIn('old', result.stdout)
+ def test_update_reuses_venv_when_shell_python_is_unavailable(self):
+ self.assertEqual(self.install(self.old).returncode, 0)
+ self.log.write_text('')
+ result = self.install(self.new, PYTHON_BIN='missing-python')
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn(['new', ['--version']], self.calls())
+
def test_setup_failure_resumes_previously_stopped_service(self):
self.assertEqual(self.install(self.old).returncode, 0)
self.log.write_text('')