Adjust the docs for 3.9.17

Doc/library/shutil.rst

@@ -654,8 +654,9 @@ 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 is passed to the underlying unpacking
-   function. For zip files, *filter* is not accepted.
+   The keyword-only *filter* argument, which was added in Python 3.8.17,
+   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.)

Doc/library/tarfile.rst

@@ -36,13 +36,6 @@ Some facts and figures:
 .. versionchanged:: 3.3
    Added support for :mod:`lzma` compression.
 
-.. versionchanged:: 3.12
-   Archives are extracted using a :ref:`filter <tarfile-extraction-filter>`,
-   which makes it possible to either limit surprising/dangerous features,
-   or to acknowledge that they are expected and the archive is fully trusted.
-   By default, archives are fully trusted, but this default is deprecated
-   and slated to change in Python 3.14.
-
 
 .. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)
 
@@ -431,8 +424,8 @@ be finalized; only the internally used file object will be closed. See the
    are used to set the owner/group for the extracted files. Otherwise, the named
    values from the tarfile are used.
 
-   The *filter* argument specifies how ``members`` are modified or rejected
-   before extraction.
+   The *filter* argument, which was added in Python 3.8.17, specifies how
+   ``members`` are modified or rejected before extraction.
    See :ref:`tarfile-extraction-filter` for details.
    It is recommended to set this explicitly depending on which *tar* features
    you need to support.
@@ -453,7 +446,7 @@ be finalized; only the internally used file object will be closed. See the
    .. versionchanged:: 3.6
       The *path* parameter accepts a :term:`path-like object`.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
       Added the *filter* parameter.
 
 
@@ -489,7 +482,7 @@ be finalized; only the internally used file object will be closed. See the
    .. versionchanged:: 3.6
       The *path* parameter accepts a :term:`path-like object`.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
       Added the *filter* parameter.
 
 
@@ -526,7 +519,7 @@ be finalized; only the internally used file object will be closed. See the
 
 .. attribute:: TarFile.extraction_filter
 
-   .. versionadded:: 3.12
+   .. versionadded:: 3.8.17
 
    The :ref:`extraction filter <tarfile-extraction-filter>` used
    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
    argument to :meth:`~TarFile.extract`.
 
    If ``extraction_filter`` is ``None`` (the default),
-   calling an extraction method without a *filter* argument will raise a
-   ``DeprecationWarning``,
-   and fall back to the :func:`fully_trusted <fully_trusted_filter>` filter,
-   whose dangerous behavior matches previous versions of Python.
+   calling an extraction method without a *filter* argument will
+   use the :func:`fully_trusted <fully_trusted_filter>` filter for
+   compatibility with previous Python versions.
+
+   In Python 3.12+, leaving ``extraction_filter=None`` will emit a
+   ``DeprecationWarning``.
 
    In Python 3.14+, leaving ``extraction_filter=None`` will cause
    extraction methods to use the :func:`data <data_filter>` filter by default.
@@ -645,6 +640,11 @@ Different :class:`TarInfo` methods handle ``None`` differently:
 - :meth:`~TarFile.addfile` will fail.
 - :meth:`~TarFile.list` will print a placeholder string.
 
+
+.. versionchanged:: 3.8.17
+   Added :meth:`~TarInfo.replace` and handling of ``None``.
+
+
 .. class:: TarInfo(name="")
 
    Create a :class:`TarInfo` object.
@@ -693,7 +693,7 @@ A ``TarInfo`` object has the following public data attributes:
    Time of last modification in seconds since the :ref:`epoch <epoch>`,
    as in :attr:`os.stat_result.st_mtime`.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -704,7 +704,7 @@ A ``TarInfo`` object has the following public data attributes:
 
    Permission bits, as for :func:`os.chmod`.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -731,7 +731,7 @@ A ``TarInfo`` object has the following public data attributes:
 
    User ID of the user who originally stored this member.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -742,7 +742,7 @@ A ``TarInfo`` object has the following public data attributes:
 
    Group ID of the user who originally stored this member.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -753,7 +753,7 @@ A ``TarInfo`` object has the following public data attributes:
 
    User name.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -764,7 +764,7 @@ A ``TarInfo`` object has the following public data attributes:
 
    Group name.
 
-   .. versionchanged:: 3.12
+   .. versionchanged:: 3.8.17
 
       Can be set to ``None`` for :meth:`~TarFile.extract` and
       :meth:`~TarFile.extractall`, causing extraction to skip applying this
@@ -779,7 +779,7 @@ A ``TarInfo`` object has the following public data attributes:
                             uid=..., gid=..., uname=..., gname=...,
                             deep=True)
 
-   .. versionadded:: 3.12
+   .. versionadded:: 3.8.17
 
    Return a *new* copy of the :class:`!TarInfo` object with the given attributes
    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:
 Extraction filters
 ------------------
 
-.. versionadded:: 3.12
+.. versionadded:: 3.8.17
 
 The *tar* format is designed to capture all details of a UNIX-like filesystem,
 which makes it very powerful.
@@ -881,9 +881,10 @@ can be:
 
 * ``None`` (default): Use :attr:`TarFile.extraction_filter`.
 
-  If that is also ``None`` (the default), raise a ``DeprecationWarning``,
-  and fall back to the ``'fully_trusted'`` filter, whose dangerous behavior
-  matches previous versions of Python.
+  If that is also ``None`` (the default), the ``'fully_trusted'``
+  filter will be used (for compatibility with earlier versions of Python).
+
+  In Python 3.12, the default will emit a ``DeprecationWarning``.
 
   In Python 3.14, the ``'data'`` filter will become the default instead.
   It's possible to switch earlier; see :attr:`TarFile.extraction_filter`.
@@ -1020,7 +1021,7 @@ Also note that:
 Supporting older Python versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Extraction filters were added to Python 3.12, but may be backported to older
+Extraction filters were added to Python 3.12, and are backported to older
 versions as security updates.
 To check whether the feature is available, use e.g.
 ``hasattr(tarfile, 'data_filter')`` rather than checking the Python version.
@@ -1167,6 +1168,8 @@ Command-line options
    Only string names are accepted (that is, ``fully_trusted``, ``tar``,
    and ``data``).
 
+   .. versionadded:: 3.8.17
+
 .. _tar-examples:
 
 Examples
@@ -1176,7 +1179,7 @@ How to extract an entire tar archive to the current working directory::
 
    import tarfile
    tar = tarfile.open("sample.tar.gz")
-   tar.extractall(filter='data')
+   tar.extractall()
    tar.close()
 
 How to extract a subset of a tar archive with :meth:`TarFile.extractall` using

Doc/whatsnew/3.8.rst

@@ -2339,3 +2339,19 @@ This limit can be configured or disabled by environment variable, command
 line flag, or :mod:`sys` APIs. See the :ref:`integer string conversion
 length limitation <int_max_str_digits>` documentation.  The default limit
 is 4300 digits in string form.
+
+Notable Changes in 3.8.17
+=========================
+
+tarfile
+-------
+
+* The extraction methods in :mod:`tarfile`, and :func:`shutil.unpack_archive`,
+  have a new a *filter* argument that allows limiting tar features than may be
+  surprising or dangerous, such as creating files outside the destination
+  directory.
+  See :ref:`tarfile-extraction-filter` for details.
+  In Python 3.12, use without the *filter* argument will show a
+  :exc:`DeprecationWarning`.
+  In Python 3.14, the default will switch to ``'data'``.
+  (Contributed by Petr Viktorin in :pep:`706`.)