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

[Jim Jewett]

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.
"""

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 <report at bugs.python.org>
<http://bugs.python.org/issue14318>
_______________________________________