https://github.com/python/cpython/commit/9a388b9a64927c372d85f0eaec3de9b7320a6fb5
commit: 9a388b9a64927c372d85f0eaec3de9b7320a6fb5
branch: main
author: Joachim Wuttke <j.wuttke@fz-juelich.de>
committer: encukou <encukou@gmail.com>
date: 2024-03-28T13:43:07Z
summary:
bpo-43848: explain optional argument mtime in gzip.py. (GH-25410)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
files:
A Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst
M Doc/library/gzip.rst
M Lib/gzip.py
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 79be215a766045..044be8c1c1bf41 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 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
diff --git a/Lib/gzip.py b/Lib/gzip.py
index fda93e0261e028..1d6faaa82c6a68 100644
--- a/Lib/gzip.py
+++ b/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.
"""
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.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-leave@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: list-python-checkins@lists.gossamer-threads.com
commit: 9a388b9a64927c372d85f0eaec3de9b7320a6fb5
branch: main
author: Joachim Wuttke <j.wuttke@fz-juelich.de>
committer: encukou <encukou@gmail.com>
date: 2024-03-28T13:43:07Z
summary:
bpo-43848: explain optional argument mtime in gzip.py. (GH-25410)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
files:
A Misc/NEWS.d/next/Library/2024-03-28-13-54-20.gh-issue-88014.zJz31I.rst
M Doc/library/gzip.rst
M Lib/gzip.py
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 79be215a766045..044be8c1c1bf41 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 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
diff --git a/Lib/gzip.py b/Lib/gzip.py
index fda93e0261e028..1d6faaa82c6a68 100644
--- a/Lib/gzip.py
+++ b/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.
"""
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.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-leave@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: list-python-checkins@lists.gossamer-threads.com