Skip to content

Commit 3e2c2f9

Browse files
committed
Adjust the docs for 3.9.17
1 parent 4a17b3d commit 3e2c2f9

File tree

3 files changed

+51
-31
lines changed

3 files changed

+51
-31
lines changed

Doc/library/shutil.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -654,8 +654,9 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
654654
registered for that extension. In case none is found,
655655
a :exc:`ValueError` is raised.
656656

657-
The keyword-only *filter* argument is passed to the underlying unpacking
658-
function. For zip files, *filter* is not accepted.
657+
The keyword-only *filter* argument, which was added in Python 3.8.17,
658+
is passed to the underlying unpacking function.
659+
For zip files, *filter* is not accepted.
659660
For tar files, it is recommended to set it to ``'data'``,
660661
unless using features specific to tar and UNIX-like filesystems.
661662
(See :ref:`tarfile-extraction-filter` for details.)

Doc/library/tarfile.rst

Lines changed: 32 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,6 @@ Some facts and figures:
3636
.. versionchanged:: 3.3
3737
Added support for :mod:`lzma` compression.
3838

39-
.. versionchanged:: 3.12
40-
Archives are extracted using a :ref:`filter <tarfile-extraction-filter>`,
41-
which makes it possible to either limit surprising/dangerous features,
42-
or to acknowledge that they are expected and the archive is fully trusted.
43-
By default, archives are fully trusted, but this default is deprecated
44-
and slated to change in Python 3.14.
45-
4639

4740
.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)
4841

@@ -431,8 +424,8 @@ be finalized; only the internally used file object will be closed. See the
431424
are used to set the owner/group for the extracted files. Otherwise, the named
432425
values from the tarfile are used.
433426

434-
The *filter* argument specifies how ``members`` are modified or rejected
435-
before extraction.
427+
The *filter* argument, which was added in Python 3.8.17, specifies how
428+
``members`` are modified or rejected before extraction.
436429
See :ref:`tarfile-extraction-filter` for details.
437430
It is recommended to set this explicitly depending on which *tar* features
438431
you need to support.
@@ -453,7 +446,7 @@ be finalized; only the internally used file object will be closed. See the
453446
.. versionchanged:: 3.6
454447
The *path* parameter accepts a :term:`path-like object`.
455448

456-
.. versionchanged:: 3.12
449+
.. versionchanged:: 3.8.17
457450
Added the *filter* parameter.
458451

459452

@@ -489,7 +482,7 @@ be finalized; only the internally used file object will be closed. See the
489482
.. versionchanged:: 3.6
490483
The *path* parameter accepts a :term:`path-like object`.
491484

492-
.. versionchanged:: 3.12
485+
.. versionchanged:: 3.8.17
493486
Added the *filter* parameter.
494487

495488

@@ -526,7 +519,7 @@ be finalized; only the internally used file object will be closed. See the
526519

527520
.. attribute:: TarFile.extraction_filter
528521

529-
.. versionadded:: 3.12
522+
.. versionadded:: 3.8.17
530523

531524
The :ref:`extraction filter <tarfile-extraction-filter>` used
532525
as a default for the *filter* argument of :meth:`~TarFile.extract`
@@ -537,10 +530,12 @@ be finalized; only the internally used file object will be closed. See the
537530
argument to :meth:`~TarFile.extract`.
538531

539532
If ``extraction_filter`` is ``None`` (the default),
540-
calling an extraction method without a *filter* argument will raise a
541-
``DeprecationWarning``,
542-
and fall back to the :func:`fully_trusted <fully_trusted_filter>` filter,
543-
whose dangerous behavior matches previous versions of Python.
533+
calling an extraction method without a *filter* argument will
534+
use the :func:`fully_trusted <fully_trusted_filter>` filter for
535+
compatibility with previous Python versions.
536+
537+
In Python 3.12+, leaving ``extraction_filter=None`` will emit a
538+
``DeprecationWarning``.
544539

545540
In Python 3.14+, leaving ``extraction_filter=None`` will cause
546541
extraction methods to use the :func:`data <data_filter>` filter by default.
@@ -645,6 +640,11 @@ Different :class:`TarInfo` methods handle ``None`` differently:
645640
- :meth:`~TarFile.addfile` will fail.
646641
- :meth:`~TarFile.list` will print a placeholder string.
647642

643+
644+
.. versionchanged:: 3.8.17
645+
Added :meth:`~TarInfo.replace` and handling of ``None``.
646+
647+
648648
.. class:: TarInfo(name="")
649649

650650
Create a :class:`TarInfo` object.
@@ -693,7 +693,7 @@ A ``TarInfo`` object has the following public data attributes:
693693
Time of last modification in seconds since the :ref:`epoch <epoch>`,
694694
as in :attr:`os.stat_result.st_mtime`.
695695

696-
.. versionchanged:: 3.12
696+
.. versionchanged:: 3.8.17
697697

698698
Can be set to ``None`` for :meth:`~TarFile.extract` and
699699
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -704,7 +704,7 @@ A ``TarInfo`` object has the following public data attributes:
704704

705705
Permission bits, as for :func:`os.chmod`.
706706

