gh-102950: Implement PEP 706 – Filter for tarfile.extractall (#102953) · python/cpython@b52ad18 (original) (raw)
`` @@ -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,14 @@ 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 is passed to the underlying unpacking
`
``
644
`+
function. For zip files, filter is not accepted.
`
``
645
For tar files, it is recommended to set it to ``'data'``,
``
646
`+
unless using features specific to tar and UNIX-like filesystems.
`
``
647
`` +
(See :ref:tarfile-extraction-filter for details.)
``
``
648
The ``'data'`` filter will become the default for tar files
``
649
`+
in Python 3.14.
`
``
650
+
643
651
` .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
`
644
652
``
645
653
` .. warning::
`
`` @@ -652,18 +660,24 @@ provided. They rely on the :mod:zipfile and :mod:tarfile modules.
``
652
660
` .. versionchanged:: 3.7
`
653
661
`` Accepts a :term:path-like object for filename and extract_dir.
``
654
662
``
``
663
`+
.. versionchanged:: 3.12
`
``
664
`+
Added the filter argument.
`
``
665
+
655
666
`.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
`
656
667
``
657
668
` Registers an unpack format. name is the name of the format and
`
658
669
` extensions is a list of extensions corresponding to the format, like
`
659
670
``` .zip for Zip files.
`660`
`671`
``
`661`
`672`
` *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.
`
``
673
`+
callable will receive:
`
``
674
+
``
675
`+
- the path of the archive, as a positional argument;
`
``
676
`+
- the directory the archive must be extracted to, as a positional argument;
`
``
677
`+
- possibly a filter keyword argument, if it was given to
`
``
678
`` +
:func:unpack_archive;
``
``
679
`+
- additional keyword arguments, specified by extra_args as a sequence
`
``
680
of ``(name, value)`` tuples.
667
681
``
668
682
` description can be provided to describe the format, and will be returned
`
669
683
`` by the :func:get_unpack_formats function.
``