diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 7b043f257ca0b57..9f21225acfc2818 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,20 +3283,24 @@ features: .. attribute:: st_atime_ns - Time of most recent access expressed in nanoseconds as an integer. + Time of most recent access expressed in + :ref:`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 + Time of most recent content modification expressed in + :ref:`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 + Time of most recent metadata change expressed in + :ref:`nanoseconds since the Unix epoch ` as an integer. .. versionadded:: 3.3 @@ -3305,16 +3312,19 @@ 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 + :ref:`nanoseconds since the Unix epoch ` as an + integer. This attribute is not always available, and may raise :exc:`AttributeError`. .. versionadded:: 3.12 @@ -3338,6 +3348,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`` (in seconds) to a + :class:`datetime.datetime`, use :func:`datetime.datetime.fromtimestamp` + for local time or + ``datetime.datetime.fromtimestamp(ts, tz=datetime.timezone.utc)`` for + UTC. For ``*_ns`` timestamps, divide by ``1_000_000_000`` first. + On some Unix systems (such as Linux), the following attributes may also be available: