Closes #18430: Document that peek() may change the position of the underlying

file for the BZ2File, GzipFile and LZMAFile classes.

3 files changed, 15 insertions, 0 deletions

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index 9027a35..488cda5 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -95,6 +95,11 @@ All of the classes in this module may safely be accessed from multiple threads.
       byte of data will be returned (unless at EOF). The exact number of bytes
       returned is unspecified.
 
+      .. note:: While calling :meth:`peek` does not change the file position of
+         the :class:`BZ2File`, it may change the position of the underlying file
+         object (e.g. if the :class:`BZ2File` was constructed by passing a file
+         object for *filename*).
+
       .. versionadded:: 3.3
 
    .. versionchanged:: 3.1
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index de5063a..78536fa 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -117,6 +117,11 @@ The module defines the following items:
       the call.  The number of bytes returned may be more or less than
       requested.
 
+      .. note:: While calling :meth:`peek` does not change the file position of
+         the :class:`GzipFile`, it may change the position of the underlying
+         file object (e.g. if the :class:`GzipFile` was constructed with the
+         *fileobj* parameter).
+
       .. versionadded:: 3.2
 
    .. versionchanged:: 3.1
diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst
index 53fba89..b71051d 100644
--- a/Doc/library/lzma.rst
+++ b/Doc/library/lzma.rst
@@ -102,6 +102,11 @@ Reading and writing compressed files
       byte of data will be returned, unless EOF has been reached. The exact
       number of bytes returned is unspecified (the *size* argument is ignored).
 
+      .. note:: While calling :meth:`peek` does not change the file position of
+         the :class:`LZMAFile`, it may change the position of the underlying
+         file object (e.g. if the :class:`LZMAFile` was constructed by passing a
+         file object for *filename*).
+
    .. versionchanged:: 3.4
       Added support for the ``"x"`` and ``"xb"`` modes.