diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 7b043f257ca0b57..f7f67cab3cb4e31 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3263,15 +3263,18 @@ features: .. attribute:: st_atime - Time of most recent access expressed in seconds. + Time of most recent access expressed in + :ref:`seconds since the Unix epoch `. .. attribute:: st_mtime - Time of most recent content modification expressed in seconds. + Time of most recent content modification expressed in + :ref:`seconds since the Unix epoch `. .. attribute:: st_ctime - Time of most recent metadata change expressed in seconds. + Time of most recent metadata change expressed in + :ref:`seconds since the Unix epoch `. .. versionchanged:: 3.12 ``st_ctime`` is deprecated on Windows. Use ``st_birthtime`` for @@ -3280,21 +3283,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 @@ -3305,16 +3309,18 @@ 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 + :ref:`seconds since the Unix epoch `. + 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 @@ -3338,6 +3344,18 @@ features: :attr:`st_atime_ns`, :attr:`st_mtime_ns`, :attr:`st_ctime_ns` and :attr:`st_birthtime_ns`. + .. _stat-result-timestamps: + + .. 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. + On some Unix systems (such as Linux), the following attributes may also be available: