Allow gzip mtime to be a datetime object

[gchqdev227]

Feature or enhancement

Proposal:

Currently, the mtime optional parameter of the gzip.GzipFile class and gzip.compress function can be an float representing a Unix timestamp, or None to use the current time. I propose allowing this to also be a datetime.datetime object. All of these would then be possible:

from datetime import datetime, timezone
import gzip
import zoneinfo

compress(data)  # compress using current time
compress(data, mtime=0)  # ignore the time
compress(data, mtime=1736247159)  # specify the time with a Unix timestamp
compress(data, mtime=datetime(2025, 1, 7, tzinfo=timezone.utc))  # specify time with a datetime object
compress(data, mtime=datetime(2025, 1, 7, tzinfo=zoneinfo.ZoneInfo(key='US/Eastern')))  # specify a different timezone

This avoids users needing to cast their datetime objects into timestamps before calling compress or creating a GzipFile instance, which can lead to mistakes.

I have an initial PR for this ready to go.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-128584: Allow gzip mtime to be a datetime object #128589

[serhiy-storchaka]

This would create a dependency between gzip and datetime modules. This is not desirable.

It is not hard to call the timestamp() method before calling compress().

[gchqdev227]

Hi @serhiy-storchaka, thank you for your comments.

This would create a dependency between gzip and datetime modules. This is not desirable.

This is a fair point, although I would point out that datetime is already imported in a handful of stdlib modules/packages, such as calendar, http and tomllib (a more recent example). I agree that creating this link where it is not completely necessary might be a harder sell, although this issue is a precursor to a larger gzip issue we intend to open in the future, but are trying to keep the changes smaller.

It is not hard to call the timestamp() method before calling compress().

This is true, although I would use the same argument as with supporting pathlib.Path objects instead of expecting users to cast them to a string first (although admittedly os.PathLike exists which reduces direct imports of pathlib).