From ead4f3f15a1e8c23bfcf639f6b55a6a062bff4e3 Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Thu, 14 Aug 2025 20:26:54 +0800 Subject: [PATCH 1/4] gh-137758: Clarify os.stat_result time fields are seconds since the Unix epoch Clarify that `os.stat_result` time fields (`st_atime`, `st_mtime`, `st_ctime`, `st_birthtime`) and their `*_ns` variants are measured since the Unix epoch (00:00:00 UTC, 1970-01-01). Add a short note showing how to convert these timestamps to `datetime` using `datetime.datetime.fromtimestamp`, including a UTC example. Documentation-only; no behavior change. Files touched: Doc/library/os.rst Co-authored-by: tangyuan0821 --- Doc/library/os.rst | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 45ec6c7a51b7b0..9ab1264523fac0 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3177,15 +3177,18 @@ features: .. attribute:: st_atime - Time of most recent access expressed in seconds. + Time of most recent access expressed in seconds since the epoch + (see the :mod:`time` module). .. attribute:: st_mtime - Time of most recent content modification expressed in seconds. + Time of most recent content modification expressed in seconds since + the epoch (see the :mod:`time` module). .. attribute:: st_ctime - Time of most recent metadata change expressed in seconds. + Time of most recent metadata change expressed in seconds since the + epoch (see the :mod:`time` module). .. versionchanged:: 3.12 ``st_ctime`` is deprecated on Windows. Use ``st_birthtime`` for @@ -3194,21 +3197,22 @@ features: .. attribute:: st_atime_ns - Time of most recent access expressed in nanoseconds as an integer. + Time of most recent access expressed in nanoseconds since the epoch + as an integer. .. versionadded:: 3.3 .. attribute:: st_mtime_ns - Time of most recent content modification expressed in nanoseconds as an - integer. + Time of most recent content modification expressed in nanoseconds since + the epoch as an integer. .. versionadded:: 3.3 .. attribute:: st_ctime_ns - Time of most recent metadata change expressed in nanoseconds as an - integer. + Time of most recent metadata change expressed in nanoseconds since the + epoch as an integer. .. versionadded:: 3.3 @@ -3219,16 +3223,17 @@ features: .. attribute:: st_birthtime - Time of file creation expressed in seconds. This attribute is not - always available, and may raise :exc:`AttributeError`. + Time of file creation expressed in seconds since the epoch + (see the :mod:`time` module). This attribute is not always available, + and may raise :exc:`AttributeError`. .. versionchanged:: 3.12 ``st_birthtime`` is now available on Windows. .. attribute:: st_birthtime_ns - Time of file creation expressed in nanoseconds as an integer. - This attribute is not always available, and may raise + Time of file creation expressed in nanoseconds since the epoch as an + integer. This attribute is not always available, and may raise :exc:`AttributeError`. .. versionadded:: 3.12 @@ -3252,6 +3257,17 @@ features: :attr:`st_atime_ns`, :attr:`st_mtime_ns`, :attr:`st_ctime_ns` and :attr:`st_birthtime_ns`. + .. note:: + + These timestamps are seconds (or nanoseconds for the ``*_ns`` variants) + since the Unix epoch (00:00:00 UTC, January 1, 1970), and are compatible + with :func:`time.time`. To convert a timestamp ``ts`` to a + :class:`datetime.datetime`, use + :func:`datetime.datetime.fromtimestamp` for local time or + ``datetime.datetime.fromtimestamp(ts, tz=datetime.timezone.utc)`` for + UTC. The function :func:`datetime.datetime.utcfromtimestamp` can also be + used to get a naive UTC datetime. + On some Unix systems (such as Linux), the following attributes may also be available: From 49caa9fff0f4b3344c004af2a7f4c26439a8817a Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Thu, 14 Aug 2025 20:50:46 +0800 Subject: [PATCH 2/4] Correct the description of the time field in the document to clearly indicate that it is the number of seconds since the Unix epoch. --- Doc/library/os.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9ab1264523fac0..c521db5a331dc0 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3177,18 +3177,18 @@ features: .. attribute:: st_atime - Time of most recent access expressed in seconds since the epoch + Time of most recent access expressed in seconds since the Unix epoch (see the :mod:`time` module). .. attribute:: st_mtime - Time of most recent content modification expressed in seconds since - the epoch (see the :mod:`time` module). + Time of most recent content modification expressed in seconds since + the Unix epoch (see the :mod:`time` module). .. attribute:: st_ctime - Time of most recent metadata change expressed in seconds since the - epoch (see the :mod:`time` module). + Time of most recent metadata change expressed in seconds since the + Unix epoch (see the :mod:`time` module). .. versionchanged:: 3.12 ``st_ctime`` is deprecated on Windows. Use ``st_birthtime`` for @@ -3197,22 +3197,22 @@ features: .. attribute:: st_atime_ns - Time of most recent access expressed in nanoseconds since the epoch + Time of most recent access expressed in nanoseconds since the Unix epoch as an integer. .. versionadded:: 3.3 .. attribute:: st_mtime_ns - Time of most recent content modification expressed in nanoseconds since - the epoch as an integer. + Time of most recent content modification expressed in nanoseconds since + the Unix epoch as an integer. .. versionadded:: 3.3 .. attribute:: st_ctime_ns - Time of most recent metadata change expressed in nanoseconds since the - epoch as an integer. + Time of most recent metadata change expressed in nanoseconds since the + Unix epoch as an integer. .. versionadded:: 3.3 @@ -3223,7 +3223,7 @@ features: .. attribute:: st_birthtime - Time of file creation expressed in seconds since the epoch + Time of file creation expressed in seconds since the Unix epoch (see the :mod:`time` module). This attribute is not always available, and may raise :exc:`AttributeError`. @@ -3232,7 +3232,7 @@ features: .. attribute:: st_birthtime_ns - Time of file creation expressed in nanoseconds since the epoch as an + Time of file creation expressed in nanoseconds since the Unix epoch as an integer. This attribute is not always available, and may raise :exc:`AttributeError`. From 49a652a02aa317e370abb74c2e2bb861ffa0e809 Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Thu, 14 Aug 2025 21:00:31 +0800 Subject: [PATCH 3/4] Fix the indentation of the time field in the document. --- Doc/library/os.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index c521db5a331dc0..e42a6c26921995 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3178,7 +3178,7 @@ features: .. attribute:: st_atime Time of most recent access expressed in seconds since the Unix epoch - (see the :mod:`time` module). + (see the :mod:`time` module). .. attribute:: st_mtime @@ -3198,7 +3198,7 @@ features: .. attribute:: st_atime_ns Time of most recent access expressed in nanoseconds since the Unix epoch - as an integer. + as an integer. .. versionadded:: 3.3 @@ -3225,7 +3225,7 @@ features: Time of file creation expressed in seconds since the Unix epoch (see the :mod:`time` module). This attribute is not always available, - and may raise :exc:`AttributeError`. + and may raise :exc:`AttributeError`. .. versionchanged:: 3.12 ``st_birthtime`` is now available on Windows. @@ -3233,8 +3233,8 @@ features: .. attribute:: st_birthtime_ns Time of file creation expressed in nanoseconds since the Unix epoch as an - integer. This attribute is not always available, and may raise - :exc:`AttributeError`. + integer. This attribute is not always available, and may raise + :exc:`AttributeError`. .. versionadded:: 3.12 From 5cc8731f9907aa6027fce05cc4def254d25fc38f Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Thu, 14 Aug 2025 21:46:10 +0800 Subject: [PATCH 4/4] Fix the indentation of the time field in the document. --- Doc/library/os.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e42a6c26921995..7378215871cb3f 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3177,18 +3177,18 @@ features: .. attribute:: st_atime - Time of most recent access expressed in seconds since the Unix epoch - (see the :mod:`time` module). + Time of most recent access expressed in seconds since the Unix epoch + (see the :mod:`time` module). .. attribute:: st_mtime - Time of most recent content modification expressed in seconds since - the Unix epoch (see the :mod:`time` module). + Time of most recent content modification expressed in seconds since + the Unix epoch (see the :mod:`time` module). .. attribute:: st_ctime - Time of most recent metadata change expressed in seconds since the - Unix epoch (see the :mod:`time` module). + Time of most recent metadata change expressed in seconds since the + Unix epoch (see the :mod:`time` module). .. versionchanged:: 3.12 ``st_ctime`` is deprecated on Windows. Use ``st_birthtime`` for @@ -3197,22 +3197,22 @@ features: .. attribute:: st_atime_ns - Time of most recent access expressed in nanoseconds since the Unix epoch - as an integer. + Time of most recent access expressed in nanoseconds since the Unix epoch + as an integer. .. versionadded:: 3.3 .. attribute:: st_mtime_ns - Time of most recent content modification expressed in nanoseconds since - the Unix epoch as an integer. + Time of most recent content modification expressed in nanoseconds since + the Unix epoch as an integer. .. versionadded:: 3.3 .. attribute:: st_ctime_ns - Time of most recent metadata change expressed in nanoseconds since the - Unix epoch as an integer. + Time of most recent metadata change expressed in nanoseconds since the + Unix epoch as an integer. .. versionadded:: 3.3 @@ -3223,18 +3223,18 @@ features: .. attribute:: st_birthtime - Time of file creation expressed in seconds since the Unix epoch - (see the :mod:`time` module). This attribute is not always available, - and may raise :exc:`AttributeError`. + Time of file creation expressed in seconds since the Unix epoch + (see the :mod:`time` module). This attribute is not always available, + and may raise :exc:`AttributeError`. .. versionchanged:: 3.12 ``st_birthtime`` is now available on Windows. .. attribute:: st_birthtime_ns - Time of file creation expressed in nanoseconds since the Unix epoch as an - integer. This attribute is not always available, and may raise - :exc:`AttributeError`. + Time of file creation expressed in nanoseconds since the Unix epoch as an + integer. This attribute is not always available, and may raise + :exc:`AttributeError`. .. versionadded:: 3.12