[3.12] gh-104212: Explain how to port imp code to importlib (GH-105905) (#105952)

gh-104212: Explain how to port imp code to importlib (GH-105905)
(cherry picked from commit 7a56a4148c521969d64164d2776641f19e3ca9e8)

Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 28bd4a8a64ee4b9ad1d2d117dd0e55a5f0d61bd4..ed4657c5b7a4a21c2bfa40e18411c70c5aae0252 100644 (file)
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -1368,7 +1368,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