@@ -614,7 +614,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
614614 Remove the archive format *name * from the list of supported formats.
615615
616616
617- ..function ::unpack_archive(filename[, extract_dir[, format]])
617+ ..function ::unpack_archive(filename[, extract_dir[, format[, filter] ]])
618618
619619 Unpack an archive. *filename * is the full path of the archive.
620620
@@ -628,6 +628,15 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
628628 registered for that extension. In case none is found,
629629 a:exc: `ValueError ` is raised.
630630
631+ The keyword-only *filter * argument, which was added in Python 3.9.17,
632+ is passed to the underlying unpacking function.
633+ For zip files, *filter * is not accepted.
634+ For tar files, it is recommended to set it to ``'data' ``,
635+ unless using features specific to tar and UNIX-like filesystems.
636+ (See:ref: `tarfile-extraction-filter ` for details.)
637+ The ``'data' `` filter will become the default for tar files
638+ in Python 3.14.
639+
631640 ..audit-event ::shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
632641
633642 ..warning ::
@@ -640,18 +649,24 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
640649 ..versionchanged ::3.7
641650 Accepts a:term: `path-like object ` for *filename * and *extract_dir *.
642651
652+ ..versionchanged ::3.9.17
653+ Added the *filter * argument.
654+
643655..function ::register_unpack_format(name, extensions, function[, extra_args[, description]])
644656
645657 Registers an unpack format. *name * is the name of the format and
646658 *extensions * is a list of extensions corresponding to the format, like
647659 ``.zip `` for Zip files.
648660
649661 *function * is the callable that will be used to unpack archives. The
650- callable will receive the path of the archive, followed by the directory
651- the archive must be extracted to.
652-
653- When provided, *extra_args * is a sequence of ``(name, value) `` tuples that
654- will be passed as keywords arguments to the callable.
662+ callable will receive:
663+
664+ - the path of the archive, as a positional argument;
665+ - the directory the archive must be extracted to, as a positional argument;
666+ - possibly a *filter * keyword argument, if it was given to
667+ :func: `unpack_archive `;
668+ - additional keyword arguments, specified by *extra_args * as a sequence
669+ of ``(name, value) `` tuples.
655670
656671 *description * can be provided to describe the format, and will be returned
657672 by the:func: `get_unpack_formats ` function.