gh-114099 - Add iOS framework loading machinery.

Doc/library/importlib.rst

@@ -1241,6 +1241,73 @@ find and load modules.
     and how the module's :attr:`__file__` is populated.
 
 
+.. class:: AppleFrameworkLoader(fullname, dylib_path, parent_paths=None)
+
+   A specialization of :class:`importlib.machinery.ExtensionFileLoader` that
+   is able to load extension modules in Framework format.
+
+   For compatibility with the iOS App Store, *all* binary modules in an iOS app
+   must be ``.dylib objects``, contained in a framework with appropriate
+   metadata, stored in the ``Frameworks`` folder of the packaged app. There can
+   be only a single binary per framework, and there can be no executable binary
+   material outside the Frameworks folder.
+
+   If you're trying to run ``from foo.bar import _whiz``, and ``_whiz`` is
+   implemented with the binary module ``foo/bar/_whiz.abi3.dylib`` (or any
+   other ABI .dylib extension), this loader will look for
+   ``{dirname(sys.executable)}/Frameworks/foo.bar._whiz.framework/_whiz.abi3.dylib``
+   (forming the framework name from the full name of the module).
+
+   However, this loader will re-write the ``__file__`` attribute of the
+   ``_whiz`` module will report as the original location inside the ``foo/bar``
+   subdirectory. This so that code that depends on walking directory trees will
+   continue to work as expected based on the *original* file location.
+
+   The *fullname* argument specifies the name of the module the loader is to
+   support. The *dylib_path* argument is the path to the framework's ``.dylib``
+   file. The ``parent_paths`` is the path or paths that was searched to find
+   the extension module.
+
+   .. versionadded:: 3.13
+
+   .. availability:: iOS.
+
+   .. attribute:: fullname
+
+      Name of the module the loader supports.
+
+   .. attribute:: dylib_path
+
+      Path to the ``.dylib`` file in the framework.
+
+   .. attribute:: parent_paths
+
+      The parent paths that were originally searched to find the module.
+
+.. class:: AppleFrameworkFinder(framework_path)
+
+   An extension module finder which is able to load extension modules packaged
+   as frameworks in an iOS app.
+
+   See the documentation for :class:`AppleFrameworkLoader` for details on the
+   requirements of binary extension modules on iOS.
+
+   The *framework_path* argument is the Frameworks directory for the app.
+
+   .. versionadded:: 3.13
+
+   .. availability:: iOS.
+
+   .. attribute:: framework_path
+
+      The path the finder will search for frameworks.
+
+   .. method:: find_spec(fullname, paths, target=None)
+
+      Attempt to find the spec to handle ``fullname``, imported from one
+      of the filesystem locations described by ``paths``.
+
+
 :mod:`importlib.util` -- Utility code for importers
 ---------------------------------------------------
 

Doc/tools/extensions/pyspecific.py

