
Hi, I see PEP 418 gives time.clock_info() two boolean fields named "is_monotonic" and "is_adjusted". I think the "is_" is unnecessary and a bit ugly, and they could just be renamed "monotonic" and "adjusted". Thoughts? -- Regards, Benjamin

In http://mail.python.org/pipermail/python-dev/2012-April/119134.html Benjamin Peterson wrote:
I agree with monotonic, but I think it should be "adjustable". To me, "adjusted" and "is_adjusted" both imply that an adjustment has already been made; "adjustable" only implies that it is possible. I do remember concerns (including Stephen J. Turnbull's <CAL_0O19nmi0+zB+tV8poZDAffNdTnohxo9y5dbw+E2q=9rX9YA@mail.gmail.com> ) that "adjustable" should imply at least a list of past adjustments, and preferably a way to make an adjustment. I just think that stating it is adjustable (without saying how, or whether and when it already happened) is less wrong than claiming it is already adjusted just in case it might have been. -jJ -- If there are still threading problems with my replies, please email me with details, so that I can try to resolve them. -jJ

On 30Apr2012 09:26, Mark Shannon <mark@hotpy.org> wrote: | monotonic is an adjective, Yes. | whereas adjusted is (part of) a verb. No. It is an adjective. | I think | both should be adjectives. Does "adjusted" mean that it has been | adjusted, that it can be adjusted or it will be adjusted? That depends on context. Reach for the doco. Of course, in the context of the PEP means "may be adjusted by exterior clock maintenance like NTP, and in fact this may have already happened". I am unhappy with that filled with underscores and used as the name:-( Cheers, -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ Experience is what you get when you don't get what you want.

On 29Apr2012 21:31, Benjamin Peterson <benjamin@python.org> wrote: | 2012/4/29 Jim J. Jewett <jimjjewett@gmail.com>: | > In http://mail.python.org/pipermail/python-dev/2012-April/119134.html | > Benjamin Peterson wrote: | > | >> I see PEP 418 gives time.clock_info() two boolean fields named | >> "is_monotonic" and "is_adjusted". I think the "is_" is unnecessary and | >> a bit ugly, and they could just be renamed "monotonic" and "adjusted". | > | > I agree with monotonic, but I think it should be "adjustable". | | I don't really care, but I think "adjusted" is fine. As in "this clock | is adjusted (occasionally)". -1 on "adjustable". That suggests the user can adjust it, not that the OS may adjust it. +1 on "adjusted" over "is_adjusted". -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ Winter is gods' way of telling us to polish. - Peter Harper <bo165@freenet.carleton.ca> <harperp@algonquinc.on.ca>

To me, "adjusted" and "is_adjusted" both imply that an adjustment has already been made; "adjustable" only implies that it is possible.
The documentation is: "True if the clock can be adjusted (e.g. by a NTP daemon), False otherwise." I prefer "adjustable", because no OS tell us if the clock has an ajustement or not... except Windows: see GetSystemTimeAdjustment(). http://msdn.microsoft.com/en-us/library/windows/desktop/ms724394%28v=vs.85%2... I propose to rename is_adjusted (which is now called adjusted) to adjustable, and not use GetSystemTimeAdjustment() on Windows but hardcode the value to True for the system clock, False for other functions (GetTick, QueryPerformanceCounter, ...). Victor

On 04May2012 01:47, Victor Stinner <victor.stinner@gmail.com> wrote: | I prefer "adjustable", because no OS tell us if the clock has an | ajustement or not... except Windows: see GetSystemTimeAdjustment(). | http://msdn.microsoft.com/en-us/library/windows/desktop/ms724394%28v=vs.85%2... | | I propose to rename is_adjusted (which is now called adjusted) to | adjustable, I'm -1 on that. To my mind "adjustable" suggests that the caller can adjust the clock, while "adjusted" suggests that the clock may be adjusted by a mechanism outside the caller's hands. That latter is the meaning in the context of the PEP. Cheers, -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ I'm not making any of this up you know. - Anna Russell

2012/5/4 Victor Stinner <victor.stinner@gmail.com>:
Anyway, the implementation and/or the documentation is buggy and should be fixed (especially the Windows case).
Done, I renamed "adjusted" to "adjustable", fixed its value on Windows (time.time) and Linux (time.monotonic), and updated the doc. -- changeset: 77415:0e46e0cd368f tag: tip user: Victor Stinner <victor.stinner@gmail.com> date: Tue Jun 12 22:46:37 2012 +0200 files: Doc/library/time.rst Include/pytime.h Lib/test/test_time.py Misc/NEWS Modules/timemodule.c Python/pytime.c description: PEP 418: Rename adjusted attribute to adjustable in time.get_clock_info() result Fix also its value on Windows and Linux according to its documentation: "adjustable" indicates if the clock *can be* adjusted, not if it is or was adjusted. In most cases, it is not possible to indicate if a clock is or was adjusted. -- Basically, time.get_clock_info().adjustable is only True for time.time(). It can also be True for time.perf_counter() if time.monotonic() is not available. I prefer "adjustable" over "adjusted" because it is well defined and its value is well known. For example, it is not easy to say if time.monotonic() is "adjusted" or not on Linux, whereas I can say that time.monotonic() is not *adjustable* on any OS. I will update the PEP except if someone complains :-) Sorry for being late, but I was exhausted by this PEP. Victor

On Fri, May 4, 2012 at 10:12 AM, Cameron Simpson <cs@zip.com.au> wrote:
+1 The connotations of "adjusted" and "adjustable" are slightly different and, in this case, "adjusted" is a better fit. The fact that "adjusted" may be misinterpreted as "this clock has been adjusted in the past" (incorrectly leaving out the "and/or may be adjusted in the future" part) is still closer to the mark than the likely misinterpretation of "adjustable" as meaning "can be adjusted directly by the application" (which is simply false, unless the application starts tinkering with the relevant platform specific time configuration interfaces, which aren't exposed by the standard library). Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

In http://mail.python.org/pipermail/python-dev/2012-April/119134.html Benjamin Peterson wrote:
I agree with monotonic, but I think it should be "adjustable". To me, "adjusted" and "is_adjusted" both imply that an adjustment has already been made; "adjustable" only implies that it is possible. I do remember concerns (including Stephen J. Turnbull's <CAL_0O19nmi0+zB+tV8poZDAffNdTnohxo9y5dbw+E2q=9rX9YA@mail.gmail.com> ) that "adjustable" should imply at least a list of past adjustments, and preferably a way to make an adjustment. I just think that stating it is adjustable (without saying how, or whether and when it already happened) is less wrong than claiming it is already adjusted just in case it might have been. -jJ -- If there are still threading problems with my replies, please email me with details, so that I can try to resolve them. -jJ

On 30Apr2012 09:26, Mark Shannon <mark@hotpy.org> wrote: | monotonic is an adjective, Yes. | whereas adjusted is (part of) a verb. No. It is an adjective. | I think | both should be adjectives. Does "adjusted" mean that it has been | adjusted, that it can be adjusted or it will be adjusted? That depends on context. Reach for the doco. Of course, in the context of the PEP means "may be adjusted by exterior clock maintenance like NTP, and in fact this may have already happened". I am unhappy with that filled with underscores and used as the name:-( Cheers, -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ Experience is what you get when you don't get what you want.

On 29Apr2012 21:31, Benjamin Peterson <benjamin@python.org> wrote: | 2012/4/29 Jim J. Jewett <jimjjewett@gmail.com>: | > In http://mail.python.org/pipermail/python-dev/2012-April/119134.html | > Benjamin Peterson wrote: | > | >> I see PEP 418 gives time.clock_info() two boolean fields named | >> "is_monotonic" and "is_adjusted". I think the "is_" is unnecessary and | >> a bit ugly, and they could just be renamed "monotonic" and "adjusted". | > | > I agree with monotonic, but I think it should be "adjustable". | | I don't really care, but I think "adjusted" is fine. As in "this clock | is adjusted (occasionally)". -1 on "adjustable". That suggests the user can adjust it, not that the OS may adjust it. +1 on "adjusted" over "is_adjusted". -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ Winter is gods' way of telling us to polish. - Peter Harper <bo165@freenet.carleton.ca> <harperp@algonquinc.on.ca>

To me, "adjusted" and "is_adjusted" both imply that an adjustment has already been made; "adjustable" only implies that it is possible.
The documentation is: "True if the clock can be adjusted (e.g. by a NTP daemon), False otherwise." I prefer "adjustable", because no OS tell us if the clock has an ajustement or not... except Windows: see GetSystemTimeAdjustment(). http://msdn.microsoft.com/en-us/library/windows/desktop/ms724394%28v=vs.85%2... I propose to rename is_adjusted (which is now called adjusted) to adjustable, and not use GetSystemTimeAdjustment() on Windows but hardcode the value to True for the system clock, False for other functions (GetTick, QueryPerformanceCounter, ...). Victor

On 04May2012 01:47, Victor Stinner <victor.stinner@gmail.com> wrote: | I prefer "adjustable", because no OS tell us if the clock has an | ajustement or not... except Windows: see GetSystemTimeAdjustment(). | http://msdn.microsoft.com/en-us/library/windows/desktop/ms724394%28v=vs.85%2... | | I propose to rename is_adjusted (which is now called adjusted) to | adjustable, I'm -1 on that. To my mind "adjustable" suggests that the caller can adjust the clock, while "adjusted" suggests that the clock may be adjusted by a mechanism outside the caller's hands. That latter is the meaning in the context of the PEP. Cheers, -- Cameron Simpson <cs@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ I'm not making any of this up you know. - Anna Russell

2012/5/4 Victor Stinner <victor.stinner@gmail.com>:
Anyway, the implementation and/or the documentation is buggy and should be fixed (especially the Windows case).
Done, I renamed "adjusted" to "adjustable", fixed its value on Windows (time.time) and Linux (time.monotonic), and updated the doc. -- changeset: 77415:0e46e0cd368f tag: tip user: Victor Stinner <victor.stinner@gmail.com> date: Tue Jun 12 22:46:37 2012 +0200 files: Doc/library/time.rst Include/pytime.h Lib/test/test_time.py Misc/NEWS Modules/timemodule.c Python/pytime.c description: PEP 418: Rename adjusted attribute to adjustable in time.get_clock_info() result Fix also its value on Windows and Linux according to its documentation: "adjustable" indicates if the clock *can be* adjusted, not if it is or was adjusted. In most cases, it is not possible to indicate if a clock is or was adjusted. -- Basically, time.get_clock_info().adjustable is only True for time.time(). It can also be True for time.perf_counter() if time.monotonic() is not available. I prefer "adjustable" over "adjusted" because it is well defined and its value is well known. For example, it is not easy to say if time.monotonic() is "adjusted" or not on Linux, whereas I can say that time.monotonic() is not *adjustable* on any OS. I will update the PEP except if someone complains :-) Sorry for being late, but I was exhausted by this PEP. Victor

On Fri, May 4, 2012 at 10:12 AM, Cameron Simpson <cs@zip.com.au> wrote:
+1 The connotations of "adjusted" and "adjustable" are slightly different and, in this case, "adjusted" is a better fit. The fact that "adjusted" may be misinterpreted as "this clock has been adjusted in the past" (incorrectly leaving out the "and/or may be adjusted in the future" part) is still closer to the mark than the likely misinterpretation of "adjustable" as meaning "can be adjusted directly by the application" (which is simply false, unless the application starts tinkering with the relevant platform specific time configuration interfaces, which aren't exposed by the standard library). Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
participants (7)
-
Antoine Pitrou
-
Benjamin Peterson
-
Cameron Simpson
-
Jim J. Jewett
-
Mark Shannon
-
Nick Coghlan
-
Victor Stinner