python-utils-r1.eclass: Add a sanity check for PYTHONPATH

Add a sanity check that ensures that PYTHONPATH does not contain any
relative paths.  While at it, also explicitly warn about PYTHONPATH
being set, so we know about it in build logs.

Signed-off-by: Michał Górny <mgorny@gentoo.org>

5 files changed, 41 insertions, 2 deletions

diff --git a/eclass/distutils-r1.eclass b/eclass/distutils-r1.eclass
index 4afee3d45b1c..5d9f97474b29 100644
--- a/eclass/distutils-r1.eclass
+++ b/eclass/distutils-r1.eclass
@@ -936,6 +936,7 @@ _distutils-r1_print_package_versions() {
 # distutils patches and/or quirks.
 distutils-r1_python_prepare_all() {
 	debug-print-function ${FUNCNAME} "${@}"
+	_python_sanity_checks
 	_distutils-r1_check_all_phase_mismatch
 
 	if [[ ! ${DISTUTILS_OPTIONAL} ]]; then
diff --git a/eclass/python-any-r1.eclass b/eclass/python-any-r1.eclass
index a21df8e89498..c1f27cfbac0d 100644
--- a/eclass/python-any-r1.eclass
+++ b/eclass/python-any-r1.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2023 Gentoo Authors
+# Copyright 1999-2024 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: python-any-r1.eclass
@@ -272,6 +272,7 @@ python_gen_any_dep() {
 # This function will call python_check_deps() if defined.
 python_setup() {
 	debug-print-function ${FUNCNAME} "${@}"
+	_python_sanity_checks
 
 	# support developer override
 	if [[ ${PYTHON_COMPAT_OVERRIDE} ]]; then
diff --git a/eclass/python-r1.eclass b/eclass/python-r1.eclass
index c5fa6770558f..adf87c2c52f7 100644
--- a/eclass/python-r1.eclass
+++ b/eclass/python-r1.eclass
@@ -617,6 +617,7 @@ _python_multibuild_wrapper() {
 # locally, and the former two are exported to the command environment.
 python_foreach_impl() {
 	debug-print-function ${FUNCNAME} "${@}"
+	_python_sanity_checks
 
 	if [[ ${_DISTUTILS_R1_ECLASS} ]]; then
 		if has "${EBUILD_PHASE}" prepare configure compile test install &&
@@ -708,6 +709,7 @@ python_foreach_impl() {
 # @CODE
 python_setup() {
 	debug-print-function ${FUNCNAME} "${@}"
+	_python_sanity_checks
 
 	local has_check_deps
 	declare -f python_check_deps >/dev/null && has_check_deps=1
diff --git a/eclass/python-single-r1.eclass b/eclass/python-single-r1.eclass
index 4d61f08c06f0..481b6cf91ba0 100644
--- a/eclass/python-single-r1.eclass
+++ b/eclass/python-single-r1.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2022 Gentoo Authors
+# Copyright 1999-2024 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: python-single-r1.eclass
@@ -393,6 +393,7 @@ python_gen_impl_dep() {
 # the Python build environment up for it.
 python_setup() {
 	debug-print-function ${FUNCNAME} "${@}"
+	_python_sanity_checks
 
 	unset EPYTHON
 
diff --git a/eclass/python-utils-r1.eclass b/eclass/python-utils-r1.eclass
index c47565fa1db2..cc33a1c1bffd 100644
--- a/eclass/python-utils-r1.eclass
+++ b/eclass/python-utils-r1.eclass
@@ -1544,4 +1544,38 @@ python_has_version() {
 	return 0
 }
 
+# @FUNCTION: _python_sanity_checks
+# @INTERNAL
+# @DESCRIPTION:
+# Perform additional environment sanity checks.
+_python_sanity_checks() {
+	debug-print-function ${FUNCNAME} "${@}"
+
+	[[ ${_PYTHON_SANITY_CHECKED} ]] && return
+
+	if [[ -v PYTHONPATH ]]; then
+		local x paths=()
+		mapfile -d ':' -t paths <<<${PYTHONPATH}
+
+		for x in "${paths[@]}"; do
+			if [[ ${x} != /* ]]; then
+				eerror "Relative path found in PYTHONPATH:"
+				eerror
+				eerror "  PYTHONPATH=${PYTHONPATH@Q}"
+				eerror
+				eerror "This is guaranteed to cause random breakage.  Please make sure that"
+				eerror "your PYTHONPATH contains absolute paths only (and only if necessary)."
+				eerror "Note that empty values (including ':' at either end and an empty"
+				eerror "PYTHONPATH) count as the current directory.  If no PYTHONPATH"
+				eerror "is intended, it needs to be unset instead."
+				die "Relative paths in PYTHONPATH are forbidden: ${x@Q}"
+			fi
+		done
+
+		elog "PYTHONPATH=${PYTHONPATH@Q}"
+	fi
+
+	_PYTHON_SANITY_CHECKED=1
+}
+
 fi