@@ -36,13 +36,6 @@ Some facts and figures:
36
36
.. versionchanged :: 3.3
37
37
Added support for :mod: `lzma ` compression.
38
38
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
-
46
39
47
40
.. function :: open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)
48
41
@@ -431,8 +424,8 @@ be finalized; only the internally used file object will be closed. See the
431
424
are used to set the owner/group for the extracted files. Otherwise, the named
432
425
values from the tarfile are used.
433
426
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.
436
429
See :ref: `tarfile-extraction-filter ` for details.
437
430
It is recommended to set this explicitly depending on which *tar * features
438
431
you need to support.
@@ -453,7 +446,7 @@ be finalized; only the internally used file object will be closed. See the
453
446
.. versionchanged :: 3.6
454
447
The *path * parameter accepts a :term: `path-like object `.
455
448
456
- .. versionchanged :: 3.12
449
+ .. versionchanged :: 3.8.17
457
450
Added the *filter * parameter.
458
451
459
452
@@ -489,7 +482,7 @@ be finalized; only the internally used file object will be closed. See the
489
482
.. versionchanged :: 3.6
490
483
The *path * parameter accepts a :term: `path-like object `.
491
484
492
- .. versionchanged :: 3.12
485
+ .. versionchanged :: 3.8.17
493
486
Added the *filter * parameter.
494
487
495
488
@@ -526,7 +519,7 @@ be finalized; only the internally used file object will be closed. See the
526
519
527
520
.. attribute :: TarFile.extraction_filter
528
521
529
- .. versionadded :: 3.12
522
+ .. versionadded :: 3.8.17
530
523
531
524
The :ref: `extraction filter <tarfile-extraction-filter >` used
532
525
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
537
530
argument to :meth: `~TarFile.extract `.
538
531
539
532
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 ``.
544
539
545
540
In Python 3.14+, leaving ``extraction_filter=None `` will cause
546
541
extraction methods to use the :func: `data <data_filter> ` filter by default.
@@ -645,6 +640,11 @@ Different :class:`TarInfo` methods handle ``None`` differently:
645
640
- :meth: `~TarFile.addfile ` will fail.
646
641
- :meth: `~TarFile.list ` will print a placeholder string.
647
642
643
+
644
+ .. versionchanged :: 3.8.17
645
+ Added :meth: `~TarInfo.replace ` and handling of ``None ``.
646
+
647
+
648
648
.. class :: TarInfo(name="")
649
649
650
650
Create a :class: `TarInfo ` object.
@@ -693,7 +693,7 @@ A ``TarInfo`` object has the following public data attributes:
693
693
Time of last modification in seconds since the :ref: `epoch <epoch >`,
694
694
as in :attr: `os.stat_result.st_mtime `.
695
695
696
- .. versionchanged :: 3.12
696
+ .. versionchanged :: 3.8.17
697
697
698
698
Can be set to ``None `` for :meth: `~TarFile.extract ` and
699
699
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -704,7 +704,7 @@ A ``TarInfo`` object has the following public data attributes:
704
704
705
705
Permission bits, as for :func: `os.chmod `.
706
706
707
- .. versionchanged :: 3.12
707
+ .. versionchanged :: 3.8.17
708
708
709
709
Can be set to ``None `` for :meth: `~TarFile.extract ` and
710
710
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -731,7 +731,7 @@ A ``TarInfo`` object has the following public data attributes:
731
731
732
732
User ID of the user who originally stored this member.
733
733
734
- .. versionchanged :: 3.12
734
+ .. versionchanged :: 3.8.17
735
735
736
736
Can be set to ``None `` for :meth: `~TarFile.extract ` and
737
737
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -742,7 +742,7 @@ A ``TarInfo`` object has the following public data attributes:
742
742
743
743
Group ID of the user who originally stored this member.
744
744
745
- .. versionchanged :: 3.12
745
+ .. versionchanged :: 3.8.17
746
746
747
747
Can be set to ``None `` for :meth: `~TarFile.extract ` and
748
748
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -753,7 +753,7 @@ A ``TarInfo`` object has the following public data attributes:
753
753
754
754
User name.
755
755
756
- .. versionchanged :: 3.12
756
+ .. versionchanged :: 3.8.17
757
757
758
758
Can be set to ``None `` for :meth: `~TarFile.extract ` and
759
759
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -764,7 +764,7 @@ A ``TarInfo`` object has the following public data attributes:
764
764
765
765
Group name.
766
766
767
- .. versionchanged :: 3.12
767
+ .. versionchanged :: 3.8.17
768
768
769
769
Can be set to ``None `` for :meth: `~TarFile.extract ` and
770
770
:meth: `~TarFile.extractall `, causing extraction to skip applying this
@@ -779,7 +779,7 @@ A ``TarInfo`` object has the following public data attributes:
779
779
uid=..., gid=..., uname=..., gname=...,
780
780
deep=True)
781
781
782
- .. versionadded :: 3.12
782
+ .. versionadded :: 3.8.17
783
783
784
784
Return a *new * copy of the :class: `!TarInfo ` object with the given attributes
785
785
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:
844
844
Extraction filters
845
845
------------------
846
846
847
- .. versionadded :: 3.12
847
+ .. versionadded :: 3.8.17
848
848
849
849
The *tar * format is designed to capture all details of a UNIX-like filesystem,
850
850
which makes it very powerful.
@@ -881,9 +881,10 @@ can be:
881
881
882
882
* ``None `` (default): Use :attr: `TarFile.extraction_filter `.
883
883
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 ``.
887
888
888
889
In Python 3.14, the ``'data' `` filter will become the default instead.
889
890
It's possible to switch earlier; see :attr: `TarFile.extraction_filter `.
@@ -1020,7 +1021,7 @@ Also note that:
1020
1021
Supporting older Python versions
1021
1022
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1022
1023
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
1024
1025
versions as security updates.
1025
1026
To check whether the feature is available, use e.g.
1026
1027
``hasattr(tarfile, 'data_filter') `` rather than checking the Python version.
@@ -1167,6 +1168,8 @@ Command-line options
1167
1168
Only string names are accepted (that is, ``fully_trusted ``, ``tar ``,
1168
1169
and ``data ``).
1169
1170
1171
+ .. versionadded :: 3.8.17
1172
+
1170
1173
.. _tar-examples :
1171
1174
1172
1175
Examples
@@ -1176,7 +1179,7 @@ How to extract an entire tar archive to the current working directory::
1176
1179
1177
1180
import tarfile
1178
1181
tar = tarfile.open("sample.tar.gz")
1179
- tar.extractall(filter='data' )
1182
+ tar.extractall()
1180
1183
tar.close()
1181
1184
1182
1185
How to extract a subset of a tar archive with :meth: `TarFile.extractall ` using
0 commit comments