python · ned-deily · Mar 19, 2024 · Mar 7, 2024 · Mar 7, 2024 · Mar 7, 2024
@@ -1241,6 +1241,74 @@ 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
+   ``{sys.executable}/Frameworks/foo.bar._whiz.framework/_whiz.abi3.dylib``
+   (forming the package name by taking the full import path of the library,
+   and replacing ``/`` with ``.``).
+
+   However, this loader will re-write the ``__file__`` attribute of the
+   ``_whiz`` module will report as the original location inside the ``foo/bar``
-   ``_whiz`` module will report as the original location inside the ``foo/bar``
+   ``_whiz`` module to report the original location inside the ``foo/bar``
-   ``_whiz`` module will report as the original location inside the ``foo/bar``
+   ``_whiz`` module to report 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
 ---------------------------------------------------
 

@@ -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

@@ -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,78 @@ 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.
+
+    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
+    ``{sys.executable}/Frameworks/foo.bar._whiz.framework/_whiz.abi3.dylib``
+    (forming the package name by taking the full import path of the library,
+    and replacing ``/`` with ``.``).
+
+    However, 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 Xcode project building the app is responsible for converting any
+    ``.dylib`` files from wherever they exist in the ``PYTHONPATH`` into
+    frameworks in the ``Frameworks`` folder (including the addition of
+    framework metadata, and signing the resulting framework). This will usually
+    be done with a build step in the Xcode project; see the iOS documentation
+    for details on how to construct this build step.
+    """
+    def __init__(self, fullname, dylib_file, parent_paths=None):
+        super().__init__(fullname, dylib_file)
+        self.parent_paths = parent_paths
+
+    def create_module(self, spec):
+        mod = super().create_module(spec)
+        if self.parent_paths:
+            for parent_path in self.parent_paths:
+                if _path_isdir(parent_path):
+                    mod.__file__ = _path_join(
+                        parent_path,
+                        _path_split(self.path)[-1],
+                    )
+                    break
+        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.split(".")[-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:
+                loader = AppleFrameworkLoader(fullname, dylib_file, paths)
+                return _bootstrap.spec_from_loader(fullname, loader)
+
+        return None
+
 # Import setup ###############################################################
 
 def _fix_up_module(ns, name, pathname, cpathname=None):
@@ -1760,3 +1832,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))
@@ -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
 
 

@@ -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.

@@ -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))