gh-137758: Clarify os.stat_result time fields (since Unix epoch) and add datetime conversion note#137761
gh-137758: Clarify os.stat_result time fields (since Unix epoch) and add datetime conversion note#137761tangyuan0821 wants to merge 9 commits into
Conversation
… 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>
bedevere-app
Bot
added
awaiting review
docs
…indicate that it is the number of seconds since the Unix epoch.
|
Please do not use the Update Branch button unless necessary (e.g. fixing conflicts, jogging the CI, or very old PRs) as it uses valuable resources. For more information see the devguide. |
This comment was marked as outdated.
This comment was marked as outdated.
|
This PR is stale because it has been open for 30 days with no activity. |
|
@StanFromIreland The indentation fix is in. Mind taking another look? |
|
|
||
| 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). |
There was a problem hiding this comment.
I don't think these suggestions are helpful. It sends a user to the top of the time documentation, and while there are functions that deal with timestamps, the majority don't.
There was a problem hiding this comment.
Agreed. Will remove those.
|
|
||
| .. note:: | ||
|
|
||
| These timestamps are seconds (or nanoseconds for the ``*_ns`` variants) |
There was a problem hiding this comment.
Optionally, we can add an anchor to this note and make "seconds since the Unix epoch" above link here.
| :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 |
There was a problem hiding this comment.
Don't recommend deprecated functions please.
Documentation build overview
4 files changed± library/numbers.html± library/os.html± library/tkinter.html± whatsnew/changelog.html |
| .. 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>`. |
There was a problem hiding this comment.
Please wrap these lines.
- Remove unhelpful (see the :mod:`time` module) cross-references - Add .. _stat-result-timestamps: anchor and use :ref: from attributes - Remove deprecated utcfromtimestamp recommendation
|
|
||
| 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 |
There was a problem hiding this comment.
Note that this won't work for nanosecond timestamps.
|
|
||
| Time of most recent metadata change expressed in nanoseconds as an | ||
| integer. | ||
| Time of most recent metadata change expressed in nanoseconds since the |
There was a problem hiding this comment.
We can also link to the note here?
3 participants
#137758
📚 Documentation preview 📚: https://cpython-previews--137761.org.readthedocs.build/