doebuild: Add returnproc parameter and deprecate returnpid

Raise NotImplementedError if returnproc is enabled for anything
other than the "depend" phase, since corresponding returnpid
support has long been deprecated.

Bug: https://bugs.gentoo.org/916566
Signed-off-by: Zac Medico <zmedico@gentoo.org>

2 files changed, 39 insertions, 12 deletions

diff --git a/lib/_emerge/EbuildMetadataPhase.py b/lib/_emerge/EbuildMetadataPhase.py
index a7c9650d7..f4f685e81 100644
--- a/lib/_emerge/EbuildMetadataPhase.py
+++ b/lib/_emerge/EbuildMetadataPhase.py
@@ -124,7 +124,7 @@ class EbuildMetadataPhase(SubProcess):
             mydbapi=self.portdb,
             tree="porttree",
             fd_pipes=fd_pipes,
-            returnpid=True,
+            returnproc=True,
         )
         settings.pop("PORTAGE_PIPE_FD", None)
 
@@ -137,7 +137,7 @@ class EbuildMetadataPhase(SubProcess):
             self._async_wait()
             return
 
-        self._proc = portage.process.Process(retval[0])
+        self._proc = retval
 
     def _output_handler(self):
         while True:
diff --git a/lib/portage/package/ebuild/doebuild.py b/lib/portage/package/ebuild/doebuild.py
index e10b884e0..1c89af5ac 100644
--- a/lib/portage/package/ebuild/doebuild.py
+++ b/lib/portage/package/ebuild/doebuild.py
@@ -19,6 +19,7 @@ import sys
 import tempfile
 from textwrap import wrap
 import time
+from typing import Union
 import warnings
 import zlib
 
@@ -246,14 +247,21 @@ def _doebuild_spawn(phase, settings, actionmap=None, **kwargs):
 
 
 def _spawn_phase(
-    phase, settings, actionmap=None, returnpid=False, logfile=None, **kwargs
+    phase,
+    settings,
+    actionmap=None,
+    returnpid=False,
+    returnproc=False,
+    logfile=None,
+    **kwargs,
 ):
-    if returnpid:
+    if returnproc or returnpid:
         return _doebuild_spawn(
             phase,
             settings,
             actionmap=actionmap,
             returnpid=returnpid,
+            returnproc=returnproc,
             logfile=logfile,
             **kwargs,
         )
@@ -725,7 +733,8 @@ def doebuild(
     prev_mtimes=None,
     fd_pipes=None,
     returnpid=False,
-):
+    returnproc=False,
+) -> Union[int, portage.process.MultiprocessingProcess, list[int]]:
     """
     Wrapper function that invokes specific ebuild phases through the spawning
     of ebuild.sh
@@ -762,9 +771,15 @@ def doebuild(
             for example.
     @type fd_pipes: Dictionary
     @param returnpid: Return a list of process IDs for a successful spawn, or
-            an integer value if spawn is unsuccessful. NOTE: This requires the
-            caller clean up all returned PIDs.
+            an integer value if spawn is unsuccessful. This parameter is supported
+            supported only when mydo is "depend". NOTE: This requires the caller clean
+            up all returned PIDs.
     @type returnpid: Boolean
+    @param returnproc: Return a MultiprocessingProcess instance for a successful spawn, or
+            an integer value if spawn is unsuccessful. This parameter is supported
+            supported only when mydo is "depend". NOTE: This requires the caller to
+            asynchronously wait for the MultiprocessingProcess instance.
+    @type returnproc: Boolean
     @rtype: Boolean
     @return:
     1. 0 for success
@@ -867,17 +882,25 @@ def doebuild(
         writemsg("\n", noiselevel=-1)
         return 1
 
-    if returnpid and mydo != "depend":
+    if (returnproc or returnpid) and mydo != "depend":
         # This case is not supported, since it bypasses the EbuildPhase class
         # which implements important functionality (including post phase hooks
         # and IPC for things like best/has_version and die).
+        if returnproc:
+            raise NotImplementedError(f"returnproc not implemented for phase {mydo}")
         warnings.warn(
             "portage.doebuild() called "
             "with returnpid parameter enabled. This usage will "
             "not be supported in the future.",
-            DeprecationWarning,
+            UserWarning,
             stacklevel=2,
         )
+    elif returnpid:
+        warnings.warn(
+            "The portage.doebuild() returnpid parameter is deprecated and replaced by returnproc",
+            UserWarning,
+            stacklevel=1,
+        )
 
     if mydo == "fetchall":
         fetchall = 1
@@ -1027,10 +1050,14 @@ def doebuild(
 
         # get possible slot information from the deps file
         if mydo == "depend":
-            if not returnpid:
-                raise TypeError("returnpid must be True for depend phase")
+            if not (returnproc or returnpid):
+                raise TypeError("returnproc or returnpid must be True for depend phase")
             return _spawn_phase(
-                mydo, mysettings, fd_pipes=fd_pipes, returnpid=returnpid
+                mydo,
+                mysettings,
+                fd_pipes=fd_pipes,
+                returnpid=returnpid,
+                returnproc=returnproc,
             )
 
         if mydo == "nofetch":