This adds support for configuring the app's Python version using a .python-version file. This file is used by several tools in the Python ecosystem (such as pyenv, actions/setup-python, uv), whereas the existing runtime.txt file is proprietary to Heroku.
For now, if both a runtime.txt file and a .python-version file are present, then the runtime.txt file will take precedence. In the future, support for runtime.txt will be deprecated (and eventually removed) in favour of the .python-version file.
We support the following .python-version syntax:
Major Python version (e.g. 3.12, which will then be resolved to the latest Python 3.12). (This form is recommended, since it allows for Python security updates to be pulled in without having to manually bump the version.)
Exact Python version (e.g. 3.12.6)
Comments (lines starting with #)
Blank lines
We don't support the following .python-version features:
Specifying multiple Python versions
Prefixing versions with python- (since this form is undocumented and will likely be deprecated in the future)
Since the .python-version file (unlike runtime.txt) supports specifying just the Python major version, adding support also required:
adding a mapping of major versions to the latest patch releases
explicit handling for EOL/unrecognised major versions
adding the concept of a "requested Python version" vs the resolved Python version (which should hopefully tie in well with use of a manifest in the future)
In addition, the "origin" of a Python version now has to be tracked, so that build output can state which file was used, or in the case of invalid version errors, which file needs to be fixed by the user.
This adds support for configuring the app's Python version using a
.python-versionfile. This file is used by several tools in the Python ecosystem (such as pyenv,actions/setup-python, uv), whereas the existingruntime.txtfile is proprietary to Heroku.For now, if both a
runtime.txtfile and a.python-versionfile are present, then theruntime.txtfile will take precedence. In the future, support forruntime.txtwill be deprecated (and eventually removed) in favour of the.python-versionfile.We support the following
.python-versionsyntax:3.12, which will then be resolved to the latest Python 3.12). (This form is recommended, since it allows for Python security updates to be pulled in without having to manually bump the version.)3.12.6)#)We don't support the following
.python-versionfeatures:python-(since this form is undocumented and will likely be deprecated in the future)Since the
.python-versionfile (unlikeruntime.txt) supports specifying just the Python major version, adding support also required:In addition, the "origin" of a Python version now has to be tracked, so that build output can state which file was used, or in the case of invalid version errors, which file needs to be fixed by the user.
Closes #6. Closes #9. GUS-W-12151504. GUS-W-11475071.