From 51fa9b60dd95c30d0031bd471e77ff5d2c583760 Mon Sep 17 00:00:00 2001 From: Joachim Wuttke Date: Wed, 14 Apr 2021 20:20:47 +0200 Subject: [PATCH 1/8] gzip.py: Explain mtime; recommend mtime = 0. Explain data type of mtime. Reommend mtime = 0 for deterministic compression. --- Lib/gzip.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Lib/gzip.py b/Lib/gzip.py index 5b20e5ba698ee9..c79b065e9e3d67 100644 --- a/Lib/gzip.py +++ b/Lib/gzip.py @@ -160,10 +160,11 @@ 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 GMT, Jan. 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. + """ if mode and ('t' in mode or 'U' in mode): From f8fe17334c998ae4b8a2026a672a28865d181584 Mon Sep 17 00:00:00 2001 From: Joachim Wuttke Date: Wed, 14 Apr 2021 20:51:37 +0200 Subject: [PATCH 2/8] Update gzip.py --- Lib/gzip.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/gzip.py b/Lib/gzip.py index c79b065e9e3d67..b1a7853ad8548b 100644 --- a/Lib/gzip.py +++ b/Lib/gzip.py @@ -164,7 +164,7 @@ def __init__(self, filename=None, mode=None, is in Unix format, i.e., seconds since 00:00:00 GMT, Jan. 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. - + """ if mode and ('t' in mode or 'U' in mode): From 75d7320c5a61cb78808e00b5e618a4746983354e Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Wed, 14 Apr 2021 19:24:40 +0000 Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst diff --git a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst new file mode 100644 index 00000000000000..69e83b88b1a655 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst @@ -0,0 +1 @@ +In documentation of :class:`GzipFile`, explain data type of optional constructor argument `mtime`, and recommend `mtime = 0` for generating deterministic streams. \ No newline at end of file From a992d88b9ff6c22ef0e2e54db98e592c91dc8691 Mon Sep 17 00:00:00 2001 From: Joachim Wuttke Date: Wed, 14 Apr 2021 21:43:27 +0200 Subject: [PATCH 4/8] Update 2021-04-14-19-24-39.bpo-43848.gjIRIY.rst --- .../next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst index 69e83b88b1a655..b8a1112d616490 100644 --- a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst +++ b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst @@ -1 +1 @@ -In documentation of :class:`GzipFile`, explain data type of optional constructor argument `mtime`, and recommend `mtime = 0` for generating deterministic streams. \ No newline at end of file +In documentation of class `GzipFile` in module gzip, explain data type of optional constructor argument `mtime`, and recommend `mtime = 0` for generating deterministic streams. From c43cb2a5194ada639e5dfc33fcc82e2dfb0097f6 Mon Sep 17 00:00:00 2001 From: Joachim Wuttke Date: Thu, 15 Apr 2021 09:10:17 +0200 Subject: [PATCH 5/8] Update 2021-04-14-19-24-39.bpo-43848.gjIRIY.rst ReST, not MarkDown --- .../next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst index b8a1112d616490..cefcd6bdece301 100644 --- a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst +++ b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst @@ -1 +1 @@ -In documentation of class `GzipFile` in module gzip, explain data type of optional constructor argument `mtime`, and recommend `mtime = 0` for generating deterministic streams. +In documentation of class ``GzipFile`` in module gzip, explain data type of optional constructor argument ``mtime``, and recommend ``mtime = 0`` for generating deterministic streams. From 025c03b6652121bebd58ce56fbb853a6fca81619 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Wed, 4 May 2022 09:56:54 +0200 Subject: [PATCH 6/8] In gzip.rst, extend explanation of argument mtime, and simplify description of attribute mtime --- Doc/library/gzip.rst | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst index 8cea2649ee6cb6..a1d0e99f8661dc 100644 --- a/Doc/library/gzip.rst +++ b/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 GMT, Jan. 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 last timestamp in the most + recently read header. It is an integer, holding the number of seconds + since the Unix epoch (00:00:00 GMT, Jan. 1, 1970). + The initial value before reading any headers is ``None``. .. versionchanged:: 3.1 Support for the :keyword:`with` statement was added, along with the @@ -275,4 +272,3 @@ Command line options .. cmdoption:: -h, --help Show the help message. - From 6d024a5401ae9887e00c447b6bb2f44fab3eb889 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 28 Mar 2024 14:10:03 +0100 Subject: [PATCH 7/8] Update & rewrite the NEWS entry --- .../Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst | 1 - .../next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst | 3 +++ 2 files changed, 3 insertions(+), 1 deletion(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst create mode 100644 Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst diff --git a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst b/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst deleted file mode 100644 index cefcd6bdece301..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2021-04-14-19-24-39.bpo-43848.gjIRIY.rst +++ /dev/null @@ -1 +0,0 @@ -In documentation of class ``GzipFile`` in module gzip, explain data type of optional constructor argument ``mtime``, and recommend ``mtime = 0`` for generating deterministic streams. diff --git a/Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst b/Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst new file mode 100644 index 00000000000000..f8bb784e39fbb6 --- /dev/null +++ b/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. From 61eed2d014d67d0ee9b92ceb5529e103bb91cd52 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 28 Mar 2024 14:11:36 +0100 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Jelle Zijlstra --- Doc/library/gzip.rst | 8 ++++---- Lib/gzip.py | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst index 20398bc2a8f338..044be8c1c1bf41 100644 --- a/Doc/library/gzip.rst +++ b/Doc/library/gzip.rst @@ -101,8 +101,8 @@ The module defines the following items: is no compression. The default is ``9``. The optional *mtime* argument is the timestamp requested by gzip. The time - is in Unix format, i.e., seconds since 00:00:00 GMT, Jan. 1, 1970. - If mtime is omitted or None, the current time is used. Use mtime = 0 + 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. @@ -135,9 +135,9 @@ The module defines the following items: .. attribute:: mtime - When decompressing, this attribute is set to last timestamp in the most + 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 GMT, Jan. 1, 1970). + since the Unix epoch (00:00:00 UTC, January 1, 1970). The initial value before reading any headers is ``None``. .. attribute:: name diff --git a/Lib/gzip.py b/Lib/gzip.py index 79604ce5cfeda7..1d6faaa82c6a68 100644 --- a/Lib/gzip.py +++ b/Lib/gzip.py @@ -179,7 +179,7 @@ def __init__(self, filename=None, mode=None, at all. The default is 9. The optional mtime argument is the timestamp requested by gzip. The time - is in Unix format, i.e., seconds since 00:00:00 GMT, Jan. 1, 1970. + 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.