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

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 <stat-result-timestamps>`.
 
    .. 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 <stat-result-timestamps>`.
 
    .. 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 <stat-result-timestamps>`.
 
       .. 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 <stat-result-timestamps>`.
+      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: