gh-104212: Explain how to port imp code to importlib (#105905)

1 files changed, 32 insertions, 1 deletions

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 8febb6c..1a50bce 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -1369,7 +1369,38 @@ Removed
   * The :mod:`!imp` module has been removed.  (Contributed by Barry Warsaw in
     :gh:`98040`.)
 
-  * Replace ``imp.new_module(name)`` with ``types.ModuleType(name)``.
+  * Replace removed :mod:`!imp` functions with :mod:`importlib` functions:
+
+    =================================  =======================================
+       imp                                importlib
+    =================================  =======================================
+    ``imp.NullImporter``               Insert ``None`` into ``sys.path_importer_cache``
+    ``imp.cache_from_source()``        :func:`importlib.util.cache_from_source`
+    ``imp.find_module()``              :func:`importlib.util.find_spec`
+    ``imp.get_magic()``                :attr:`importlib.util.MAGIC_NUMBER`
+    ``imp.get_suffixes()``             :attr:`importlib.machinery.SOURCE_SUFFIXES`, :attr:`importlib.machinery.EXTENSION_SUFFIXES`, and :attr:`importlib.machinery.BYTECODE_SUFFIXES`
+    ``imp.get_tag()``                  :attr:`sys.implementation.cache_tag <sys.implementation>`
+    ``imp.load_module()``              :func:`importlib.import_module`
+    ``imp.new_module(name)``           ``types.ModuleType(name)``
+    ``imp.reload()``                   :func:`importlib.reload`
+    ``imp.source_from_cache()``        :func:`importlib.util.source_from_cache`
+    =================================  =======================================
+
+  * Removed :mod:`!imp` functions and attributes with no replacements:
+
+    * undocumented functions:
+
+      * ``imp.init_builtin()``
+      * ``imp.load_compiled()``
+      * ``imp.load_dynamic()``
+      * ``imp.load_package()``
+      * ``imp.load_source()``
+
+    * ``imp.lock_held()``, ``imp.acquire_lock()``, ``imp.release_lock()``:
+      the locking scheme has changed in Python 3.3 to per-module locks.
+    * ``imp.find_module()`` constants: ``SEARCH_ERROR``, ``PY_SOURCE``,
+      ``PY_COMPILED``, ``C_EXTENSION``, ``PY_RESOURCE``, ``PKG_DIRECTORY``,
+      ``C_BUILTIN``, ``PY_FROZEN``, ``PY_CODERESOURCE``, ``IMP_HOOK``.
 
 * Removed the ``suspicious`` rule from the documentation Makefile, and
   removed ``Doc/tools/rstlint.py``, both in favor of `sphinx-lint