time.monotonic(): Docs imply comparing call N and call N+M is invalid for M>1

[moreati]

BPO	43407
Nosy	@terryjreedy, @moreati, @miss-islington
PRs	bpo-43407: Docs: Clarify comparisons of time.monotonic() et al results #24757 [3.8] bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757) #24768 [3.9] bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757) #24769

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2021-03-06.01:53:35.241>
created_at = <Date 2021-03-04.22:21:10.347>
labels = ['3.8', '3.9', '3.10', 'docs']
title = 'time.monotonic(): Docs imply comparing call N and call N+M is invalid for M>1'
updated_at = <Date 2021-03-06.01:53:35.240>
user = 'https://github.com/moreati'

bugs.python.org fields:

activity = <Date 2021-03-06.01:53:35.240>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-03-06.01:53:35.241>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2021-03-04.22:21:10.347>
creator = 'Alex.Willmer'
dependencies = []
files = []
hgrepos = []
issue_num = 43407
keywords = ['patch']
message_count = 5.0
messages = ['388133', '388135', '388180', '388182', '388185']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'docs@python', 'Alex.Willmer', 'miss-islington']
pr_nums = ['24757', '24768', '24769']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue43407'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[moreati]

I believe the documentation for time.monotonic() and time.perf_counter() could be misleading. Taken literally they could imply that given

delta = 0.1
a = time.monotonic()
b = time.monotonic()
c = time.monotonic()

the comparisons b - a < delta, and c - b < delta are valid; but c - a < delta is not valid.

I believe that c - a < delta is a valid comparison, and that what the documentation means to say is "only the difference between the results of subsequent calls is valid."

The exact wording (present since the functions were added in https://hg.python.org/cpython/rev/376ce937823c)

The reference point of the returned value is undefined, so that only
the difference between the results of consecutive calls is valid.

If there is agreement I'll submit a PR.

[moreati]

Discussion from #python IRC

[21:51] Given a=time.monotonic(); b=time.monotonic(); c=time.monotonic() is c-a < delta a valid comparison? Until this evening I thought so, but I've just read https://docs.python.org/3/library/time.html#time.monotonic and the wording it uses is "only the difference between the results of consecutive calls is valid" implying b-a < delta is valid, or c-b < delta; but not c-a < delta. Am I understanding the wording correctly?
[21:52] IOW is it literally only call n, and n+1. or n, and n+m?
[21:53] moreati, I think "consecutive" is incorrect there, based on the rest of that sentence.
[21:57] moreati SnoopJ yes, I agree, the consecutive wording has tripped me up when I first started using monotonic. I think there's an understated transitive property that allows a to c comparisons just fine.
[21:58] jarthur, yea, it would be deeply weird if b-a and c-b were meaningful deltas, but c-a was not
[21:59] re time.monotonic() the only reason I could of for the literal interpretation of the wording is an overflow, or integer wraparound corner case
[22:00] weirdly, the CPython doc uses the same language
[22:02] I actually ended up looking at the monotonic code a while back, and at least back then the wraparound case is really hard to reach, maybe possible on Windows if you haven't called it in a while. Either way, there was nothing in the Linux/glibc or Windows calls used that would have made the wraparound/overflow case apply to skipped evaluation of a middle observation more than it would consecutive observations.
...
[22:06] moreati, looks like this language was added when the function was, and I guess maybe nobody's ever raised this complaint about the wording: https://hg.python.org/cpython/rev/376ce937823c
[22:07] nice catch :)
...
[22:22] FTR https://bugs.python.org/issue43407
[22:28] moreati, I would recommend just submitting the PR, since it's docs.
[22:28] ok
[22:28] but I think the best wording would be something like "only the difference between two calls of this function is meaningful"
[22:30] agreed, subsequent is a $5 word in a 50c requirement. May I quote our conversation in the ticket? Ditto jarthur
[22:30] absolutely
[22:30] yep
[22:30] ty
[22:30] but yea, just open a PR, that way you need a single pass from someone with authority here rather than two ;)
[22:31] >Never use a long word where a short one will do.

[terryjreedy]

New changeset ff5f059 by Alex Willmer in branch 'master':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
ff5f059

[miss-islington]

New changeset e12a9e2 by Miss Islington (bot) in branch '3.8':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
e12a9e2

[miss-islington]

New changeset 65f3a0d by Miss Islington (bot) in branch '3.9':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
65f3a0d