gh-126925: Modify how iOS test results are gathered (#127592)

Adds a `use_system_log` config item to enable stdout/stderr redirection for
Apple platforms. This log streaming is then used by a new iOS test runner
script, allowing the display of test suite output at runtime. The iOS test
runner script can be used by any Python project, not just the CPython test
suite.

4 files changed, 227 insertions, 0 deletions

diff --git a/Lib/_apple_support.py b/Lib/_apple_support.py
new file mode 100644
index 0000000..92febdc
--- /dev/null
+++ b/Lib/_apple_support.py
@@ -0,0 +1,66 @@
+import io
+import sys
+
+
+def init_streams(log_write, stdout_level, stderr_level):
+    # Redirect stdout and stderr to the Apple system log. This method is
+    # invoked by init_apple_streams() (initconfig.c) if config->use_system_logger
+    # is enabled.
+    sys.stdout = SystemLog(log_write, stdout_level, errors=sys.stderr.errors)
+    sys.stderr = SystemLog(log_write, stderr_level, errors=sys.stderr.errors)
+
+
+class SystemLog(io.TextIOWrapper):
+    def __init__(self, log_write, level, **kwargs):
+        kwargs.setdefault("encoding", "UTF-8")
+        kwargs.setdefault("line_buffering", True)
+        super().__init__(LogStream(log_write, level), **kwargs)
+
+    def __repr__(self):
+        return f"<SystemLog (level {self.buffer.level})>"
+
+    def write(self, s):
+        if not isinstance(s, str):
+            raise TypeError(
+                f"write() argument must be str, not {type(s).__name__}")
+
+        # In case `s` is a str subclass that writes itself to stdout or stderr
+        # when we call its methods, convert it to an actual str.
+        s = str.__str__(s)
+
+        # We want to emit one log message per line, so split
+        # the string before sending it to the superclass.
+        for line in s.splitlines(keepends=True):
+            super().write(line)
+
+        return len(s)
+
+
+class LogStream(io.RawIOBase):
+    def __init__(self, log_write, level):
+        self.log_write = log_write
+        self.level = level
+
+    def __repr__(self):
+        return f"<LogStream (level {self.level!r})>"
+
+    def writable(self):
+        return True
+
+    def write(self, b):
+        if type(b) is not bytes:
+            try:
+                b = bytes(memoryview(b))
+            except TypeError:
+                raise TypeError(
+                    f"write() argument must be bytes-like, not {type(b).__name__}"
+                ) from None
+
+        # Writing an empty string to the stream should have no effect.
+        if b:
+            # Encode null bytes using "modified UTF-8" to avoid truncating the
+            # message. This should not affect the return value, as the caller
+            # may be expecting it to match the length of the input.
+            self.log_write(self.level, b.replace(b"\x00", b"\xc0\x80"))
+
+        return len(b)
diff --git a/Lib/test/test_apple.py b/Lib/test/test_apple.py
new file mode 100644
index 0000000..ab5296a
--- /dev/null
+++ b/Lib/test/test_apple.py
@@ -0,0 +1,155 @@
+import unittest
+from _apple_support import SystemLog
+from test.support import is_apple
+from unittest.mock import Mock, call
+
+if not is_apple:
+    raise unittest.SkipTest("Apple-specific")
+
+
+# Test redirection of stdout and stderr to the Apple system log.
+class TestAppleSystemLogOutput(unittest.TestCase):
+    maxDiff = None
+
+    def assert_writes(self, output):
+        self.assertEqual(
+            self.log_write.mock_calls,
+            [
+                call(self.log_level, line)
+                for line in output
+            ]
+        )
+
+        self.log_write.reset_mock()
+
+    def setUp(self):
+        self.log_write = Mock()
+        self.log_level = 42
+        self.log = SystemLog(self.log_write, self.log_level, errors="replace")
+
+    def test_repr(self):
+        self.assertEqual(repr(self.log), "<SystemLog (level 42)>")
+        self.assertEqual(repr(self.log.buffer), "<LogStream (level 42)>")
+
+    def test_log_config(self):
+        self.assertIs(self.log.writable(), True)
+        self.assertIs(self.log.readable(), False)
+
+        self.assertEqual("UTF-8", self.log.encoding)
+        self.assertEqual("replace", self.log.errors)
+
+        self.assertIs(self.log.line_buffering, True)
+        self.assertIs(self.log.write_through, False)
+
+    def test_empty_str(self):
+        self.log.write("")
+        self.log.flush()
+
+        self.assert_writes([])
+
+    def test_simple_str(self):
+        self.log.write("hello world\n")
+
+        self.assert_writes([b"hello world\n"])
+
+    def test_buffered_str(self):
+        self.log.write("h")
+        self.log.write("ello")
+        self.log.write(" ")
+        self.log.write("world\n")
+        self.log.write("goodbye.")
+        self.log.flush()
+
+        self.assert_writes([b"hello world\n", b"goodbye."])
+
+    def test_manual_flush(self):
+        self.log.write("Hello")
+
+        self.assert_writes([])
+
+        self.log.write(" world\nHere for a while...\nGoodbye")
+        self.assert_writes([b"Hello world\n", b"Here for a while...\n"])
+
+        self.log.write(" world\nHello again")
+        self.assert_writes([b"Goodbye world\n"])
+
+        self.log.flush()
+        self.assert_writes([b"Hello again"])
+
+    def test_non_ascii(self):
+        # Spanish
+        self.log.write("ol\u00e9\n")
+        self.assert_writes([b"ol\xc3\xa9\n"])
+
+        # Chinese
+        self.log.write("\u4e2d\u6587\n")
+        self.assert_writes([b"\xe4\xb8\xad\xe6\x96\x87\n"])
+
+        # Printing Non-BMP emoji
+        self.log.write("\U0001f600\n")
+        self.assert_writes([b"\xf0\x9f\x98\x80\n"])
+
+        # Non-encodable surrogates are replaced
+        self.log.write("\ud800\udc00\n")
+        self.assert_writes([b"??\n"])
+
+    def test_modified_null(self):
+        # Null characters are logged using "modified UTF-8".
+        self.log.write("\u0000\n")
+        self.assert_writes([b"\xc0\x80\n"])
+        self.log.write("a\u0000\n")
+        self.assert_writes([b"a\xc0\x80\n"])
+        self.log.write("\u0000b\n")
+        self.assert_writes([b"\xc0\x80b\n"])
+        self.log.write("a\u0000b\n")
+        self.assert_writes([b"a\xc0\x80b\n"])
+
+    def test_nonstandard_str(self):
+        # String subclasses are accepted, but they should be converted
+        # to a standard str without calling any of their methods.
+        class CustomStr(str):
+            def splitlines(self, *args, **kwargs):
+                raise AssertionError()
+
+            def __len__(self):
+                raise AssertionError()
+
+            def __str__(self):
+                raise AssertionError()
+
+        self.log.write(CustomStr("custom\n"))
+        self.assert_writes([b"custom\n"])
+
+    def test_non_str(self):
+        # Non-string classes are not accepted.
+        for obj in [b"", b"hello", None, 42]:
+            with self.subTest(obj=obj):
+                with self.assertRaisesRegex(
+                    TypeError,
+                    fr"write\(\) argument must be str, not "
+                    fr"{type(obj).__name__}"
+                ):
+                    self.log.write(obj)
+
+    def test_byteslike_in_buffer(self):
+        # The underlying buffer *can* accept bytes-like objects
+        self.log.buffer.write(bytearray(b"hello"))
+        self.log.flush()
+
+        self.log.buffer.write(b"")
+        self.log.flush()
+
+        self.log.buffer.write(b"goodbye")
+        self.log.flush()
+
+        self.assert_writes([b"hello", b"goodbye"])
+
+    def test_non_byteslike_in_buffer(self):
+        for obj in ["hello", None, 42]:
+            with self.subTest(obj=obj):
+                with self.assertRaisesRegex(
+                    TypeError,
+                    fr"write\(\) argument must be bytes-like, not "
+                    fr"{type(obj).__name__}"
+                ):
+                    self.log.buffer.write(obj)
diff --git a/Lib/test/test_capi/test_config.py b/Lib/test/test_capi/test_config.py
index 77730ad..a3179ef 100644
--- a/Lib/test/test_capi/test_config.py
+++ b/Lib/test/test_capi/test_config.py
@@ -110,6 +110,10 @@ class CAPITests(unittest.TestCase):
             options.extend((
                 ("_pystats", bool, None),
             ))
+        if support.is_apple:
+            options.extend((
+                ("use_system_logger", bool, None),
+            ))
 
         for name, option_type, sys_attr in options:
             with self.subTest(name=name, option_type=option_type,
diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py
index 5c38b28..7110fb8 100644
--- a/Lib/test/test_embed.py
+++ b/Lib/test/test_embed.py
@@ -649,6 +649,8 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
         CONFIG_COMPAT.update({
             'legacy_windows_stdio': False,
         })
+    if support.is_apple:
+        CONFIG_COMPAT['use_system_logger'] = False
 
     CONFIG_PYTHON = dict(CONFIG_COMPAT,
         _config_init=API_PYTHON,