[docs] [issue14318] clarify "may not" in time.steady docs
report at bugs.python.org
Fri Mar 23 23:38:18 CET 2012
Jim Jewett <jimjjewett at 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.
"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 <report at bugs.python.org>
More information about the docs