[New-bugs-announce] [issue43407] time.monotonic(): Docs imply comparing call N and call N+M is invalid for M>1

[Alex Willmer]

New submission from Alex Willmer <alex at moreati.org.uk>:

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.

----------
assignee: docs at python
components: Documentation
messages: 388133
nosy: Alex.Willmer, docs at python
priority: normal
severity: normal
status: open
title: time.monotonic(): Docs imply comparing call N and call N+M is invalid for M>1
versions: Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43407>
_______________________________________