fix(common): add pip to compile

Author: nickchecan

README.md

@@ -6,6 +6,41 @@ The current cloud foundry [python-buildpack](https://github.com/cloudfoundry/pyt
 
 ## How to use
 
+
+### Defining the initialization script
+
+This buildpack detects uv-managed apps when both `pyproject.toml` and `uv.lock` are present.
+
+At staging time, `bin/compile` exports the locked dependencies from `uv.lock`, installs them into `.python_packages`, and writes a `.profile.d/python.sh` file so the app can import those staged packages at runtime. If the app uses a `src/` layout, that `src/` directory is also added to `PYTHONPATH`.
+
+At release time, `bin/release` chooses the web command in this order:
+
+1. If the app has a `Procfile`, the buildpack does not generate a default process type and Cloud Foundry uses the `Procfile`.
+2. If `pyproject.toml` exists and `[project.scripts]` contains a script named exactly the same as `[project].name`, that script is used.
+3. Otherwise, if `[project.scripts]` contains a `start` script, that script is used.
+4. Otherwise, if `main.py` exists, the buildpack uses `python3 main.py`.
+5. Otherwise, if `app.py` exists, the buildpack uses `python3 app.py`.
+6. If none of the above are present, the buildpack emits an empty `web` process and you must provide your own entrypoint.
+
+For `pyproject.toml` scripts, the buildpack converts a console-script target such as:
+
+```toml
+[project]
+name = "my-app"
+
+[project.scripts]
+my-app = "server.main:run"
+start = "server.main:start"
+```
+
+into a process command like:
+
+```sh
+python3 -c "from server.main import run; run()"
+```
+
+In the example above, `my-app` wins over `start` because it matches `[project].name`.
+
 ## Testing Locally
 
 Run the buildpack test flow from the repository root:

bin/compile

@@ -17,6 +17,17 @@ else
   exit 1
 fi
 
+ensure_pip() {
+  # Some CF Python runtimes do not expose pip by default, so bootstrap it
+  # before the buildpack tries to install uv or exported dependencies.
+  if "$PYTHON_BIN" -m pip --version >/dev/null 2>&1; then
+    return 0
+  fi
+
+  echo "pip not found for $PYTHON_BIN. Bootstrapping with ensurepip."
+  "$PYTHON_BIN" -m ensurepip --upgrade
+}
+
 cd "$BUILD_DIR"
 
 # Only treat the app as a supported uv project when both the project
@@ -30,10 +41,14 @@ if [ -f "pyproject.toml" ] && [ -f "uv.lock" ]; then
 
   mkdir -p "$PIP_CACHE_DIR" "$UV_CACHE_DIR"
 
+  # Install uv into the selected interpreter so the buildpack can export the
+  # exact locked dependency set from the app's uv.lock file.
+  ensure_pip
   "$PYTHON_BIN" -m pip install uv
 
   PYTHON_VERSION=$("$PYTHON_BIN" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
-  # Stage dependencies into a buildpack-owned location instead of a local venv.
+  # Stage dependencies into a buildpack-owned location instead of a local venv
+  # because CF launches the app from the droplet, not from a project virtualenv.
   SITE_PACKAGES_DIR="$BUILD_DIR/.python_packages/lib/python${PYTHON_VERSION}/site-packages"
   SRC_DIR="$BUILD_DIR/src"
   PROFILE_DIR="$BUILD_DIR/.profile.d"

test/unit/compile_test.sh

@@ -67,6 +67,7 @@ assert_path_exists() {
 }
 
 setup_fake_commands() {
+  local pip_available="${1:-1}"
   mkdir -p "$FAKE_BIN_DIR"
 
   cat > "$FAKE_BIN_DIR/python3" <<'EOF'
@@ -78,6 +79,23 @@ if [ "$#" -ge 2 ] && [ "$1" = "-c" ] && [ "$2" = "import sys; print(f\"{sys.vers
   exit 0
 fi
 
+if [ "$#" -ge 3 ] && [ "$1" = "-m" ] && [ "$2" = "pip" ] && [ "$3" = "--version" ]; then
+  if [ "${FAKE_PIP_AVAILABLE:-1}" = "1" ]; then
+    printf 'pip 24.0 from /fake/site-packages/pip (python 3.13)\n'
+    exit 0
+  fi
+
+  echo "No module named pip" >&2
+  exit 1
+fi
+
+if [ "$#" -ge 3 ] && [ "$1" = "-m" ] && [ "$2" = "ensurepip" ] && [ "$3" = "--upgrade" ]; then
+  log_file="${TEST_ROOT}/ensurepip.log"
+  mkdir -p "$(dirname "$log_file")"
+  printf '%s\n' "$*" >> "$log_file"
+  exit 0
+fi
+
 if [ "$#" -ge 3 ] && [ "$1" = "-m" ] && [ "$2" = "pip" ]; then
   log_file="${TEST_ROOT}/pip.log"
   mkdir -p "$(dirname "$log_file")"
@@ -149,6 +167,7 @@ exit 1
 EOF
 
   chmod +x "$FAKE_BIN_DIR/python3" "$FAKE_BIN_DIR/uv"
+  FAKE_PIP_AVAILABLE="$pip_available"
 }
 
 run_compile() {
@@ -158,7 +177,7 @@ run_compile() {
   local output_file="$TEST_ROOT/output.txt"
 
   set +e
-  PATH="$FAKE_BIN_DIR:/usr/bin:/bin" TEST_ROOT="$TEST_ROOT" "$COMPILE_SCRIPT" "$build_dir" "$cache_dir" "$env_dir" >"$output_file" 2>&1
+  PATH="$FAKE_BIN_DIR:/usr/bin:/bin" TEST_ROOT="$TEST_ROOT" FAKE_PIP_AVAILABLE="${FAKE_PIP_AVAILABLE:-1}" "$COMPILE_SCRIPT" "$build_dir" "$cache_dir" "$env_dir" >"$output_file" 2>&1
   status=$?
   set -e
 
@@ -193,6 +212,26 @@ test_compile_succeeds_for_locked_uv_project() {
   assert_file_contains "$TEST_ROOT/pip.log" "--no-deps --target $site_packages_dir -r $export_file" "compile should install exported dependencies into the staged site-packages directory"
 }
 
+test_compile_bootstraps_pip_when_missing() {
+  # Arrange
+  local build_dir="$TEST_ROOT/missing-pip/build"
+  local cache_dir="$TEST_ROOT/missing-pip/cache"
+  local env_dir="$TEST_ROOT/missing-pip/env"
+
+  mkdir -p "$build_dir" "$cache_dir" "$env_dir"
+  touch "$build_dir/pyproject.toml" "$build_dir/uv.lock"
+  setup_fake_commands 0
+
+  # Act
+  run_compile "$build_dir" "$cache_dir" "$env_dir"
+
+  # Assert
+  assert_exit_code "$status" 0 "compile should bootstrap pip when the interpreter does not ship it"
+  assert_contains "$output" "pip not found for python3. Bootstrapping with ensurepip." "compile should explain when it needs to bootstrap pip"
+  assert_file_contains "$TEST_ROOT/ensurepip.log" "-m ensurepip --upgrade" "compile should bootstrap pip before using it"
+  assert_file_contains "$TEST_ROOT/pip.log" "-m pip install uv" "compile should continue with pip installs after bootstrapping"
+}
+
 test_compile_adds_src_directory_to_pythonpath_when_present() {
   # Arrange
   local build_dir="$TEST_ROOT/src-layout/build"
@@ -231,6 +270,7 @@ test_compile_fails_when_lockfile_is_missing() {
 }
 
 test_compile_succeeds_for_locked_uv_project
+test_compile_bootstraps_pip_when_missing
 test_compile_adds_src_directory_to_pythonpath_when_present
 test_compile_fails_when_lockfile_is_missing