@@ -626,7 +626,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
626
626
Remove the archive format *name * from the list of supported formats.
627
627
628
628
629
- .. function :: unpack_archive(filename[, extract_dir[, format]])
629
+ .. function :: unpack_archive(filename[, extract_dir[, format[, filter] ]])
630
630
631
631
Unpack an archive. *filename * is the full path of the archive.
632
632
@@ -640,6 +640,15 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
640
640
registered for that extension. In case none is found,
641
641
a :exc: `ValueError ` is raised.
642
642
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
+
643
652
.. audit-event :: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
644
653
645
654
.. warning ::
@@ -652,18 +661,24 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
652
661
.. versionchanged :: 3.7
653
662
Accepts a :term: `path-like object ` for *filename * and *extract_dir *.
654
663
664
+ .. versionchanged :: 3.11.4
665
+ Added the *filter * argument.
666
+
655
667
.. function :: register_unpack_format(name, extensions, function[, extra_args[, description]])
656
668
657
669
Registers an unpack format. *name * is the name of the format and
658
670
*extensions * is a list of extensions corresponding to the format, like
659
671
``.zip `` for Zip files.
660
672
661
673
*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.
667
682
668
683
*description * can be provided to describe the format, and will be returned
669
684
by the :func: `get_unpack_formats ` function.
0 commit comments