707-
.. versionchanged:: 3.12
707+
.. versionchanged:: 3.8.17
708708

709709
Can be set to ``None`` for :meth:`~TarFile.extract` and
710710
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -731,7 +731,7 @@ A ``TarInfo`` object has the following public data attributes:
731731

732732
User ID of the user who originally stored this member.
733733

734-
.. versionchanged:: 3.12
734+
.. versionchanged:: 3.8.17
735735

736736
Can be set to ``None`` for :meth:`~TarFile.extract` and
737737
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -742,7 +742,7 @@ A ``TarInfo`` object has the following public data attributes:
742742

743743
Group ID of the user who originally stored this member.
744744

745-
.. versionchanged:: 3.12
745+
.. versionchanged:: 3.8.17
746746

747747
Can be set to ``None`` for :meth:`~TarFile.extract` and
748748
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -753,7 +753,7 @@ A ``TarInfo`` object has the following public data attributes:
753753

754754
User name.
755755

756-
.. versionchanged:: 3.12
756+
.. versionchanged:: 3.8.17
757757

758758
Can be set to ``None`` for :meth:`~TarFile.extract` and
759759
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -764,7 +764,7 @@ A ``TarInfo`` object has the following public data attributes:
764764

765765
Group name.
766766

767-
.. versionchanged:: 3.12
767+
.. versionchanged:: 3.8.17
768768

769769
Can be set to ``None`` for :meth:`~TarFile.extract` and
770770
:meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -779,7 +779,7 @@ A ``TarInfo`` object has the following public data attributes:
779779
uid=..., gid=..., uname=..., gname=...,
780780
deep=True)
781781

782-
.. versionadded:: 3.12
782+
.. versionadded:: 3.8.17
783783

784784
Return a *new* copy of the :class:`!TarInfo` object with the given attributes
785785
changed. For example, to return a ``TarInfo`` with the group name set to
@@ -844,7 +844,7 @@ A :class:`TarInfo` object also provides some convenient query methods:
844844
Extraction filters
845845
------------------
846846

847-
.. versionadded:: 3.12
847+
.. versionadded:: 3.8.17
848848

849849
The *tar* format is designed to capture all details of a UNIX-like filesystem,
850850
which makes it very powerful.
@@ -881,9 +881,10 @@ can be:
881881

882882
* ``None`` (default): Use :attr:`TarFile.extraction_filter`.
883883

884-
If that is also ``None`` (the default), raise a ``DeprecationWarning``,
885-
and fall back to the ``'fully_trusted'`` filter, whose dangerous behavior
886-
matches previous versions of Python.
884+
If that is also ``None`` (the default), the ``'fully_trusted'``
885+
filter will be used (for compatibility with earlier versions of Python).
886+
887+
In Python 3.12, the default will emit a ``DeprecationWarning``.
887888

888889
In Python 3.14, the ``'data'`` filter will become the default instead.
889890
It's possible to switch earlier; see :attr:`TarFile.extraction_filter`.
@@ -1020,7 +1021,7 @@ Also note that:
10201021
Supporting older Python versions
10211022
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10221023

1023-
Extraction filters were added to Python 3.12, but may be backported to older
1024+
Extraction filters were added to Python 3.12, and are backported to older
10241025
versions as security updates.
10251026
To check whether the feature is available, use e.g.
10261027
``hasattr(tarfile, 'data_filter')`` rather than checking the Python version.
@@ -1167,6 +1168,8 @@ Command-line options
11671168
Only string names are accepted (that is, ``fully_trusted``, ``tar``,
11681169
and ``data``).
11691170

1171+
.. versionadded:: 3.8.17
1172+
11701173
.. _tar-examples:
11711174

11721175
Examples
@@ -1176,7 +1179,7 @@ How to extract an entire tar archive to the current working directory::
11761179

11771180
import tarfile
11781181
tar = tarfile.open("sample.tar.gz")
1179-
tar.extractall(filter='data')
1182+
tar.extractall()
11801183
tar.close()
11811184

11821185
How to extract a subset of a tar archive with :meth:`TarFile.extractall` using

Doc/whatsnew/3.8.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2339,3 +2339,19 @@ This limit can be configured or disabled by environment variable, command
23392339
line flag, or :mod:`sys` APIs. See the :ref:`integer string conversion
23402340
length limitation <int_max_str_digits>` documentation. The default limit
23412341
is 4300 digits in string form.
2342+
2343+
Notable Changes in 3.8.17
2344+
=========================
2345+
2346+
tarfile
2347+
-------
2348+
2349+
* The extraction methods in :mod:`tarfile`, and :func:`shutil.unpack_archive`,
2350+
have a new a *filter* argument that allows limiting tar features than may be
2351+
surprising or dangerous, such as creating files outside the destination
2352+
directory.
2353+
See :ref:`tarfile-extraction-filter` for details.
2354+
In Python 3.12, use without the *filter* argument will show a
2355+
:exc:`DeprecationWarning`.
2356+
In Python 3.14, the default will switch to ``'data'``.
2357+
(Contributed by Petr Viktorin in :pep:`706`.)

0 commit comments

Comments
 (0)