devlib: Add Target.execute_raw() method

Add a Target.execute_raw() method that provides raw stderr and stdout output as
bytestring.

This allows dealing with binary data in the output of commands and also
splitting stdout stderr.

Author: douglas-raillard-arm

devlib/target.py

@@ -54,7 +54,9 @@
 from devlib.exception import (DevlibTransientError, TargetStableError,
                               TargetNotRespondingError, TimeoutError,
                               TargetTransientError, KernelConfigKeyError,
-                              TargetError, HostError, TargetCalledProcessError) # pylint: disable=redefined-builtin
+                              TargetError, HostError, TargetCalledProcessError,
+                              TargetStableCalledProcessError, TargetTransientCalledProcessError,
+                              ) # pylint: disable=redefined-builtin
 from devlib.utils.ssh import SshConnection
 from devlib.utils.android import AdbConnection, AndroidProperties, LogcatMonitor, adb_command, adb_disconnect, INTENT_FLAGS
 from devlib.utils.misc import memoized, isiterable, convert_new_lines, groupby_value
@@ -888,6 +890,32 @@ def _execute(self, command, timeout=None, check_exit_code=True,
                 check_exit_code=check_exit_code, as_root=as_root,
                 strip_colors=strip_colors, will_succeed=will_succeed)
 
+    @asyn.asyncf
+    @call_conn
+    async def execute_raw(self, command, *, timeout=None, check_exit_code=True,
+                as_root=False, will_succeed=False, force_locale='C'):
+        bg = self.background(
+            command=command,
+            as_root=as_root,
+            force_locale=force_locale,
+        )
+
+        # TODO: make BackgroundCommand API async-friendly and use that
+        with bg as bg:
+            try:
+                # Timeout on communicate() usually saves a thread
+                stdout, stderr = bg.communicate(timeout=timeout)
+            except subprocess.CalledProcessError as e:
+                if check_exit_code:
+                    if will_succeed:
+                        raise TargetTransientCalledProcessError(*e.args)
+                    else:
+                        raise
+                else:
+                    return (e.stdout, e.stderr)
+            else:
+                return (stdout, stderr)
+
     execute = asyn._AsyncPolymorphicFunction(
         asyn=_execute_async.asyn,
         blocking=_execute,

doc/target.rst

@@ -275,7 +275,7 @@ Target
         notably paramiko + OpenSSH combination having performance issues when
         pulling big files from sysfs.
 
-.. method:: Target.execute(command [, timeout [, check_exit_code [, as_root [, strip_colors [, will_succeed [, force_locale]]]]]])
+.. method:: Target.execute(command [, timeout [, check_exit_code [, as_root [, strip_colors [, will_succeed [, force_locale, ]]]]]])
 
    Execute the specified command on the target device and return its output.
 
@@ -299,6 +299,11 @@ Target
       command to get predictable output that can be more safely parsed.
       If ``None``, no locale is prepended.
 
+.. method:: Target.execute_raw(command [, timeout [, check_exit_code [, as_root [, will_succeed [, force_locale, ]]]]])
+
+   Same as :meth:`Target.execute` except that it will return a ``tuple(stdout, stderr)`` of
+   bytestrings.
+
 .. method:: Target.background(command [, stdout [, stderr [, as_root, [, force_locale [, timeout]]])
 
    Execute the command on the target, invoking it via subprocess on the host.