Add platform.android_ver

python · vstinner · Mar 27, 2024 · Mar 12, 2024 · Mar 12, 2024 · Mar 13, 2024
commit ead6dcbd8eda802ca45d52c98d190927852b8078
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
@@ -301,3 +301,34 @@ Linux Platforms
           return ids
 
    .. versionadded:: 3.10
+
+
+Android Platform
+----------------
+
+.. function:: android_ver(release="", api_level=0, min_api_level=0, \
+                          manufacturer="", model="", device="")
+
+   Get Android device information. Returns a :func:`~collections.namedtuple`
+   with the following attributes. Values which cannot be determined are set to
+   the defaults given as parameters.
+
+   * ``release`` - Android version of the device, as a string (e.g. ``"14"``)
+   * ``api_level`` - API level of the device, as an integer (e.g. ``34``)
+   * ``min_api_level`` - Minimum API level this build of Python can run on, as
+      an integer (e.g. ``23``).
+   * ``manufacturer`` - `manufacturer
+      <https://developer.android.com/reference/android/os/Build#MANUFACTURER>`__
+      of the device, as a string (e.g. ``"Google"``)
+   * ``model`` - `model name
+      <https://developer.android.com/reference/android/os/Build#MODEL>`__ of the
+      device, as a string (e.g. ``"Pixel 7"``)
+   * ``device`` - `device name
+      <https://developer.android.com/reference/android/os/Build#DEVICE>`__ of
+      the device, as a string (e.g. ``"panther"``)
+
+   Which one of ``model`` and ``device`` is more likely to be unique, and which
+   one is more likely to resemble the marketing name, varies between different
+   manufacturers.
+
+   .. versionadded:: 3.13
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -753,7 +753,9 @@ always available.
 
 .. function:: getandroidapilevel()
 
-   Return the build time API version of Android as an integer.
+   Return the build-time API level of Android as an integer. This represents the
+   minimum version of Android this build of Python can run on. For runtime
+   version information, see :func:`platform.android_ver`.
 
    .. availability:: Android.
 

diff --git a/Lib/platform.py b/Lib/platform.py
@@ -542,6 +542,45 @@ def java_ver(release='', vendor='', vminfo=('', '', ''), osinfo=('', '', '')):
 
     return release, vendor, vminfo, osinfo
 
+
+AndroidVer = collections.namedtuple(
+    "AndroidVer",
+    "release api_level min_api_level manufacturer model device")
+
+def android_ver(release="", api_level=0, min_api_level=0,
+                manufacturer="", model="", device=""):
+    if sys.platform == "android":
+        min_api_level = sys.getandroidapilevel()
+        try:
+            from ctypes import CDLL, c_char_p, create_string_buffer
+        except ImportError:
+            pass
+        else:
+            # An NDK developer confirmed that this is an officially-supported
+            # API (https://stackoverflow.com/a/28416743). Use `getattr` to avoid
+            # private name mangling.
+            system_property_get = getattr(CDLL("libc.so"), "__system_property_get")
+            system_property_get.argtypes = (c_char_p, c_char_p)
+
+            def getprop(name, default):
+                PROP_VALUE_MAX = 92  # From sys/system_properties.h
+                buffer = create_string_buffer(PROP_VALUE_MAX)
+                length = system_property_get(name.encode("UTF-8"), buffer)
+                if length == 0:
+                    return default
+                else:
+                    return buffer.value.decode("UTF-8", "backslashreplace")
+
+            release = getprop("ro.build.version.release", release)
+            api_level = int(getprop("ro.build.version.sdk", api_level))
+            manufacturer = getprop("ro.product.manufacturer", manufacturer)
+            model = getprop("ro.product.model", model)
+            device = getprop("ro.product.device", device)
+
+    return AndroidVer(
+        release, api_level, min_api_level, manufacturer, model, device)
+
+
 ### System name aliasing
 
 def system_alias(system, release, version):
@@ -972,6 +1011,11 @@ def uname():
         system = 'Windows'
         release = 'Vista'
 
+    # On Android, return the name and version of the OS rather than the kernel.
+    if sys.platform == 'android':
+        system = 'Android'
+        release = android_ver().release
+
     vals = system, node, release, version, machine
     # Replace 'unknown' values with the more portable ''
     _uname_cache = uname_result(*map(_unknown_as_blank, vals))

diff --git a/Lib/test/pythoninfo.py b/Lib/test/pythoninfo.py
@@ -179,6 +179,9 @@ def collect_platform(info_add):
             info_add(f'platform.freedesktop_os_release[{key}]',
                      os_release[key])
 
+    if sys.platform == 'android':
+        info_add('platform.android_ver', platform.android_ver())
+
 
 def collect_locale(info_add):
     import locale

@@ -3,6 +3,7 @@
 import concurrent.futures
 import errno
 import math
+import platform
 import socket
 import sys
 import threading
@@ -1430,6 +1431,10 @@ def test_create_connection_no_inet_pton(self, m_socket):
         self._test_create_connection_ip_addr(m_socket, False)
 
     @patch_socket
