Skip to content

gh-137758: Clarify os.stat_result time fields (since Unix epoch) and add datetime conversion note #137761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+28 −12
Open

gh-137758: Clarify os.stat_result time fields (since Unix epoch) and add datetime conversion note #137761

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ead4f3f
gh-137758: Clarify os.stat_result time fields are seconds since the U…
tangyuan0821 Aug 14, 2025
a34b6df
Merge branch 'python:main' into main2
tangyuan0821 Aug 14, 2025
49caa9f
Correct the description of the time field in the document to clearly …
tangyuan0821 Aug 14, 2025
49a652a
Fix the indentation of the time field in the document.
tangyuan0821 Aug 14, 2025
a6b8620
Merge branch 'main' into main2
tangyuan0821 Aug 14, 2025
5cc8731
Fix the indentation of the time field in the document.
tangyuan0821 Aug 14, 2025
58d2f66
Merge branch 'main' into main2
tangyuan0821 Aug 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 28 additions & 12 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 Unix 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 Unix 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
Unix epoch (see the :mod:`time` module).

.. versionchanged:: 3.12
``st_ctime`` is deprecated on Windows. Use ``st_birthtime`` for
Expand All @@ -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 Unix 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 Unix 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
Unix epoch as an integer.

.. versionadded:: 3.3

Expand All @@ -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 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 as an integer.
This attribute is not always available, and may raise
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
Expand All @@ -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:

Expand Down
Loading