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 <tangyuan0821@hotmail.com>

Author: tangyuan0821

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: