bpo-43848: explain optional argument mtime in gzip.py. (GH-25410)

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: jwuttke

Doc/library/gzip.rst

@@ -100,10 +100,12 @@ The module defines the following items:
    compression, and ``9`` is slowest and produces the most compression. ``0``
    is no compression. The default is ``9``.
 
-   The *mtime* argument is an optional numeric timestamp to be written to
-   the last modification time field in the stream when compressing.  It
-   should only be provided in compression mode.  If omitted or ``None``, the
-   current time is used.  See the :attr:`mtime` attribute for more details.
+   The optional *mtime* argument is the timestamp requested by gzip. The time
+   is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.
+   If *mtime* is omitted or None, the current time is used. Use *mtime* = 0
+   to generate a compressed stream that does not depend on creation time.
+
+   See below for the :attr:`mtime` attribute that is set when decompressing.
 
    Calling a :class:`GzipFile` object's :meth:`!close` method does not close
    *fileobj*, since you might wish to append more material after the compressed
@@ -133,15 +135,10 @@ The module defines the following items:
 
    .. attribute:: mtime
 
-      When decompressing, the value of the last modification time field in
-      the most recently read header may be read from this attribute, as an
-      integer.  The initial value before reading any headers is ``None``.
-
-      All :program:`gzip` compressed streams are required to contain this
-      timestamp field.  Some programs, such as :program:`gunzip`\ , make use
-      of the timestamp.  The format is the same as the return value of
-      :func:`time.time` and the :attr:`~os.stat_result.st_mtime` attribute of
-      the object returned by :func:`os.stat`.
+      When decompressing, this attribute is set to the last timestamp in the most
+      recently read header.  It is an integer, holding the number of seconds
+      since the Unix epoch (00:00:00 UTC, January 1, 1970).
+      The initial value before reading any headers is ``None``.
 
    .. attribute:: name
 

Lib/gzip.py

@@ -178,9 +178,10 @@ def __init__(self, filename=None, mode=None,
         and 9 is slowest and produces the most compression. 0 is no compression
         at all. The default is 9.
 
-        The mtime argument is an optional numeric timestamp to be written
-        to the last modification time field in the stream when compressing.
-        If omitted or None, the current time is used.
+        The optional mtime argument is the timestamp requested by gzip. The time
+        is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.
+        If mtime is omitted or None, the current time is used. Use mtime = 0
+        to generate a compressed stream that does not depend on creation time.
 
         """
 

Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst

@@ -0,0 +1,3 @@
+In documentation of :class:`gzip.GzipFile` in module gzip, explain data type
+of optional constructor argument *mtime*, and recommend ``mtime = 0`` for
+generating deterministic streams.