Deprecate implicit setup.py support (#1897)

Currently if an app has only a `setup.py` file and no Python package
manager files (such as `requirements.txt`, `Pipfile.lock`, `Poetry.lock`
or `uv.lock`), the buildpack will install the project using
`pip install --editable .`

However, there is nothing pip-specific about `setup.py` - the file is
not a package manager dependency file but instead a setuptools package
file, and could easily be installed by any package manager. In addition,
some projects may want to install this file in standard rather than
editable mode.

As such, it's best that the buildpack doesn't guess which package
manager and mode to use, and instead we require explicit configuration
from the user.

For example in the form of a `requirements.txt` file that references the
package definition, via this single line in the requirements file:

```
--editable .
```

That said, in general we recommend people don't use `setup.py` to declare
their dependencies, since:
(a) the file is deprecated in favour of `pyproject.toml`
(b) it's intended more for libraries rather than applications, and it's
    much less common (and practical) to list all transitive dependencies
    in a `setup.py`, meaning apps using the file typically have unpinned
    dependencies, which is a production reliability risk. (Apps should
    either be using a package manager that supports lockfiles, or else
    using one of the pip requirements files substitutes like pip-tools
    or `pip freeze` etc).

The existing metrics for this fallback show usage to be very low, so
we'll likely not wait long before converting this warning to an error
(particularly since fixing the error is a case of adding a single
line requirements file, so fairly simple).

GUS-W-19275438.

Author: edmorley

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Deprecated support for falling back to installing dependencies from a `setup.py` file if no Python package manager files were found. ([#1897](https://github.com/heroku/heroku-buildpack-python/pull/1897))
 
 ## [v306] - 2025-09-09
 

lib/package_manager.sh

@@ -57,14 +57,32 @@ function package_manager::determine_package_manager() {
 		package_managers_found_display_text+=("uv.lock (uv)")
 	fi
 
-	# TODO: Deprecate/sunset this fallback, since using setup.py declared dependencies is
-	# not a best practice, and we can only guess as to which package manager to use.
 	if ((${#package_managers_found[@]} == 0)) && [[ -f "${build_dir}/setup.py" ]]; then
 		package_managers_found+=(pip)
 		package_managers_found_display_text+=("setup.py (pip)")
+		output::warning <<-EOF
+			Warning: Implicit setup.py file support is deprecated.
+
+			Your app currently only has a setup.py file and no Python
+			package manager files. This means that the buildpack has
+			to guess which package manager you want to use and also
+			whether to install your project in editable mode or not.
+
+			For now, we will use pip to install your dependencies in
+			editable mode, however, this fallback is deprecated and
+			will be removed in the future.
+
+			Please add an explicit package manager file to your app.
+
+			To continue using pip in editable mode, create a new file
+			in the root directory of your app named 'requirements.txt'
+			containing the requirement '--editable .' (without quotes).
+
+			Alternatively, if you wish to switch to another package
+			manager, we highly recommend uv:
+			https://docs.astral.sh/uv/
+		EOF
 		build_data::set_raw "setup_py_only" "true"
-	else
-		build_data::set_raw "setup_py_only" "false"
 	fi
 
 	local num_package_managers_found=${#package_managers_found[@]}

lib/pip.sh

@@ -90,7 +90,7 @@ function pip::install_dependencies() {
 		install
 	)
 
-	# TODO: Deprecate/sunset this missing requirements file fallback.
+	# Support for the setup.py fallback is deprecated and will be removed in the future.
 	if [[ -f setup.py && ! -f requirements.txt ]]; then
 		pip_install_command+=(--editable .)
 	else

spec/hatchet/package_manager_spec.rb

@@ -49,14 +49,36 @@
     end
   end
 
-  # TODO: Deprecate/sunset the setup.py file fallback.
+  # This case will be turned into an error in the future.
   context 'when there is only a setup.py' do
     let(:app) { Hatchet::Runner.new('spec/fixtures/setup_py_only') }
 
     it 'installs packages from setup.py using pip' do
       app.deploy do |app|
         expect(clean_output(app.output)).to match(Regexp.new(<<~REGEX, Regexp::MULTILINE))
           remote: -----> Python app detected
+          remote: 
+          remote:  !     Warning: Implicit setup.py file support is deprecated.
+          remote:  !     
+          remote:  !     Your app currently only has a setup.py file and no Python
+          remote:  !     package manager files. This means that the buildpack has
+          remote:  !     to guess which package manager you want to use and also
+          remote:  !     whether to install your project in editable mode or not.
+          remote:  !     
+          remote:  !     For now, we will use pip to install your dependencies in
+          remote:  !     editable mode, however, this fallback is deprecated and
+          remote:  !     will be removed in the future.
+          remote:  !     
+          remote:  !     Please add an explicit package manager file to your app.
+          remote:  !     
+          remote:  !     To continue using pip in editable mode, create a new file
+          remote:  !     in the root directory of your app named 'requirements.txt'
+          remote:  !     containing the requirement '--editable .' \\(without quotes\\).
+          remote:  !     
+          remote:  !     Alternatively, if you wish to switch to another package
+          remote:  !     manager, we highly recommend uv:
+          remote:  !     https://docs.astral.sh/uv/
+          remote: 
           remote: -----> Using Python #{DEFAULT_PYTHON_MAJOR_VERSION} specified in .python-version
           remote: -----> Installing Python #{DEFAULT_PYTHON_FULL_VERSION}
           remote: -----> Installing pip #{PIP_VERSION}

spec/hatchet/pip_spec.rb

@@ -77,7 +77,6 @@
           remote:   "python_version_outdated": false,
           remote:   "python_version_pinned": false,
           remote:   "python_version_requested": "3.13",
-          remote:   "setup_py_only": false,
           remote:   "total_duration": [0-9.]+
           remote: \\}
         REGEX

spec/hatchet/pipenv_spec.rb

@@ -79,7 +79,6 @@
           remote:   "python_version_outdated": false,
           remote:   "python_version_pinned": false,
           remote:   "python_version_requested": "3.13",
-          remote:   "setup_py_only": false,
           remote:   "total_duration": [0-9.]+
           remote: \\}
         REGEX

spec/hatchet/poetry_spec.rb

@@ -79,7 +79,6 @@
           remote:   "python_version_outdated": false,
           remote:   "python_version_pinned": false,
           remote:   "python_version_requested": "3.13",
-          remote:   "setup_py_only": false,
           remote:   "total_duration": [0-9.]+
           remote: \\}
         REGEX

spec/hatchet/uv_spec.rb

@@ -84,7 +84,6 @@
           remote:   "python_version_outdated": false,
           remote:   "python_version_pinned": false,
           remote:   "python_version_requested": "3.13",
-          remote:   "setup_py_only": false,
           remote:   "total_duration": [0-9.]+,
           remote:   "uv_version": "#{UV_VERSION}"
           remote: \\}