https://github.com/python/cpython/commit/cfea838851a3d4c78bd099202e1fb818057a7a04
commit: cfea838851a3d4c78bd099202e1fb818057a7a04
branch: main
author: David Eisert <[email protected]>
committer: ethanfurman <[email protected]>
date: 2026-10-12T10:12:23-07:00
summary:
gh-62944: Add performance note for out-of-order extraction from compressed
archives (GH-151115)
Extracting members in a different order than they appear in a compressed
tarfile requires re-decompressing from the beginning of the stream for each
backward seek. Add a note to tarfile.open() documenting this and recommending
in-order extraction or use of TarFile.extractall() for best performance.
files:
M Doc/library/tarfile.rst
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index 0d8ce6e497915f..f8a40bc94a3fef 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -123,6 +123,17 @@ Some facts and figures:
:exc:`ReadError` is raised. Use *mode* ``'r'`` to avoid this. If a
compression method is not supported, :exc:`CompressionError` is raised.
+ .. note::
+
+ Compressed archives opened with modes like ``'r:gz'``, ``'r:bz2'``,
+ ``'r:xz'``, or ``'r:zst'`` support random access, but seeking backwards
+ in the underlying compressed stream requires re-decompressing from the
+ beginning. Extracting members in a different order than they appear in
+ the archive can therefore be significantly slower — proportional to the
+ total compressed data read rather than just the target member's size.
For
+ best performance, extract members in archive order or use
+ :meth:`TarFile.extractall`.
+
If *fileobj* is specified, it is used as an alternative to a :term:`file
object`
opened in binary mode for *name*. It is supposed to be at position 0.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
