gh-123084: Turn shutil.ExecError into a deprecated alias of RuntimeError

Doc/deprecations/pending-removal-in-future.rst

@@ -154,3 +154,6 @@ although there is currently no date scheduled for their removal.
 
 * :meth:`zipimport.zipimporter.load_module` is deprecated:
   use :meth:`~zipimport.zipimporter.exec_module` instead.
+
+* :class:`!shutil.ExecError` is deprecated:
+  use :class:`RuntimeError` instead.

Lib/shutil.py

@@ -56,7 +56,7 @@
 
 __all__ = ["copyfileobj", "copyfile", "copymode", "copystat", "copy", "copy2",
            "copytree", "move", "rmtree", "Error", "SpecialFileError",
-           "ExecError", "make_archive", "get_archive_formats",
+           "make_archive", "get_archive_formats",
            "register_archive_format", "unregister_archive_format",
            "get_unpack_formats", "register_unpack_format",
            "unregister_unpack_format", "unpack_archive",
@@ -74,8 +74,7 @@ class SpecialFileError(OSError):
     """Raised when trying to do a kind of operation (e.g. copying) which is
     not supported on a special file (e.g. a named pipe)"""
 
-class ExecError(OSError):
-    """Raised when a command could not be executed"""
+_ExecError = RuntimeError
 
 class ReadError(OSError):
     """Raised when an archive cannot be read"""
@@ -1582,3 +1581,14 @@ def which(cmd, mode=os.F_OK | os.X_OK, path=None):
                 if _access_check(name, mode):
                     return name
     return None
+
+def __getattr__(name):
+    if name == "ExecError":
+        import warnings
+        warnings._deprecated(
+            "shutil.ExecError",
+            f"{warnings._DEPRECATED_MSG}; use RuntimeError instead",
+            remove=(3, 16)
+        )
+        return _ExecError
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

Lib/test/test_shutil.py

@@ -3393,7 +3393,7 @@ def test_module_all_attribute(self):
         self.assertTrue(hasattr(shutil, '__all__'))
         target_api = ['copyfileobj', 'copyfile', 'copymode', 'copystat',
                       'copy', 'copy2', 'copytree', 'move', 'rmtree', 'Error',
-                      'SpecialFileError', 'ExecError', 'make_archive',
+                      'SpecialFileError', 'make_archive',
                       'get_archive_formats', 'register_archive_format',
                       'unregister_archive_format', 'get_unpack_formats',
                       'register_unpack_format', 'unregister_unpack_format',
@@ -3402,6 +3402,8 @@ def test_module_all_attribute(self):
         if hasattr(os, 'statvfs') or os.name == 'nt':
             target_api.append('disk_usage')
         self.assertEqual(set(shutil.__all__), set(target_api))
+        with self.assertWarns(DeprecationWarning):
+            from shutil import ExecError
 
 
 if __name__ == '__main__':

Misc/NEWS.d/next/Library/2024-08-18-08-25-32.gh-issue-123084.rf8izX.rst

@@ -0,0 +1,2 @@
+:class:`!shutil.ExecError` is now a deprecated alias of
+:class:`RuntimeError`.