Implement PEP 706 – Filter for tarfile.extractall

python · ambv · May 17, 2023 · Jan 31, 2023 · May 16, 2023 · Apr 25, 2023
commit f4556de8cf9f0d84d8a7e3a9d93690fabd072fe4
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
@@ -640,7 +640,7 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
   Remove the archive format *name* from the list of supported formats.


-.. function:: unpack_archive(filename[, extract_dir[, format]])
+.. function:: unpack_archive(filename[, extract_dir[, format[, filter]]])

   Unpack an archive. *filename* is the full path of the archive.

@@ -654,11 +654,21 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
   registered for that extension.  In case none is found,
   a :exc:`ValueError` is raised.

+   The keyword-only *filter* argument is passed to the underlying unpacking
+   function. For zip files, *filter* is not accepted.
+   For tar files, it is recommended to set it to ``'data'``,
+   unless using features specific to tar and UNIX-like filesystems.
+   (See :ref:`tarfile-extraction-filter` for details.)
+   The ``'data'`` filter will become the default for tar files
+   in Python 3.14.
+
   .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive

   .. versionchanged:: 3.7
      Accepts a :term:`path-like object` for *filename* and *extract_dir*.

+   .. versionchanged:: 3.8.17
+      Added the *filter* argument.

 .. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])

@@ -667,11 +677,14 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
   ``.zip`` for Zip files.

   *function* is the callable that will be used to unpack archives. The
-   callable will receive the path of the archive, followed by the directory
-   the archive must be extracted to.
-
-   When provided, *extra_args* is a sequence of ``(name, value)`` tuples that
-   will be passed as keywords arguments to the callable.
+   callable will receive:
+
+   - the path of the archive, as a positional argument;
+   - the directory the archive must be extracted to, as a positional argument;
+   - possibly a *filter* keyword argument, if it was given to
+     :func:`unpack_archive`;
+   - additional keyword arguments, specified by *extra_args* as a sequence
+     of ``(name, value)`` tuples.

   *description* can be provided to describe the format, and will be returned
   by the :func:`get_unpack_formats` function.