[docs] [issue14318] clarify "may not" in time.steady docs

Jim Jewett 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 mailing list