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

[STINNER Victor]

STINNER Victor  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 

___
___
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]

STINNER Victor  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 

___
___
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]

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

___
___
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]

STINNER Victor  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 

___
___
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]

STINNER Victor  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 

___
___
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

[Éric Araujo]

Changes by Éric Araujo :


--
nosy: +haypo

___
Python tracker 

___
___
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]

New submission from Jim Jewett :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com