Improve the error message shown for legacy Celery (#1718)

pip 24.1+ rejects packages that use invalid versions in their metadata
(such as Celery older than v5.2.1).

We now annotate such failures with additional help text, mentioning
the package needs to be upgraded, and link to the changelog entry
which has additional advice:
https://devcenter.heroku.com/changelog-items/3073

GUS-W-17415804.

Author: edmorley

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
       HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
       HEROKU_API_USER: ${{ secrets.HEROKU_API_USER }}
       HEROKU_DISABLE_AUTOUPDATE: 1
-      PARALLEL_SPLIT_TEST_PROCESSES: 70
+      PARALLEL_SPLIT_TEST_PROCESSES: 75
       RSPEC_RETRY_RETRY_COUNT: 2
     steps:
       - name: Checkout

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Improved the error message shown when pip install fails due to pip rejecting a package with invalid version metadata. ([#1718](https://github.com/heroku/heroku-buildpack-python/pull/1718))
 
 ## [v270] - 2024-12-10
 

bin/warnings

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-gdal-missing() {
+show-warnings() {
 	# shellcheck disable=SC2154 # TODO: Env var is referenced but not assigned.
 	if grep -qi 'Could not find gdal-config' "${WARNINGS_LOG}"; then
 		output::error <<-'EOF'
@@ -10,8 +10,19 @@ gdal-missing() {
 			https://github.com/heroku/heroku-geo-buildpack
 		EOF
 	fi
-}
 
-show-warnings() {
-	gdal-missing
+	# shellcheck disable=SC2154 # TODO: Env var is referenced but not assigned.
+	if grep -qi 'Please use pip<24.1 if you need to use this version' "${WARNINGS_LOG}"; then
+		output::error <<-'EOF'
+			Error: One of your dependencies contains broken metadata.
+
+			Newer versions of pip reject packages that use invalid versions
+			in their metadata (such as Celery older than v5.2.1).
+
+			Try upgrading to a newer version of the affected package.
+
+			For more help, see:
+			https://devcenter.heroku.com/changelog-items/3073
+		EOF
+	fi
 }

spec/fixtures/requirements_legacy_celery/requirements.txt

@@ -0,0 +1 @@
+celery==5.2.0

spec/hatchet/pip_spec.rb

@@ -285,4 +285,33 @@
       end
     end
   end
+
+  context 'when requirements.txt contains an old version of Celery with invalid metadata' do
+    let(:app) { Hatchet::Runner.new('spec/fixtures/requirements_legacy_celery', allow_failure: true) }
+
+    it 'outputs instructions for how to resolve the build failure' do
+      app.deploy do |app|
+        expect(clean_output(app.output)).to include(<<~OUTPUT)
+          remote:        ERROR: No matching distribution found for celery==5.2.0
+          remote: 
+          remote:  !     Error: One of your dependencies contains broken metadata.
+          remote:  !     
+          remote:  !     Newer versions of pip reject packages that use invalid versions
+          remote:  !     in their metadata (such as Celery older than v5.2.1).
+          remote:  !     
+          remote:  !     Try upgrading to a newer version of the affected package.
+          remote:  !     
+          remote:  !     For more help, see:
+          remote:  !     https://devcenter.heroku.com/changelog-items/3073
+          remote: 
+          remote: 
+          remote:  !     Error: Unable to install dependencies using pip.
+          remote:  !     
+          remote:  !     See the log output above for more information.
+          remote: 
+          remote:  !     Push rejected, failed to compile Python app.
+        OUTPUT
+      end
+    end
+  end
 end