From 849e2750ff6628f989819215cef339c12fb1c2ed Mon Sep 17 00:00:00 2001 From: KentaroJay Date: Sat, 28 Jun 2025 20:28:09 +0200 Subject: [PATCH 1/4] Clarify ZipInfo.date_time attribute documentation to specify source of timestamp and limitations --- Doc/library/zipfile.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 6a4fa67332e179..951f16cd634099 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -818,7 +818,18 @@ Instances have the following methods and attributes: .. attribute:: ZipInfo.date_time The time and date of the last modification to the archive member. This is a - tuple of six values: + tuple of six values representing the "last mod file time" and "last mod file date" + fields from the ZIP file's central directory. + + .. note:: + + The ZIP format supports multiple timestamp fields in different locations + (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute + specifically returns the timestamp from the central directory. Future Python + versions may use alternative timestamp sources if they provide better accuracy + or precision. + + The tuple contains: +-------+--------------------------+ | Index | Value | @@ -838,7 +849,10 @@ Instances have the following methods and attributes: .. note:: - The ZIP file format does not support timestamps before 1980. + The central directory timestamp format in ZIP files does not support + timestamps before 1980. While some extra field formats (such as UNIX + timestamps) can represent earlier dates, this attribute only returns + the central directory timestamp. .. attribute:: ZipInfo.compress_type From fcad6c532448036ee043b71c6e8852b107865c2f Mon Sep 17 00:00:00 2001 From: KentaroJay Date: Sat, 28 Jun 2025 20:37:47 +0200 Subject: [PATCH 2/4] Fix --- Doc/library/zipfile.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 951f16cd634099..757dabba2127d0 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -819,16 +819,16 @@ Instances have the following methods and attributes: The time and date of the last modification to the archive member. This is a tuple of six values representing the "last mod file time" and "last mod file date" - fields from the ZIP file's central directory. - + fields from the ZIP file's central directory. + .. note:: - + The ZIP format supports multiple timestamp fields in different locations (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute specifically returns the timestamp from the central directory. Future Python versions may use alternative timestamp sources if they provide better accuracy or precision. - + The tuple contains: +-------+--------------------------+ @@ -849,8 +849,8 @@ Instances have the following methods and attributes: .. note:: - The central directory timestamp format in ZIP files does not support - timestamps before 1980. While some extra field formats (such as UNIX + The central directory timestamp format in ZIP files does not support + timestamps before 1980. While some extra field formats (such as UNIX timestamps) can represent earlier dates, this attribute only returns the central directory timestamp. From aa6bb16f36e9a58a2d5083bc78f56c1a190bcfab Mon Sep 17 00:00:00 2001 From: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com> Date: Mon, 28 Jul 2025 17:12:56 +0900 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Emma Smith --- Doc/library/zipfile.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 757dabba2127d0..4adf533c03f505 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -818,16 +818,14 @@ Instances have the following methods and attributes: .. attribute:: ZipInfo.date_time The time and date of the last modification to the archive member. This is a - tuple of six values representing the "last mod file time" and "last mod file date" + tuple of six values representing the "last [modified] file time" and "last [modified] file date" fields from the ZIP file's central directory. .. note:: The ZIP format supports multiple timestamp fields in different locations (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute - specifically returns the timestamp from the central directory. Future Python - versions may use alternative timestamp sources if they provide better accuracy - or precision. + specifically returns the timestamp from the central directory. The tuple contains: From 5afd441892ea3d2b64f7c901da374cc2160c72c1 Mon Sep 17 00:00:00 2001 From: KentaroJay Date: Mon, 28 Jul 2025 17:37:07 +0900 Subject: [PATCH 4/4] Fixed spare notes into emrged note, also added explanation about local timezone --- Doc/library/zipfile.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 4adf533c03f505..6711bf0cb28763 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -821,12 +821,6 @@ Instances have the following methods and attributes: tuple of six values representing the "last [modified] file time" and "last [modified] file date" fields from the ZIP file's central directory. - .. note:: - - The ZIP format supports multiple timestamp fields in different locations - (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute - specifically returns the timestamp from the central directory. - The tuple contains: +-------+--------------------------+ @@ -847,10 +841,14 @@ Instances have the following methods and attributes: .. note:: - The central directory timestamp format in ZIP files does not support - timestamps before 1980. While some extra field formats (such as UNIX - timestamps) can represent earlier dates, this attribute only returns - the central directory timestamp. + The ZIP format supports multiple timestamp fields in different locations + (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute + specifically returns the timestamp from the central directory. The central + directory timestamp format in ZIP files does not support timestamps before + 1980. While some extra field formats (such as UNIX timestamps) can represent + earlier dates, this attribute only returns the central directory timestamp. + + CPython interprets this timestamp as representing local time, not UTC. .. attribute:: ZipInfo.compress_type