@@ -133,7 +133,7 @@ class Availability(SphinxDirective):
     known_platforms = frozenset({
         "AIX", "Android", "BSD", "DragonFlyBSD", "Emscripten", "FreeBSD",
         "GNU/kFreeBSD", "Linux", "NetBSD", "OpenBSD", "POSIX", "Solaris",
-        "Unix", "VxWorks", "WASI", "Windows", "macOS",
+        "Unix", "VxWorks", "WASI", "Windows", "macOS", "iOS",
         # libc
         "BSD libc", "glibc", "musl",
         # POSIX platforms with pthreads

Lib/importlib/_bootstrap_external.py

@@ -52,7 +52,7 @@
 
 # Bootstrap-related code ######################################################
 _CASE_INSENSITIVE_PLATFORMS_STR_KEY = 'win',
-_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY = 'cygwin', 'darwin'
+_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY = 'cygwin', 'darwin', 'ios', 'tvos', 'watchos'
 _CASE_INSENSITIVE_PLATFORMS =  (_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY
                                 + _CASE_INSENSITIVE_PLATFORMS_STR_KEY)
 
@@ -1711,6 +1711,57 @@ def __repr__(self):
         return f'FileFinder({self.path!r})'
 
 
+class AppleFrameworkLoader(ExtensionFileLoader):
+    """A loader for modules that have been packaged as frameworks for
+    compatibility with Apple's iOS App Store policies.
+    """
+    def create_module(self, spec):
+        mod = super().create_module(spec)
+        if spec.loader_state.origfile is not None:
+            mod.__file__ = spec.loader_state.origfile
+        return mod
+
+
+class AppleFrameworkFinder:
+    """A finder for modules that have been packaged as Apple Frameworks
+    for compatibility with Apple's App Store policies.
+
+    See AppleFrameworkLoader for details.
+    """
+    def __init__(self, frameworks_path):
+        self.frameworks_path = frameworks_path
+
+    def find_spec(self, fullname, paths, target=None):
+        name = fullname.rpartition(".")[-1]
+
+        for extension in EXTENSION_SUFFIXES:
+            dylib_file = _path_join(
+                self.frameworks_path,
+                f"{fullname}.framework",
+                f"{name}{extension}",
+            )
+            _bootstrap._verbose_message("Looking for Apple Framework dylib {}", dylib_file)
+
+            dylib_exists = _path_isfile(dylib_file)
+            if dylib_exists:
+                origfile = None
+                if paths:
+                    for parent_path in paths:
+                        if _path_isdir(parent_path):
+                            origfile = _path_join(
+                                parent_path,
+                                _path_split(self.path)[-1],
+                            )
+                            break
+                loader = AppleFrameworkLoader(fullname, dylib_file)
+                spec = _bootstrap.spec_from_loader(fullname, loader)
+                spec.loader_state = type(sys.implementation)(
+                    origfile=origfile,
+                )
+                return spec
+
+        return None
+
 # Import setup ###############################################################
 
 def _fix_up_module(ns, name, pathname, cpathname=None):
@@ -1760,3 +1811,7 @@ def _install(_bootstrap_module):
     supported_loaders = _get_supported_file_loaders()
     sys.path_hooks.extend([FileFinder.path_hook(*supported_loaders)])
     sys.meta_path.append(PathFinder)
+    if sys.platform in {"ios", "tvos", "watchos"}:
+        frameworks_folder = _path_join(_path_split(sys.executable)[0], "Frameworks")
+        _bootstrap._verbose_message("Adding Apple Framework dylib finder at {}", frameworks_folder)
+        sys.meta_path.append(AppleFrameworkFinder(frameworks_folder))

Lib/importlib/machinery.py

@@ -12,6 +12,8 @@
 from ._bootstrap_external import SourceFileLoader
 from ._bootstrap_external import SourcelessFileLoader
 from ._bootstrap_external import ExtensionFileLoader
+from ._bootstrap_external import AppleFrameworkLoader
+from ._bootstrap_external import AppleFrameworkFinder
 from ._bootstrap_external import NamespaceLoader
 
 

Lib/test/test_import/__init__.py

@@ -5,7 +5,7 @@
 import importlib.util
 from importlib._bootstrap_external import _get_sourcefile
 from importlib.machinery import (
-    BuiltinImporter, ExtensionFileLoader, FrozenImporter, SourceFileLoader,
+    AppleFrameworkLoader, BuiltinImporter, ExtensionFileLoader, FrozenImporter, SourceFileLoader,
 )
 import marshal
 import os
@@ -25,7 +25,7 @@
 
 from test.support import os_helper
 from test.support import (
-    STDLIB_DIR, swap_attr, swap_item, cpython_only, is_emscripten,
+    STDLIB_DIR, swap_attr, swap_item, cpython_only, is_apple_mobile, is_emscripten,
     is_wasi, run_in_subinterp, run_in_subinterp_with_config, Py_TRACE_REFS)
 from test.support.import_helper import (
     forget, make_legacy_pyc, unlink, unload, ready_to_import,
@@ -66,6 +66,7 @@ def _require_loader(module, loader, skip):
     MODULE_KINDS = {
         BuiltinImporter: 'built-in',
         ExtensionFileLoader: 'extension',
+        AppleFrameworkLoader: 'framework extension',
         FrozenImporter: 'frozen',
         SourceFileLoader: 'pure Python',
     }
@@ -91,7 +92,10 @@ def require_builtin(module, *, skip=False):
     assert module.__spec__.origin == 'built-in', module.__spec__
 
 def require_extension(module, *, skip=False):
-    _require_loader(module, ExtensionFileLoader, skip)
+    if is_apple_mobile:
+        _require_loader(module, AppleFrameworkLoader, skip)
+    else:
+        _require_loader(module, ExtensionFileLoader, skip)
 
 def require_frozen(module, *, skip=True):
     module = _require_loader(module, FrozenImporter, skip)
@@ -360,7 +364,7 @@ def test_from_import_missing_attr_has_name_and_so_path(self):
             self.assertEqual(cm.exception.path, _testcapi.__file__)
             self.assertRegex(
                 str(cm.exception),
-                r"cannot import name 'i_dont_exist' from '_testcapi' \(.*\.(so|pyd)\)"
+                r"cannot import name 'i_dont_exist' from '_testcapi' \(.*\.(so|dylib|pyd)\)"
             )
         else:
             self.assertEqual(
@@ -1689,6 +1693,12 @@ def pipe(self):
             os.set_blocking(r, False)
         return (r, w)
 
+    def create_extension_loader(self, modname, filename):
+        if is_apple_mobile:
+            return AppleFrameworkLoader(modname, filename, None)
+        else:
+            return ExtensionFileLoader(modname, filename)
+
     def import_script(self, name, fd, filename=None, check_override=None):
         override_text = ''
         if check_override is not None:
@@ -1883,7 +1893,7 @@ def test_multi_init_extension_compat(self):
     def test_multi_init_extension_non_isolated_compat(self):
         modname = '_test_non_isolated'
         filename = _testmultiphase.__file__
-        loader = ExtensionFileLoader(modname, filename)
+        loader = self.create_extension_loader(modname, filename)
         spec = importlib.util.spec_from_loader(modname, loader)
         module = importlib.util.module_from_spec(spec)
         loader.exec_module(module)
@@ -1901,7 +1911,7 @@ def test_multi_init_extension_non_isolated_compat(self):
     def test_multi_init_extension_per_interpreter_gil_compat(self):
         modname = '_test_shared_gil_only'
         filename = _testmultiphase.__file__
-        loader = ExtensionFileLoader(modname, filename)
+        loader = self.create_extension_loader(modname, filename)
         spec = importlib.util.spec_from_loader(modname, loader)
         module = importlib.util.module_from_spec(spec)
         loader.exec_module(module)
@@ -2034,10 +2044,13 @@ class SinglephaseInitTests(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         spec = importlib.util.find_spec(cls.NAME)
-        from importlib.machinery import ExtensionFileLoader
+        from importlib.machinery import AppleFrameworkLoader, ExtensionFileLoader
         cls.FILE = spec.origin
         cls.LOADER = type(spec.loader)
-        assert cls.LOADER is ExtensionFileLoader
+        if is_apple_mobile:
+            assert cls.LOADER is AppleFrameworkLoader
+        else:
+            assert cls.LOADER is ExtensionFileLoader
 
         # Start fresh.
         cls.clean_up()
@@ -2077,7 +2090,10 @@ def _load_dynamic(self, name, path):
         """
         # This is essentially copied from the old imp module.
         from importlib._bootstrap import _load
-        loader = self.LOADER(name, path)
+        if is_apple_mobile:
+            loader = self.LOADER(name, path, None)
+        else:
+            loader = self.LOADER(name, path)
 
         # Issue bpo-24748: Skip the sys.modules check in _load_module_shim;
         # always load new extension.

Lib/test/test_importlib/extension/test_finder.py

@@ -1,8 +1,10 @@
+from test.support import is_apple_mobile
 from test.test_importlib import abc, util
 
 machinery = util.import_importlib('importlib.machinery')
 
 import unittest
+import os
 import sys
 
 
@@ -19,11 +21,25 @@ def setUp(self):
             )
 
     def find_spec(self, fullname):
-        importer = self.machinery.FileFinder(util.EXTENSIONS.path,
-                                            (self.machinery.ExtensionFileLoader,
-                                             self.machinery.EXTENSION_SUFFIXES))
+        if is_apple_mobile:
+            # Apple extensions must be distributed as frameworks. This requires
+            # a specialist finder.
+            frameworks_folder = os.path.join(
+                os.path.split(sys.executable)[0], "Frameworks"
+            )
+            importer = self.machinery.AppleFrameworkFinder(frameworks_folder)
+
+            return importer.find_spec(fullname, None)
+        else:
+            importer = self.machinery.FileFinder(
+                util.EXTENSIONS.path,
+                (
+                    self.machinery.ExtensionFileLoader,
+                    self.machinery.EXTENSION_SUFFIXES
+                )
+            )
 
-        return importer.find_spec(fullname)
+            return importer.find_spec(fullname)
 
     def test_module(self):
         self.assertTrue(self.find_spec(util.EXTENSIONS.name))