PEP 418: Define time.monotonic and time.steady

pep-0418.txt

@@ -51,6 +51,32 @@ Timeouts:
  * etc.
 
 
+Functions
+=========
+
+time.monotonic
+--------------
+
+Monotonic clock advancing at a steady rate relative to real time. It cannot go
+backward. It may be adjusted. The reference point of the returned value is
+undefined so only the difference of consecutive calls is valid.
+
+May raise an OSError on error.
+
+
+time.steady
+-----------
+
+This clock advances at a steady rate relative to real time. It may 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. The function falls back to another
+clock if the monotonic clock failed or is not available.
+
+This function cannot fail.
+
+
 Clocks
 ======
 
@@ -234,6 +260,9 @@ One function with a flag: time.steady(strict=False)
 "A keyword argument that gets passed as a constant in the caller is usually
 poor API."
 
+Raising NotImplementedError for a function is something uncommon in Python and
+should be avoided.
+
 One function, no flag
 ---------------------
 
@@ -243,8 +272,8 @@ An alternative is to use a function attribute: time.steady.monotonic. The
 attribute value would be None before the first call to time.steady().
 
 
-Workaround operating system bugs?
-=================================
+Working around operating system bugs?
+=====================================
 
 Should Python ensure manually that a monotonic clock is truly monotonic by
 computing the maximum with the clock value and the previous value?