gh-84027: Add whl as an unpack format in shutil (#140385)

Co-authored-by: Emma Smith <emma@emmatyping.dev>
Co-authored-by: Stan Ulbrych <stan@python.org>

Author: emmatyping

Doc/library/shutil.rst

@@ -753,7 +753,7 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
    unpacked. If not provided, the current working directory is used.
 
    *format* is the archive format: one of "zip", "tar", "gztar", "bztar",
-   "xztar", or "zstdtar".  Or any other format registered with
+   "xztar", "zstdtar", or "whl".  Or any other format registered with
    :func:`register_unpack_format`.  If not provided, :func:`unpack_archive`
    will use the archive file name extension and see if an unpacker was
    registered for that extension.  In case none is found,
@@ -786,6 +786,9 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
    .. versionchanged:: 3.12
       Added the *filter* argument.
 
+   .. versionchanged:: next
+      Added the "whl" format.
+
 .. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
 
    Registers an unpack format. *name* is the name of the format and
@@ -827,10 +830,16 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
    - *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available).
    - *zstdtar*: Zstandard compressed tar-file (if the :mod:`compression.zstd`
      module is available).
+   - *whl*: `wheel file <https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-wheel>`__
+     (unpacking compressed files works only if the corresponding module is
+     available).
 
    You can register new formats or provide your own unpacker for any existing
    formats, by using :func:`register_unpack_format`.
 
+   .. versionchanged:: next
+      Added the *whl* format.
+
 
 .. _shutil-archiving-example:
 

Doc/whatsnew/3.16.rst

@@ -681,6 +681,9 @@ shutil
   :func:`shutil.copystat`, e.g. when copying a read-only tree.
   (Contributed by Łukasz Langa in :gh:`89721`.)
 
+* :func:`shutil.unpack_archive` can now unpack wheel files using the ``whl`` format.
+  (Contributed by Emma Harper Smith and Stan Ulbrych in :gh:`84027`.)
+
 
 socket
 ------

Lib/shutil.py

@@ -1376,6 +1376,7 @@ def _unpack_tarfile(filename, extract_dir, *, filter=None):
 _UNPACK_FORMATS = {
     'tar':   (['.tar'], _unpack_tarfile, [], "uncompressed tar file"),
     'zip':   (['.zip'], _unpack_zipfile, [], "ZIP file"),
+    'whl':   (['.whl'], _unpack_zipfile, [], "Wheel file"),
 }
 
 if _ZLIB_SUPPORTED:
@@ -1410,9 +1411,9 @@ def unpack_archive(filename, extract_dir=None, format=None, *, filter=None):
     is unpacked. If not provided, the current working directory is used.
 
     `format` is the archive format: one of "zip", "tar", "gztar", "bztar",
-    "xztar", or "zstdtar".  Or any other registered format.  If not provided,
-    unpack_archive will use the filename extension and see if an unpacker
-    was registered for that extension.
+    "xztar", "zstdtar", or "whl".  Or any other registered format.  If not
+    provided, unpack_archive will use the filename extension and see if an
+    unpacker was registered for that extension.
 
     In case none is found, a ValueError is raised.
 

Lib/test/test_shutil.py

@@ -2287,12 +2287,18 @@ def check_unpack_archive(self, format, **kwargs):
         self.check_unpack_archive_with_converter(format, FakePath, **kwargs)
 
     def check_unpack_archive_with_converter(self, format, converter, **kwargs):
+        make_format = kwargs.pop("make_format", format)
+        extension = kwargs.pop("extension", None)
         root_dir, base_dir = self._create_files()
         expected = rlistdir(root_dir)
         expected.remove('outer')
 
         base_name = os.path.join(self.mkdtemp(), 'archive')
-        filename = make_archive(base_name, format, root_dir, base_dir)
+        filename = make_archive(base_name, make_format, root_dir, base_dir)
+        if extension is not None:
+            new_filename = os.path.splitext(filename)[0] + extension
+            os.rename(filename, new_filename)
+            filename = new_filename
 
         # let's try to unpack it now
         tmpdir2 = self.mkdtemp()
@@ -2340,6 +2346,13 @@ def test_unpack_archive_zip(self):
         with self.assertRaises(TypeError):
             self.check_unpack_archive('zip', filter='data')
 
+    @support.requires_zlib()
+    def test_unpack_archive_whl(self):
+        self.check_unpack_archive('whl', make_format='zip', extension='.whl')
+        with self.assertRaises(TypeError):
+            self.check_unpack_archive('whl', filter='data', make_format='zip',
+                                      extension='.whl')
+
     def test_unpack_archive_zip_badpaths(self):
         srcdir = self.mkdtemp()
         zipname = os.path.join(srcdir, 'test.zip')

Misc/NEWS.d/next/Library/2025-10-20-13-08-04.gh-issue-84027.HjBO0B.rst

@@ -0,0 +1 @@
+:mod:`shutil` now can unpack wheel packages using the ``whl`` format.