https://github.com/python/cpython/commit/72410a3ecf9fde8362dccf9726fea2b6412... commit: 72410a3ecf9fde8362dccf9726fea2b641237bfa branch: 3.12 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: serhiy-storchaka <storchaka@gmail.com> date: 2023-12-27T17:32:10Z summary: [3.12] gh-67641: Clarify documentation on bytes vs text with non-seeking tarfile stream (GH-31610) (GH-113519) (cherry picked from commit 0651936ae2bc6999f488f8c519b8d07a06a11557) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> files: M Doc/library/tarfile.rst M Lib/tarfile.py diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 7078fc04bfd0ee..6e34158084eb5c 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -116,10 +116,12 @@ Some facts and figures: ``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile` object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, *fileobj* may be any object that has a - :meth:`~io.TextIOBase.read` or :meth:`~io.TextIOBase.write` method (depending on the *mode*). *bufsize* - specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant - in combination with e.g. ``sys.stdin``, a socket :term:`file object` or a tape - device. However, such a :class:`TarFile` object is limited in that it does + :meth:`~io.RawIOBase.read` or :meth:`~io.RawIOBase.write` method + (depending on the *mode*) that works with bytes. + *bufsize* specifies the blocksize and defaults to ``20 * 512`` bytes. + Use this variant in combination with e.g. ``sys.stdin.buffer``, a socket + :term:`file object` or a tape device. + However, such a :class:`TarFile` object is limited in that it does not allow random access, see :ref:`tar-examples`. The currently possible modes: diff --git a/Lib/tarfile.py b/Lib/tarfile.py index 02f5e3b66c0766..027a19b9ed5994 100755 --- a/Lib/tarfile.py +++ b/Lib/tarfile.py @@ -331,10 +331,11 @@ def write(self, s): class _Stream: """Class that serves as an adapter between TarFile and a stream-like object. The stream-like object only - needs to have a read() or write() method and is accessed - blockwise. Use of gzip or bzip2 compression is possible. - A stream-like object could be for example: sys.stdin, - sys.stdout, a socket, a tape device etc. + needs to have a read() or write() method that works with bytes, + and the method is accessed blockwise. + Use of gzip or bzip2 compression is possible. + A stream-like object could be for example: sys.stdin.buffer, + sys.stdout.buffer, a socket, a tape device etc. _Stream is intended to be used only internally. """