+    @unittest.skipIf(
+        support.is_android and platform.android_ver().api_level < 23,
+        "Issue #26936: this fails on Android before API level 23"
+    )
     def test_create_connection_service_name(self, m_socket):
         m_socket.getaddrinfo = socket.getaddrinfo
         sock = m_socket.socket.return_value

diff --git a/Lib/test/test_platform.py b/Lib/test/test_platform.py
@@ -219,6 +219,19 @@ def test_uname(self):
         self.assertEqual(res[-1], res.processor)
         self.assertEqual(len(res), 6)
 
+        if os.name == "posix":
+            uname = os.uname()
+            self.assertEqual(res.node, uname.nodename)
+            self.assertEqual(res.version, uname.version)
+            self.assertEqual(res.machine, uname.machine)
+
+            if sys.platform == "android":
+                self.assertEqual(res.system, "Android")
+                self.assertEqual(res.release, platform.android_ver().release)
+            else:
+                self.assertEqual(res.system, uname.sysname)
+                self.assertEqual(res.release, uname.release)
+
     @unittest.skipUnless(sys.platform.startswith('win'), "windows only test")
     def test_uname_win32_without_wmi(self):
         def raises_oserror(*a):
@@ -430,6 +443,47 @@ def test_libc_ver(self):
         self.assertEqual(platform.libc_ver(filename, chunksize=chunksize),
                          ('glibc', '1.23.4'))
 
+    def test_android_ver(self):
+        res = platform.android_ver()
+        self.assertIsInstance(res, tuple)
+        self.assertEqual(res, (res.release, res.api_level, res.min_api_level,
+                               res.manufacturer, res.model, res.device))
+
+        if sys.platform == "android":
+            for name in ["release", "manufacturer", "model", "device"]:
+                with self.subTest(name):
+                    value = getattr(res, name)
+                    self.assertIsInstance(value, str)
+                    self.assertGreater(len(value), 0)
+
+            for name in ["api_level", "min_api_level"]:
+                with self.subTest(name):
+                    value = getattr(res, name)
+                    self.assertIsInstance(value, int)
+                    self.assertGreater(value, 0)
+
+            self.assertEqual(res.min_api_level, sys.getandroidapilevel())
+            self.assertGreaterEqual(res.api_level, res.min_api_level)
+
+        # When not running on Android, it should return the default values.
+        else:
+            self.assertEqual(res.release, "")
+            self.assertEqual(res.api_level, 0)
+            self.assertEqual(res.min_api_level, 0)
+            self.assertEqual(res.manufacturer, "")
+            self.assertEqual(res.model, "")
+            self.assertEqual(res.device, "")
+
+            # Default values may also be overridden using parameters.
+            res = platform.android_ver("alpha", 1, 2, "bravo", "charlie", "delta")
+            self.assertEqual(res.release, "alpha")
+            self.assertEqual(res.api_level, 1)
+            self.assertEqual(res.min_api_level, 2)
+            self.assertEqual(res.manufacturer, "bravo")
+            self.assertEqual(res.model, "charlie")
+            self.assertEqual(res.device, "delta")
+
+
     @support.cpython_only
     def test__comparable_version(self):
         from platform import _comparable_version as V

diff --git a/Lib/test/test_socket.py b/Lib/test/test_socket.py
@@ -1217,8 +1217,8 @@ def testGetServBy(self):
         else:
             raise OSError
         # Try same call with optional protocol omitted
-        # Issue #26936: Android getservbyname() was broken before API 23.
-        if (not support.is_android) or sys.getandroidapilevel() >= 23:
+        # Issue #26936: this fails on Android before API level 23.
+        if not (support.is_android and platform.android_ver().api_level < 23):
             port2 = socket.getservbyname(service)
             eq(port, port2)
         # Try udp, but don't barf if it doesn't exist
@@ -1229,8 +1229,9 @@ def testGetServBy(self):
         else:
             eq(udpport, port)
         # Now make sure the lookup by port returns the same service name
-        # Issue #26936: Android getservbyport() is broken.
-        if not support.is_android:
+        # Issue #26936: when the protocol is omitted, this fails on Android
+        # before API level 28.
+        if not (support.is_android and platform.android_ver().api_level < 28):
             eq(socket.getservbyport(port2), service)
         eq(socket.getservbyport(port, 'tcp'), service)
         if udpport is not None:
@@ -1575,8 +1576,8 @@ def testGetaddrinfo(self):
             socket.getaddrinfo('::1', 80)
         # port can be a string service name such as "http", a numeric
         # port number or None
-        # Issue #26936: Android getaddrinfo() was broken before API level 23.
-        if (not support.is_android) or sys.getandroidapilevel() >= 23:
+        # Issue #26936: this fails on Android before API level 23.
+        if not (support.is_android and platform.android_ver().api_level < 23):
             socket.getaddrinfo(HOST, "http")
         socket.getaddrinfo(HOST, 80)
         socket.getaddrinfo(HOST, None)