From 3e2c2f911fedd95a37a329d2e8e0f6c71548f978 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 25 Apr 2023 14:17:07 +0200 Subject: [PATCH] Adjust the docs for 3.9.17 --- Doc/library/shutil.rst | 5 ++-- Doc/library/tarfile.rst | 61 +++++++++++++++++++++-------------------- Doc/whatsnew/3.8.rst | 16 +++++++++++ 3 files changed, 51 insertions(+), 31 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index e591a3194b0cec..0325a6e2af8e8b 100644 --- a/Doc/library/shutil.rst +++ b/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.) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 23a20717ae4ab5..85d07ffd75fadf 100644 --- a/Doc/library/tarfile.rst +++ b/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 `, - 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 ` 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 ` filter, - whose dangerous behavior matches previous versions of Python. + calling an extraction method without a *filter* argument will + use the :func:`fully_trusted ` 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 ` 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 `, 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 diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 630e060cb07a73..e5278da3f6a5be 100644 --- a/Doc/whatsnew/3.8.rst +++ b/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 ` 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`.)