Skip to content

Commit 241f2e5

Browse files
authored
[3.11] gh-102950: Implement PEP 706 – Filter for tarfile.extractall (GH-102953) (GH-103832)
See [Backporting & Forward Compatibility in PEP 706](https://peps.python.org/pep-0706/#backporting-forward-compatibility). - Backport b52ad18 - Backport c8c3956 - Remove the DeprecationWarning - Adjust docs - Remove new `__all__` entries
1 parent b3faf8c commit 241f2e5

File tree

8 files changed

+1800
-97
lines changed

8 files changed

+1800
-97
lines changed

Doc/library/shutil.rst

+21-6
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
626626
Remove the archive format *name* from the list of supported formats.
627627

628628

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

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

@@ -640,6 +640,15 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
640640
registered for that extension. In case none is found,
641641
a :exc:`ValueError` is raised.
642642

643+
The keyword-only *filter* argument, which was added in Python 3.11.4,
644+
is passed to the underlying unpacking function.
645+
For zip files, *filter* is not accepted.
646+
For tar files, it is recommended to set it to ``'data'``,
647+
unless using features specific to tar and UNIX-like filesystems.
648+
(See :ref:`tarfile-extraction-filter` for details.)
649+
The ``'data'`` filter will become the default for tar files
650+
in Python 3.14.
651+
643652
.. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
644653

645654
.. warning::
@@ -652,18 +661,24 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
652661
.. versionchanged:: 3.7
653662
Accepts a :term:`path-like object` for *filename* and *extract_dir*.
654663

664+
.. versionchanged:: 3.11.4
665+
Added the *filter* argument.
666+
655667
.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
656668

657669
Registers an unpack format. *name* is the name of the format and
658670
*extensions* is a list of extensions corresponding to the format, like
659671
``.zip`` for Zip files.
660672

661673
*function* is the callable that will be used to unpack archives. The
662-
callable will receive the path of the archive, followed by the directory
663-
the archive must be extracted to.
664-
665-
When provided, *extra_args* is a sequence of ``(name, value)`` tuples that
666-
will be passed as keywords arguments to the callable.
674+
callable will receive:
675+
676+
- the path of the archive, as a positional argument;
677+
- the directory the archive must be extracted to, as a positional argument;
678+
- possibly a *filter* keyword argument, if it was given to
679+
:func:`unpack_archive`;
680+
- additional keyword arguments, specified by *extra_args* as a sequence
681+
of ``(name, value)`` tuples.
667682

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

0 commit comments

Comments
 (0)