Record the file encoding of .python-version and runtime.txt (#1948)

To help work out what file encodings are present in the wild,
in order to improve the UX for file parsing related errors that
are believe to be due to encoding issues.

The `file --brief` command will return values like:
- `ASCII text`
- `Unicode text, UTF-8 (with BOM) text`
- `Unicode text, UTF-16, little-endian text, with CRLF line terminators`

These metrics will be removed later.

See:
https://manpages.ubuntu.com/manpages/noble/en/man1/file.1.html

GUS-W-20049083.

Author: edmorley

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [Unreleased]
 
 - Improved the error message when a `.python-version` or `runtime.txt` file contains invisible Unicode whitespace characters. ([#1947](https://github.com/heroku/heroku-buildpack-python/pull/1947))
+- Added metrics for the file encoding of `.python-version` and `runtime.txt` files. ([#1948](https://github.com/heroku/heroku-buildpack-python/pull/1948))
 
 ## [v315] - 2025-10-22
 

lib/python_version.sh

@@ -64,6 +64,8 @@ function python_version::read_requested_python_version() {
 
 	local runtime_txt_path="${build_dir}/runtime.txt"
 	if [[ -f "${runtime_txt_path}" ]]; then
+		# For example: "ASCII text" or "Unicode text, UTF-16, little-endian text, with CRLF line terminators"
+		build_data::set_string "runtime_txt_encoding" "$(file --brief "${runtime_txt_path}" || true)"
 		contents="$(utils::read_file_with_special_chars_substituted "${runtime_txt_path}")"
 		version="$(python_version::parse_runtime_txt "${contents}")"
 		origin="runtime.txt"
@@ -72,6 +74,7 @@ function python_version::read_requested_python_version() {
 
 	local python_version_file_path="${build_dir}/.python-version"
 	if [[ -f "${python_version_file_path}" ]]; then
+		build_data::set_string "python_version_file_encoding" "$(file --brief "${python_version_file_path}" || true)"
 		contents="$(utils::read_file_with_special_chars_substituted "${python_version_file_path}")"
 		version="$(python_version::parse_python_version_file "${contents}")"
 		origin=".python-version"

spec/hatchet/pip_spec.rb

@@ -72,6 +72,7 @@
           remote:   "pre_compile_hook": false,
           remote:   "python_install_duration": [0-9.]+,
           remote:   "python_version": "#{DEFAULT_PYTHON_FULL_VERSION}",
+          remote:   "python_version_file_encoding": "ASCII text",
           remote:   "python_version_files": ".python-version,",
           remote:   "python_version_major": "3.13",
           remote:   "python_version_origin": ".python-version",

spec/hatchet/poetry_spec.rb

@@ -74,6 +74,7 @@
           remote:   "pre_compile_hook": false,
           remote:   "python_install_duration": [0-9.]+,
           remote:   "python_version": "#{DEFAULT_PYTHON_FULL_VERSION}",
+          remote:   "python_version_file_encoding": "ASCII text",
           remote:   "python_version_files": ".python-version,",
           remote:   "python_version_major": "3.13",
           remote:   "python_version_origin": ".python-version",

spec/hatchet/uv_spec.rb

@@ -79,6 +79,7 @@
           remote:   "pre_compile_hook": false,
           remote:   "python_install_duration": [0-9.]+,
           remote:   "python_version": "#{DEFAULT_PYTHON_FULL_VERSION}",
+          remote:   "python_version_file_encoding": "ASCII text",
           remote:   "python_version_files": ".python-version,",
           remote:   "python_version_major": "3.13",
           remote:   "python_version_origin": ".python-version",