time.clock() now emits a DeprecationWarning (GH-4020)

bpo-31803: time.clock() and time.get_clock_info('clock') now emit a
DeprecationWarning warning.

Replace time.clock() with time.perf_counter() in tests and demos.

Remove also hasattr(time, 'monotonic') in test_time since time.monotonic()
is now always available since Python 3.5.

Doc/library/profile.rst

@@ -575,7 +575,7 @@ procedure can be used to obtain a better constant for a given platform (see
 The method executes the number of Python calls given by the argument, directly
 and again under the profiler, measuring the time for both. It then computes the
 hidden overhead per profiler event, and returns that as a float.  For example,
-on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.clock() as
+on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.process_time() as
 the timer, the magical number is about 4.04e-6.
 
 The object of this exercise is to get a fairly consistent result. If your

Doc/library/time.rst

@@ -289,6 +289,9 @@ Functions
 
 .. function:: perf_counter()
 
+   .. index::
+      single: benchmarking
+
    Return the value (in fractional seconds) of a performance counter, i.e. a
    clock with the highest available resolution to measure a short duration.  It
    does include time elapsed during sleep and is system-wide.  The reference
@@ -300,6 +303,11 @@ Functions
 
 .. function:: process_time()
 
+   .. index::
+      single: CPU time
+      single: processor time
+      single: benchmarking
+
    Return the value (in fractional seconds) of the sum of the system and user
    CPU time of the current process.  It does not include time elapsed during
    sleep.  It is process-wide by definition.  The reference point of the

Lib/ctypes/test/test_numbers.py

@@ -241,7 +241,7 @@ class c_int_S(_SimpleCData):
 def run_test(rep, msg, func, arg=None):
 ##    items = [None] * rep
     items = range(rep)
-    from time import clock
+    from time import perf_counter as clock
     if arg is not None:
         start = clock()
         for i in items:

Lib/ctypes/test/test_strings.py

@@ -194,7 +194,7 @@ def test_toolong(self):
 
 def run_test(rep, msg, func, arg):
     items = range(rep)
-    from time import clock
+    from time import perf_counter as clock
     start = clock()
     for i in items:
         func(arg); func(arg); func(arg); func(arg); func(arg)

Lib/profile.py

@@ -195,7 +195,7 @@ def trace_dispatch(self, frame, event, arg):
             self.t = r[0] + r[1] - t # put back unrecorded delta
 
     # Dispatch routine for best timer program (return = scalar, fastest if
-    # an integer but float works too -- and time.clock() relies on that).
+    # an integer but float works too -- and time.process_time() relies on that).
 
     def trace_dispatch_i(self, frame, event, arg):
         timer = self.timer

Lib/test/test_time.py

@@ -9,6 +9,7 @@
 import time
 import threading
 import unittest
+import warnings
 try:
     import _testcapi
 except ImportError:
@@ -64,9 +65,11 @@ def test_time(self):
         self.assertTrue(info.adjustable)
 
     def test_clock(self):
-        time.clock()
+        with self.assertWarns(DeprecationWarning):
+            time.clock()
 
-        info = time.get_clock_info('clock')
+        with self.assertWarns(DeprecationWarning):
+            info = time.get_clock_info('clock')
         self.assertTrue(info.monotonic)
         self.assertFalse(info.adjustable)
 
@@ -427,8 +430,6 @@ def test_mktime_error(self):
             pass
         self.assertEqual(time.strftime('%Z', tt), tzname)
 
-    @unittest.skipUnless(hasattr(time, 'monotonic'),
-                         'need time.monotonic')
     def test_monotonic(self):
         # monotonic() should not go backward
         times = [time.monotonic() for n in range(100)]
@@ -467,8 +468,6 @@ def test_process_time(self):
         self.assertTrue(info.monotonic)
         self.assertFalse(info.adjustable)
 
-    @unittest.skipUnless(hasattr(time, 'monotonic'),
-                         'need time.monotonic')
     @unittest.skipUnless(hasattr(time, 'clock_settime'),
                          'need time.clock_settime')
     def test_monotonic_settime(self):
@@ -506,12 +505,15 @@ def test_localtime_failure(self):
         self.assertRaises(ValueError, time.ctime, float("nan"))
 
     def test_get_clock_info(self):
-        clocks = ['clock', 'perf_counter', 'process_time', 'time']
+        clocks = ['clock', 'monotonic', 'perf_counter', 'process_time', 'time']
-        if hasattr(time, 'monotonic'):
-            clocks.append('monotonic')
 
         for name in clocks:
-            info = time.get_clock_info(name)
+            if name == 'clock':
+                with self.assertWarns(DeprecationWarning):
+                    info = time.get_clock_info('clock')
+            else:
+                info = time.get_clock_info(name)
+
             #self.assertIsInstance(info, dict)
             self.assertIsInstance(info.implementation, str)
             self.assertNotEqual(info.implementation, '')

Lib/turtledemo/bytedesign.py

@@ -23,7 +23,7 @@
 """
 
 from turtle import Turtle, mainloop
-from time import clock
+from time import perf_counter as clock
 
 # wrapper for any additional drawing routines
 # that need to know about each other

Lib/turtledemo/forest.py

@@ -13,7 +13,7 @@
 """
 from turtle import Turtle, colormode, tracer, mainloop
 from random import randrange
-from time import clock
+from time import perf_counter as clock
 
 def symRandom(n):
     return randrange(-n,n+1)

Lib/turtledemo/fractalcurves.py

@@ -12,7 +12,7 @@
 scripts for turtle-graphics.
 """
 from turtle import *
-from time import sleep, clock
+from time import sleep, perf_counter as clock
 
 class CurvesTurtle(Pen):
     # example derived from

Lib/turtledemo/penrose.py

@@ -17,7 +17,7 @@
 """
 from turtle import *
 from math import cos, pi
-from time import clock, sleep
+from time import perf_counter as clock, sleep
 
 f = (5**0.5-1)/2.0   # (sqrt(5)-1)/2 -- golden ratio
 d = 2 * cos(3*pi/10)

Lib/turtledemo/tree.py

@@ -16,7 +16,7 @@
 there are 1024 turtles.
 """
 from turtle import Turtle, mainloop
-from time import clock
+from time import perf_counter as clock
 
 def tree(plist, l, a, f):
     """ plist is list of pens

Lib/turtledemo/wikipedia.py

@@ -14,7 +14,7 @@
 Followed by a complete undo().
 """
 from turtle import Screen, Turtle, mainloop
-from time import clock, sleep
+from time import perf_counter as clock, sleep
 
 def mn_eck(p, ne,sz):
     turtlelist = [p]

Misc/NEWS.d/next/Library/2017-10-17-22-55-13.bpo-31803.YLL1gJ.rst

@@ -0,0 +1,2 @@
+time.clock() and time.get_clock_info('clock') now emit a DeprecationWarning
+warning.

Modules/timemodule.c

@@ -104,6 +104,13 @@ perf_counter(_Py_clock_info_t *info)
 static PyObject*
 pyclock(_Py_clock_info_t *info)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                      "time.clock has been deprecated in Python 3.3 and will "
+                      "be removed from Python 3.8: "
+                      "use time.perf_counter or time.process_time "
+                      "instead", 1) < 0) {
+        return NULL;
+    }
 #ifdef MS_WINDOWS
     return perf_counter(info);
 #else