python*-r1.eclass: Deprecate python_gen_usedep

Deprecate python_gen_usedep() in favor of python_gen_cond_dep().
The latter is a newer API that generates full USE-conditional blocks
rather than pure USE-dependency strings.  As such, it can replace all
uses of the former, and is safer to use in general.  In particular:

  dev-python/foo[$(python_gen_usedep -2)]
  dev-python/bar[$(python_gen_usedep -2)]

installs the dependency (with no implementation match enforced) even
if there's no python2 implementation enabled, while:

  $(python_gen_cond_dep '
    dev-python/foo[${PYTHON_USEDEP}]
    dev-python/bar[${PYTHON_USEDEP}]
  ' -2)

installs it only if there's at least one implementation requiring it.

Since the functions are used in global scope only, a deprecation warning
is emitted only once, during the sourcing for pkg_setup phase.  This
avoids having it output during metadata cache regeneration.

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

2 files changed, 90 insertions, 32 deletions

diff --git a/eclass/python-r1.eclass b/eclass/python-r1.eclass
index 335ae9fe6370..ea4d1e3d4e41 100644
--- a/eclass/python-r1.eclass
+++ b/eclass/python-r1.eclass
@@ -276,9 +276,47 @@ _python_validate_useflags() {
 	die "No supported Python implementation in PYTHON_TARGETS."
 }
 
+# @FUNCTION: _python_gen_usedep
+# @INTERNAL
+# @USAGE: <pattern> [...]
+# @DESCRIPTION:
+# Output a USE dependency string for Python implementations which
+# are both in PYTHON_COMPAT and match any of the patterns passed
+# as parameters to the function.
+#
+# The patterns can be either fnmatch-style patterns (matched via bash
+# == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
+# appropriately all enabled Python 2/3 implementations (alike
+# python_is_python3). Remember to escape or quote the fnmatch patterns
+# to prevent accidental shell filename expansion.
+#
+# This is an internal function used to implement python_gen_cond_dep
+# and deprecated python_gen_usedep.
+_python_gen_usedep() {
+	debug-print-function ${FUNCNAME} "${@}"
+
+	local impl matches=()
+
+	for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
+		if _python_impl_matches "${impl}" "${@}"; then
+			matches+=(
+				"python_targets_${impl}(-)?"
+				"-python_single_target_${impl}(-)"
+			)
+		fi
+	done
+
+	[[ ${matches[@]} ]] || die "No supported implementations match python_gen_usedep patterns: ${@}"
+
+	local out=${matches[@]}
+	echo "${out// /,}"
+}
+
 # @FUNCTION: python_gen_usedep
 # @USAGE: <pattern> [...]
 # @DESCRIPTION:
+# DEPRECATED.  Please use python_gen_cond_dep instead.
+#
 # Output a USE dependency string for Python implementations which
 # are both in PYTHON_COMPAT and match any of the patterns passed
 # as parameters to the function.
@@ -306,21 +344,12 @@ _python_validate_useflags() {
 python_gen_usedep() {
 	debug-print-function ${FUNCNAME} "${@}"
 
-	local impl matches=()
-
-	for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
-		if _python_impl_matches "${impl}" "${@}"; then
-			matches+=(
-				"python_targets_${impl}(-)?"
-				"-python_single_target_${impl}(-)"
-			)
-		fi
-	done
-
-	[[ ${matches[@]} ]] || die "No supported implementations match python_gen_usedep patterns: ${@}"
-
-	local out=${matches[@]}
-	echo "${out// /,}"
+	# output only once, during some reasonable phase
+	# (avoid spamming cache regen runs)
+	if [[ ${EBUILD_PHASE} == setup ]]; then
+		eqawarn "python_gen_usedep() is deprecated. Please use python_gen_cond_dep instead."
+	fi
+	_python_gen_usedep "${@}"
 }
 
 # @FUNCTION: python_gen_useflags
@@ -405,7 +434,7 @@ python_gen_cond_dep() {
 			# (since python_gen_usedep() will not return ${PYTHON_USEDEP}
 			#  the code is run at most once)
 			if [[ ${dep} == *'${PYTHON_USEDEP}'* ]]; then
-				local usedep=$(python_gen_usedep "${@}")
+				local usedep=$(_python_gen_usedep "${@}")
 				dep=${dep//\$\{PYTHON_USEDEP\}/${usedep}}
 			fi
 
diff --git a/eclass/python-single-r1.eclass b/eclass/python-single-r1.eclass
index 8ac17b7815e2..47176f79e6ad 100644
--- a/eclass/python-single-r1.eclass
+++ b/eclass/python-single-r1.eclass
@@ -265,9 +265,47 @@ unset -f _python_single_set_globals
 
 if [[ ! ${_PYTHON_SINGLE_R1} ]]; then
 
+# @FUNCTION: _python_gen_usedep
+# @INTERNAL
+# @USAGE: <pattern> [...]
+# @DESCRIPTION:
+# Output a USE dependency string for Python implementations which
+# are both in PYTHON_COMPAT and match any of the patterns passed
+# as parameters to the function.
+#
+# The patterns can be either fnmatch-style patterns (matched via bash
+# == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
+# appropriately all enabled Python 2/3 implementations (alike
+# python_is_python3). Remember to escape or quote the fnmatch patterns
+# to prevent accidental shell filename expansion.
+#
+# This is an internal function used to implement python_gen_cond_dep
+# and deprecated python_gen_usedep.
+_python_gen_usedep() {
+	debug-print-function ${FUNCNAME} "${@}"
+
+	local impl matches=()
+
+	for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
+		if _python_impl_matches "${impl}" "${@}"; then
+			matches+=(
+				"python_targets_${impl}(-)?"
+				"python_single_target_${impl}(+)?"
+			)
+		fi
+	done
+
+	[[ ${matches[@]} ]] || die "No supported implementations match python_gen_usedep patterns: ${@}"
+
+	local out=${matches[@]}
+	echo "${out// /,}"
+}
+
 # @FUNCTION: python_gen_usedep
 # @USAGE: <pattern> [...]
 # @DESCRIPTION:
+# DEPRECATED.  Please use python_gen_cond_dep instead.
+#
 # Output a USE dependency string for Python implementations which
 # are both in PYTHON_COMPAT and match any of the patterns passed
 # as parameters to the function.
@@ -295,21 +333,12 @@ if [[ ! ${_PYTHON_SINGLE_R1} ]]; then
 python_gen_usedep() {
 	debug-print-function ${FUNCNAME} "${@}"
 
-	local impl matches=()
-
-	for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
-		if _python_impl_matches "${impl}" "${@}"; then
-			matches+=(
-				"python_targets_${impl}(-)?"
-				"python_single_target_${impl}(+)?"
-			)
-		fi
-	done
-
-	[[ ${matches[@]} ]] || die "No supported implementations match python_gen_usedep patterns: ${@}"
-
-	local out=${matches[@]}
-	echo "${out// /,}"
+	# output only once, during some reasonable phase
+	# (avoid spamming cache regen runs)
+	if [[ ${EBUILD_PHASE} == setup ]]; then
+		eqawarn "python_gen_usedep() is deprecated. Please use python_gen_cond_dep instead."
+	fi
+	_python_gen_usedep "${@}"
 }
 
 # @FUNCTION: python_gen_useflags
@@ -407,7 +436,7 @@ python_gen_cond_dep() {
 			# (since python_gen_usedep() will not return ${PYTHON_USEDEP}
 			#  the code is run at most once)
 			if [[ ${dep} == *'${PYTHON_USEDEP}'* ]]; then
-				local usedep=$(python_gen_usedep "${@}")
+				local usedep=$(_python_gen_usedep "${@}")
 				dep=${dep//\$\{PYTHON_USEDEP\}/${usedep}}
 			fi