Changes after first review by Steven

Author: alessandrocucci

Doc/library/timeit.rst

@@ -58,36 +58,38 @@ Python Interface
 The module defines three convenience functions and a public class:
 
 
-.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None, max_time_taken=0.2)
+.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None, target_time=0.2)
 
    Create a :class:`Timer` instance with the given statement, *setup* code and
    *timer* function and run its :meth:`.timeit` method with *number* executions.
    The optional *globals* argument specifies a namespace in which to execute the
    code. If *number* is 0, :meth:`.autorange` method is executed, a convenience
-   function that calls :meth:`.timeit` repeatedly so that the total time >= *max_time_taken* second.
+   function that calls :meth:`.timeit` repeatedly so that the total time >= *target_time* second.
 
    .. versionchanged:: 3.5
       The optional *globals* parameter was added.
 
    .. versionchanged:: 3.8
-      The optional *max_time_taken* parameter was added.
+      The optional *target_time* parameter was added.
 
 
-.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None, max_time_taken=0.2)
+.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None, target_time=0.2)
 
    Create a :class:`Timer` instance with the given statement, *setup* code and
    *timer* function and run its :meth:`.repeat` method with the given *repeat*
    count and *number* executions.  The optional *globals* argument specifies a
    namespace in which to execute the code. If *number* is 0, :meth:`.autorange`
    method is executed, a convenience function that calls :meth:`.timeit` repeatedly
-   so that the total time >= *max_time_taken* second.
+   so that the total time >= *target_time* second.
 
    .. versionchanged:: 3.5
       The optional *globals* parameter was added.
 
    .. versionchanged:: 3.7
       Default value of *repeat* changed from 3 to 5.
-      The optional *max_time_taken* parameter was added.
+
+   .. versionchanged:: 3.8
+      The optional *target_time* parameter was added.
 
 .. function:: default_timer()
 
@@ -97,7 +99,7 @@ The module defines three convenience functions and a public class:
       :func:`time.perf_counter` is now the default timer.
 
 
-.. class:: Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None, max_time_taken=0.2)
+.. class:: Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None, target_time=0.2)
 
    Class for timing execution speed of small code snippets.
 
@@ -124,7 +126,7 @@ The module defines three convenience functions and a public class:
       The optional *globals* parameter was added.
 
    .. versionchanged:: 3.8
-      The optional *max_time_taken* parameter was added.
+      The optional *target_time* parameter was added.
 
    .. method:: Timer.timeit(number=1000000)
 
@@ -147,15 +149,15 @@ The module defines three convenience functions and a public class:
             timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
 
 
-   .. method:: Timer.autorange(callback=None)
+   .. method:: Timer.autorange(callback=None, target_time=None)
 
       Automatically determine how many times to call :meth:`.timeit`.
 
       This is a convenience function that calls :meth:`.timeit` repeatedly
-      so that the total time >= *Timer.max_time_taken* second, returning the eventual
+      so that the total time >= *Timer.target_time* seconds, returning the eventual
       (number of loops, time taken for that number of loops). It calls
       :meth:`.timeit` with increasing numbers from the sequence 1, 2, 5,
-      10, 20, 50, ... until the time taken is at least *max_time_taken* second.
+      10, 20, 50, ... until the time taken is at least *target_time* seconds.
 
       If *callback* is given and is not ``None``, it will be called after
       each trial with two arguments: ``callback(number, time_taken)``.
@@ -243,9 +245,9 @@ Where the following options are understood:
 
    .. versionadded:: 3.5
 
-.. cmdoption:: -m, --max_time_taken=M
+.. cmdoption:: -t, --target_time=T
 
-    calls :meth:`.timeit` repeatedly so that the total time >= *max_time_taken* second
+    calls :meth:`.timeit` repeatedly so that the total time >= *target_time* seconds
 
    .. versionadded:: 3.8
 

Lib/test/test_timeit.py

@@ -143,7 +143,8 @@ def test_timeit_function_zero_iters(self):
 
     def test_timeit_function_max_time_taken(self):
         delta_time = timeit.timeit(self.fake_stmt, self.fake_setup, number=0,
-                timer=FakeTimer(), max_time_taken=1)
+                timer=FakeTimer(), target_time=1)
+        self.assertEqual(delta_time, (1, 1.0))
 
     def test_timeit_globals_args(self):
         global _global_timer
@@ -156,9 +157,9 @@ def test_timeit_globals_args(self):
         timeit.timeit(stmt='local_timer.inc()', timer=local_timer,
                       globals=locals(), number=3)
 
-    def repeat(self, stmt, setup, repeat=None, number=None, max_time_taken=0.5):
+    def repeat(self, stmt, setup, repeat=None, number=None, target_time=0.5):
         self.fake_timer = FakeTimer()
-        t = timeit.Timer(stmt=stmt, setup=setup, timer=self.fake_timer, max_time_taken=max_time_taken)
+        t = timeit.Timer(stmt=stmt, setup=setup, timer=self.fake_timer, target_time=target_time)
         kwargs = {}
         if repeat is None:
             repeat = DEFAULT_REPEAT
