[issue43869] Fix documentation of epoch/time.time
New submission from Ofek Lev <ofekmeister@gmail.com>: The descriptions for the following: - https://docs.python.org/3/library/time.html#epoch - https://docs.python.org/3/library/time.html#time.time indicate that it is platform dependent. However, that is likely untrue. See the brief discussion here: https://github.com/DataDog/integrations-core/pull/6692#discussion_r427469097 ---------- assignee: docs@python components: Documentation messages: 391214 nosy: Ofekmeister, docs@python, p-ganssle priority: normal severity: normal status: open title: Fix documentation of epoch/time.time type: enhancement versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
STINNER Victor <vstinner@python.org> added the comment: On Windows 10 (build 20H2), I get: Python 3.10.0a7+ (heads/master:b136b1aac4, Apr 16 2021, 14:36:39) [MSC v.1928 64 bit (AMD64)] on win32
import time time.gmtime(0) time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)
---------- nosy: +vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
STINNER Victor <vstinner@python.org> added the comment: time.time doc says "On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC)" The epoch doc says "For Unix, the epoch is January 1, 1970, 00:00:00 (UTC)". At least, the epoch doc can be completed to also mention that it's the same on Windows. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
STINNER Victor <vstinner@python.org> added the comment: "platform dependent" was added in 2017 by the commit (bpo-29026): commit 23557d59b819f57800ddef0b1373acef8e024670 Author: Eric Appelt <eric.appelt@gmail.com> Date: Thu Feb 16 05:00:45 2017 -0500 bpo-29026: Clarify documentation of time.time (#34) * bpo-29026: Clarity documentation of time.time Clarify the documentation of time.time by more precisely defining what is meant by "seconds since the epoch" on most platforms. Additionally explain how gmtime and localtime may be used to extract calendar components and convert to a more common date format. * bpo-29026: Minor improvements for time.time doc * bpo-29026: Consistency fixes for time.time doc --- MS-DOS (no longer supported by Python since 2014) uses 1980-01-01 epoch. The Windows FILETIME type uses 1601-01-01 epoch. Python has convention functions to the Unix 1970-01-01 Epoch: static __int64 secs_between_epochs = 11644473600; /* Seconds between 1.1.1601 and 1.1.1970 */ static void FILE_TIME_to_time_t_nsec(FILETIME *in_ptr, time_t *time_out, int* nsec_out) { /* XXX endianness. Shouldn't matter, as all Windows implementations are little-endian */ /* Cannot simply cast and dereference in_ptr, since it might not be aligned properly */ __int64 in; memcpy(&in, in_ptr, sizeof(in)); *nsec_out = (int)(in % 10000000) * 100; /* FILETIME is in units of 100 nsec. */ *time_out = Py_SAFE_DOWNCAST((in / 10000000) - secs_between_epochs, __int64, time_t); } void _Py_time_t_to_FILE_TIME(time_t time_in, int nsec_in, FILETIME *out_ptr) { /* XXX endianness */ __int64 out; out = time_in + secs_between_epochs; out = out * 10000000 + nsec_in / 100; memcpy(out_ptr, &out, sizeof(out)); } More epochs for more fun: https://en.wikipedia.org/wiki/Epoch_(computing)#Notable_epoch_dates_in_compu... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
Change by Miguel Brito <miguel.mdebrito@gmail.com>: ---------- keywords: +patch nosy: +miguendes nosy_count: 4.0 -> 5.0 pull_requests: +24467 stage: -> patch review pull_request: https://github.com/python/cpython/pull/25777 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
Miguel Brito <miguel.mdebrito@gmail.com> added the comment: Seen that no one is working on this issue I created an PR to clarify the docs. https://github.com/python/cpython/pull/25777 ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43869> _______________________________________
participants (3)
-
Miguel Brito -
Ofek Lev
-
STINNER Victor