gh-137758: Clarify os.stat_result time fields (since Unix epoch) and add datetime conversion note #137761
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>
…indicate that it is the number of seconds since the Unix epoch.
Doc/library/os.rst
Outdated
| @@ -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 Unix epoch | |||
There was a problem hiding this comment.
Hello, please correct the indentation, the lines should start in the column of the start of the directive name, here that is the "a"
There was a problem hiding this comment.
Thank you for your reminder!
|
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. |
Sorry. Thanks again for your reminder. I'll re-read the devguide carefully. In addition, the previously requested changes have been fixed. You can review it again. |
Summary:
st_atime,st_mtime,st_ctime,st_birthtimeand their*_nsvariants) are measured since the Unix epoch (00:00:00 UTC, 1970-01-01).datetimeusingdatetime.fromtimestamp()and UTC example.Linked issue:
Changes：
st_atime,st_mtime,st_ctime→ “seconds since the epoch”.st_atime_ns,st_mtime_ns,st_ctime_ns→ “nanoseconds since the epoch”.st_birthtime,st_birthtime_ns→ explicitly reference the epoch.time.time; includedatetimeconversion examples.📚 Documentation preview 📚: https://cpython-previews--137761.org.readthedocs.build/