@@ -192,7 +193,7 @@ def test_repeat_callable_stmt(self):
 
     def test_repeat_callable_max_time_taken(self):
         self.repeat(self.fake_callable_stmt, self.fake_setup,
-                repeat=3, number=5, max_time_taken=1)
+                repeat=3, number=5, target_time=1)
 
     def test_repeat_callable_setup(self):
         self.repeat(self.fake_stmt, self.fake_callable_setup,

Lib/timeit.py

@@ -19,6 +19,8 @@
   -p/--process: use time.process_time() (default is time.perf_counter())
   -v/--verbose: print raw timing results; repeat for more digits precision
   -u/--unit: set the output time unit (nsec, usec, msec, or sec)
+  -t/--target_time: if number is 0 the code will run until it
+                    takes *at least* ``target_time`` seconds
   -h/--help: print this usage message and exit
   --: separate options from statement, use when statement starts with -
   statement: statement to be timed (default 'pass')
@@ -59,7 +61,7 @@
 default_number = 1000000
 default_repeat = 5
 default_timer = time.perf_counter
-default_time_taken = 0.2
+default_target_time = 0.2
 
 _globals = globals
 
@@ -101,10 +103,10 @@ class Timer:
     """
 
     def __init__(self, stmt="pass", setup="pass", timer=default_timer,
-                 globals=None, max_time_taken=default_time_taken):
+                 globals=None, target_time=default_target_time):
         """Constructor.  See class doc string."""
         self.timer = timer
-        self.max_time_taken = max_time_taken
+        self.target_time = target_time
         local_ns = {}
         global_ns = _globals() if globals is None else globals
         init = ''
@@ -211,9 +213,9 @@ def repeat(self, repeat=default_repeat, number=default_number):
             r.append(t)
         return r
 
-    def autorange(self, callback=None):
-        """Return the number of loops and time taken so that total time >= max_time_taken
-        (default is 0.2 seconds).
+    def autorange(self, callback=None, target_time=None):
+        """Return the number of loops and time taken so that
+        total time >= target_time (default is 0.2 seconds).
 
         Calls the timeit method with increasing numbers from the sequence
         1, 2, 5, 10, 20, 50, ... until the max_time_taken is reached.
@@ -222,28 +224,32 @@ def autorange(self, callback=None):
         If *callback* is given and is not None, it will be called after
         each trial with two arguments: ``callback(number, time_taken)``.
         """
+        if target_time is None:
+            target_time = self.target_time
         i = 1
         while True:
             for j in 1, 2, 5:
                 number = i * j
                 time_taken = self.timeit(number)
                 if callback:
                     callback(number, time_taken)
-                if time_taken >= self.max_time_taken:
+                if time_taken >= target_time:
                     return (number, time_taken)
             i *= 10
 
 
 def timeit(stmt="pass", setup="pass", timer=default_timer,
-           number=default_number, globals=None, max_time_taken=default_time_taken):
+           number=default_number, globals=None,
+           target_time=default_target_time):
     """Convenience function to create Timer object and call timeit method."""
-    return Timer(stmt, setup, timer, globals, max_time_taken).timeit(number)
+    return Timer(stmt, setup, timer, globals, target_time).timeit(number)
 
 
 def repeat(stmt="pass", setup="pass", timer=default_timer,
-           repeat=default_repeat, number=default_number, globals=None, max_time_taken=default_time_taken):
+           repeat=default_repeat, number=default_number,
+           globals=None, target_time=default_target_time):
     """Convenience function to create Timer object and call repeat method."""
-    return Timer(stmt, setup, timer, globals, max_time_taken).repeat(repeat, number)
+    return Timer(stmt, setup, timer, globals, target_time).repeat(repeat, number)
 
 
 def main(args=None, *, _wrap_timer=None):
@@ -279,7 +285,7 @@ def main(args=None, *, _wrap_timer=None):
     timer = default_timer
     stmt = "\n".join(args) or "pass"
     number = 0 # auto-determine
-    max_time_taken = default_time_taken
+    target_time = default_target_time
     setup = []
     repeat = default_repeat
     verbose = 0
@@ -304,8 +310,8 @@ def main(args=None, *, _wrap_timer=None):
                 repeat = 1
         if o in ("-p", "--process"):
             timer = time.process_time
-        if o in ("-m", "--max_time_taken"):
-            max_time_taken = a
+        if o in ("-t", "--target_time"):
+            target_time = a
         if o in ("-v", "--verbose"):
             if verbose:
                 precision += 1
@@ -323,7 +329,7 @@ def main(args=None, *, _wrap_timer=None):
     if _wrap_timer is not None:
         timer = _wrap_timer(timer)
 
-    t = Timer(stmt, setup, timer, max_time_taken=max_time_taken)
+    t = Timer(stmt, setup, timer, target_time=target_time)
     if number == 0:
         # determine number so that 0.2 <= total time < 2.0
         callback = None
@@ -334,7 +340,7 @@ def callback(number, time_taken):
                 print(msg.format(num=number, s='s' if plural else '',
                                   secs=time_taken, prec=precision))
         try:
-            number, _ = t.autorange(callback)
+            number, _ = t.autorange(callback, target_time)
         except:
             t.print_exc()
             return 1