non functional: Add comments about imp module removal in Python 3.12

ansible_mitogen/module_finder.py

@@ -40,6 +40,13 @@ import mitogen.master
 PREFIX = 'ansible.module_utils.'
 
 
+# Analog of `importlib.machinery.ModuleSpec` or `pkgutil.ModuleInfo`.
+#   name    Unqualified name of the module.
+#   path    Filesystem path of the module.
+#   kind    One of the constants in `imp`, as returned in `imp.find_module()`
+#   parent  `ansible_mitogen.module_finder.Module` of parent package (if any).
+#
+# FIXME Python 3.12 removed `imp`, leaving no constants for `Module.kind`.
 Module = collections.namedtuple('Module', 'name path kind parent')
 
 

ansible_mitogen/runner.py

@@ -521,6 +521,7 @@ class ModuleUtilsImporter(object):
         path, is_pkg = self._by_fullname[fullname]
         source = ansible_mitogen.target.get_small_file(self._context, path)
         code = compile(source, path, 'exec', 0, 1)
+        # FIXME Python 3.12 removed `imp`
         mod = sys.modules.setdefault(fullname, imp.new_module(fullname))
         mod.__file__ = "master:%s" % (path,)
         mod.__loader__ = self

mitogen/core.py

@@ -1360,12 +1360,20 @@ class Importer(object):
         if fullname == '__main__':
             raise ModuleNotFoundError()
 
+        # For a module inside a package (e.g. pkg_a.mod_b) use the search path
+        # of that package (e.g. ['/usr/lib/python3.11/site-packages/pkg_a']).
         parent, _, modname = str_rpartition(fullname, '.')
         if parent:
             path = sys.modules[parent].__path__
         else:
             path = None
 
+        # For a top-level module search builtin modules, frozen modules,
+        # system specific locations (e.g. Windows registry, site-packages).
+        # Otherwise use search path of the parent package.
+        # Works for both stdlib modules & third-party modules.
+        # If the search is unsuccessful then raises ImportError.
+        # FIXME Python 3.12 removed `imp`.
         fp, pathname, description = imp.find_module(modname, path)
         if fp:
             fp.close()
@@ -1377,8 +1385,9 @@ class Importer(object):
         Implements importlib.abc.MetaPathFinder.find_module().
         Deprecrated in Python 3.4+, replaced by find_spec().
         Raises ImportWarning in Python 3.10+.
+        Removed in Python 3.12.
 
-        fullname    A (fully qualified?) module name, e.g. "os.path".
+        fullname    Fully qualified module name, e.g. "os.path".
         path        __path__ of parent packge. None for a top level module.
         """
         if hasattr(_tls, 'running'):
@@ -1521,6 +1530,7 @@ class Importer(object):
             raise ModuleNotFoundError(self.absent_msg % (fullname,))
 
         pkg_present = ret[1]
+        # FIXME Python 3.12 removed `imp`
         mod = sys.modules.setdefault(fullname, imp.new_module(fullname))
         mod.__file__ = self.get_filename(fullname)
         mod.__loader__ = self
@@ -3921,6 +3931,7 @@ class ExternalContext(object):
 
     def _setup_package(self):
         global mitogen
+        # FIXME Python 3.12 removed `imp`
         mitogen = imp.new_module('mitogen')
         mitogen.__package__ = 'mitogen'
         mitogen.__path__ = []

mitogen/master.py

@@ -123,6 +123,10 @@ def is_stdlib_name(modname):
     Return :data:`True` if `modname` appears to come from the standard library.
     """
     # `imp.is_builtin()` isn't a documented as part of Python's stdlib API.
+    # Returns 1 if modname names a module that is "builtin" to the the Python
+    # interpreter (e.g. '_sre'). Otherwise 0 (e.g. 're', 'netifaces').
+    # FIXME Python 3.12 removed `imp`, but `_imp.is_builtin()` remains.
+    #       `sys.builtin_module_names` (Python 2.2+) may be an alternative.
     #
     # """
     # Main is a little special - imp.is_builtin("__main__") will return False,
@@ -759,6 +763,7 @@ class ParentEnumerationMethod(FinderMethod):
     def _find_one_component(self, modname, search_path):
         try:
             #fp, path, (suffix, _, kind) = imp.find_module(modname, search_path)
+            # FIXME The imp module was removed in Python 3.12.
             return imp.find_module(modname, search_path)
         except ImportError:
             e = sys.exc_info()[1]
@@ -787,11 +792,13 @@ class ParentEnumerationMethod(FinderMethod):
                 # Still more components to descent. Result must be a package
                 if fp:
                     fp.close()
+                # FIXME The imp module was removed in Python 3.12.
                 if kind != imp.PKG_DIRECTORY:
                     LOG.debug('%r: %r appears to be child of non-package %r',
                               self, fullname, path)
                     return None
                 search_path = [path]
+            # FIXME The imp module was removed in Python 3.12.
             elif kind == imp.PKG_DIRECTORY:
                 return self._found_package(fullname, path)
             else: