[3.10] gh-102950: Implement PEP 706 – Filter for tarfile.extractall (GH-102953) by mcepl · Pull Request #104128 · python/cpython
Expand Up
@@ -620,7 +620,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.
Expand All @@ -634,6 +634,15 @@ 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, which was added in Python 3.10.12, 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
.. warning:: Expand All @@ -646,18 +655,24 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. versionchanged:: 3.7 Accepts a :term:`path-like object` for *filename* and *extract_dir*.
.. versionchanged:: 3.10.12 Added the *filter* argument.
.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
Registers an unpack format. *name* is the name of the format and *extensions* is a list of extensions corresponding to the format, like ``.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. Expand Down
.. 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.
Expand All @@ -634,6 +634,15 @@ 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, which was added in Python 3.10.12, 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
.. warning:: Expand All @@ -646,18 +655,24 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. versionchanged:: 3.7 Accepts a :term:`path-like object` for *filename* and *extract_dir*.
.. versionchanged:: 3.10.12 Added the *filter* argument.
.. function:: register_unpack_format(name, extensions, function[, extra_args[, description]])
Registers an unpack format. *name* is the name of the format and *extensions* is a list of extensions corresponding to the format, like ``.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. Expand Down