[issue14318] clarify may not in time.steady docs
STINNER Victor victor.stin...@gmail.com added the comment: I close this issue as a duplicate because it is now discussed in the PEP 418 and this PEP is going to change the new time functions (time.highres and time.monotonic/steady). -- resolution: - duplicate status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
Jim Jewett jimjjew...@gmail.com added the comment: (1) How does the user control (or even find out) which clock is used by time.steady()? If the answer is time.steady(clock=QueryPerformanceCounter) then there is no need for strict=?, but then I'm not sure what the point of time.steady itself is. I had been assuming that time.steady() relied on the best clock it could find, which shouldn't normally change on a specific machine, let alone within a single process. In that case, exposing the actual clock (or its name) as an attribute seems better than a boolean complain_if_my_machine_is_not_good_enough parameter. (2) That fragment from the C++ standard suggests that MAY NOT ought to have been replaced by the unambiguous MUST NOT. I do not think that python should repeat the editorial error. (3) Even leaving aside the question of which clock is actually provided, I still prefer a change in wording. My trailing paragraph might change with the API, but the rationale for: Return elapsed seconds as a floating point number. The start time is undefined, so only differences between calls are meaningful. steady() is the best clock for profiling response time, as opposed to CPU usage. includes: elapsed == time since something, as opposed to absolute time. If practicality and efficiency weren't important, I would even suggest that the function return an opaque object that supported only ordering and subtraction (returning a timedelta). There are enough time-related modules/classes/functions/etc that people *will* get confused; the name steady isn't obvious enough. Including the intended use case in the docstring gives people a fighting chance. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
STINNER Victor victor.stin...@gmail.com added the comment: (2) That fragment from the C++ standard suggests that MAY NOT ought to have been replaced by the unambiguous MUST NOT. No. A program cannot deny the modification of system clock and time.steady() may use the system date. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
STINNER Victor victor.stin...@gmail.com added the comment: Does may not mean that the user isn't allowed to adjust it, or that they system won't always have adjusted it? It depends on which clock is used. - clock_gettime(CLOCK_MONOTONIC_RAW) cannot be adjusted - clock_gettime(CLOCK_MONOTONIC) can be adjusted by NTP (only its speed, no forward or backward jump) - I don't think that QueryPerformanceCounter() can be adjusted - gettimeofday(), ftime() and time() are the system clock and can be changed manually by the system administrator or automatically by NTP (maybe with a jump, forward or backward) - clock() is used on Windows if QueryPerformanceFrequency failed. I donk't know if it can be ajdusted It is important to mention that time.steady() may be adjusted in some cases. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
STINNER Victor victor.stin...@gmail.com added the comment: FYI may not comes from the C++ Timeout Specification: Objects of class steady_clock represent clocks for which values of time_point never decrease as physical time advances and for which values of time_point advance at a steady rate relative to real time. That is, the clock may not be adjusted. http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3191.htm -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
Changes by Éric Araujo mer...@netwok.org: -- nosy: +haypo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14318] clarify may not in time.steady docs
New submission from Jim Jewett jimjjew...@gmail.com: http://docs.python.org/dev/library/time.html#time.steady Current: Return the current time as a floating point number expressed in seconds. This clock advances at a steady rate relative to real time and it may not be adjusted. The reference point of the returned value is undefined so only the difference of consecutive calls is valid. If available, a monotonic clock is used. By default, if strict is False, the function falls back to another clock if the monotonic clock failed or is not available. If strict is True, raise an OSError on error or NotImplementedError if no monotonic clock is available. Does may not mean that the user isn't allowed to adjust it, or that they system won't always have adjusted it? Assuming that this really means it won't jump around for daylight savings time or manual time resets, it could be reworded as: Return elapsed seconds as a floating point number. The start time is undefined, so only differences between calls are meaningful. steady() is the best clock for profiling response time, as opposed to CPU usage. This function prefers to rely upon a high-precision counter that is not affected by resetting the system time. If no such monotonic clock is available, steady() will substitute another clock, but steady(strict=true) will raise either NotImplementedError or OSError. -- title: clarify http://docs.python.org/dev/library/time.html#time.steady - clarify may not in time.steady docs ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14318 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
