- make the 0.2s time configurable;

- have `timeit` and `repeat` methods (and functions) fall back
  on `autorange` if the number is set to 0 or None.

Author: alessandrocucci

Doc/library/timeit.rst

@@ -58,29 +58,36 @@ 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)
+.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None, max_time_taken=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.
+   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.
 
    .. versionchanged:: 3.5
       The optional *globals* parameter was added.
 
+   .. versionchanged:: 3.7
+      The optional *max_time_taken* parameter was added.
+
 
-.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)
+.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None, max_time_taken=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.
+   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.
 
    .. 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.
 
 .. function:: default_timer()
 
@@ -90,7 +97,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)
+.. class:: Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None, max_time_taken=0.2)
 
    Class for timing execution speed of small code snippets.
 
@@ -116,6 +123,9 @@ The module defines three convenience functions and a public class:
    .. versionchanged:: 3.5
       The optional *globals* parameter was added.
 
+   .. versionchanged:: 3.7
+      The optional *max_time_taken* parameter was added.
+
    .. method:: Timer.timeit(number=1000000)
 
       Time *number* executions of the main statement.  This executes the setup
@@ -142,10 +152,10 @@ The module defines three convenience functions and a public class:
       Automatically determine how many times to call :meth:`.timeit`.
 
       This is a convenience function that calls :meth:`.timeit` repeatedly
-      so that the total time >= 0.2 second, returning the eventual
+      so that the total time >= *Timer.max_time_taken* second, 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 0.2 second.
+      10, 20, 50, ... until the time taken is at least *max_time_taken* second.
 
       If *callback* is given and is not ``None``, it will be called after
       each trial with two arguments: ``callback(number, time_taken)``.
@@ -202,7 +212,7 @@ Command-Line Interface
 
 When called as a program from the command line, the following form is used::
 
-   python -m timeit [-n N] [-r N] [-u U] [-s S] [-h] [statement ...]
+   python -m timeit [-n N] [-r N] [-u U] [-s S] [-m M] [-h] [statement ...]
 
 Where the following options are understood:
 
@@ -233,6 +243,12 @@ Where the following options are understood:
 
    .. versionadded:: 3.5
 
+.. cmdoption:: -m, --max_time_taken=M
+
+    calls :meth:`.timeit` repeatedly so that the total time >= *max_time_taken* second
+
+   .. versionadded:: 3.7
+
 .. cmdoption:: -v, --verbose
 
    print raw timing results; repeat for more digits precision

Lib/test/test_timeit.py

@@ -107,8 +107,8 @@ def timeit(self, stmt, setup, number=None, globals=None):
             kwargs['number'] = number
         delta_time = t.timeit(**kwargs)
         self.assertEqual(self.fake_timer.setup_calls, 1)
-        self.assertEqual(self.fake_timer.count, number)
-        self.assertEqual(delta_time, number)
+        self.assertEqual(self.fake_timer.count, number or 1)
+        self.assertEqual(delta_time, number or (1, 1.0))
 
     # Takes too long to run in debug build.
     #def test_timeit_default_iters(self):
@@ -139,7 +139,11 @@ def test_timeit_callable_stmt_and_setup(self):
     def test_timeit_function_zero_iters(self):
         delta_time = timeit.timeit(self.fake_stmt, self.fake_setup, number=0,
                 timer=FakeTimer())
-        self.assertEqual(delta_time, 0)
+        self.assertEqual(delta_time, (1, 1.0))
+
+    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)
 
     def test_timeit_globals_args(self):
         global _global_timer
@@ -152,9 +156,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):
+    def repeat(self, stmt, setup, repeat=None, number=None, max_time_taken=0.5):
         self.fake_timer = FakeTimer()
-        t = timeit.Timer(stmt=stmt, setup=setup, timer=self.fake_timer)
+        t = timeit.Timer(stmt=stmt, setup=setup, timer=self.fake_timer, max_time_taken=max_time_taken)
         kwargs = {}
         if repeat is None:
             repeat = DEFAULT_REPEAT
@@ -166,8 +170,8 @@ def repeat(self, stmt, setup, repeat=None, number=None):
             kwargs['number'] = number
         delta_times = t.repeat(**kwargs)
         self.assertEqual(self.fake_timer.setup_calls, repeat)
-        self.assertEqual(self.fake_timer.count, repeat * number)
-        self.assertEqual(delta_times, repeat * [float(number)])
+        self.assertEqual(self.fake_timer.count, (repeat * number) if number else repeat)
+        self.assertEqual(delta_times, repeat * [float(number) or (1, 1.0)])
 
     # Takes too long to run in debug build.
     #def test_repeat_default(self):
@@ -186,6 +190,10 @@ def test_repeat_callable_stmt(self):
         self.repeat(self.fake_callable_stmt, self.fake_setup,
                 repeat=3, number=5)
 
+    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)
+
     def test_repeat_callable_setup(self):
         self.repeat(self.fake_stmt, self.fake_callable_setup,
                 repeat=3, number=5)
@@ -208,7 +216,7 @@ def test_repeat_function_zero_reps(self):
     def test_repeat_function_zero_iters(self):
         delta_times = timeit.repeat(self.fake_stmt, self.fake_setup, number=0,
                 timer=FakeTimer())
-        self.assertEqual(delta_times, DEFAULT_REPEAT * [0.0])
+        self.assertEqual(delta_times, DEFAULT_REPEAT * [(1, 1.0)])
 
     def assert_exc_string(self, exc_string, expected_exc_name):
         exc_lines = exc_string.splitlines()

Lib/timeit.py

@@ -59,6 +59,7 @@
 default_number = 1000000
 default_repeat = 5
 default_timer = time.perf_counter
+default_time_taken = 0.2
 
 _globals = globals
 
@@ -75,10 +76,12 @@ def inner(_it, _timer{init}):
     return _t1 - _t0
 """
 
+
 def reindent(src, indent):
     """Helper to reindent a multi-line statement."""
     return src.replace("\n", "\n" + " "*indent)
 
+
 class Timer:
     """Class for timing execution speed of small code snippets.
 
@@ -98,9 +101,10 @@ class Timer:
     """
 
     def __init__(self, stmt="pass", setup="pass", timer=default_timer,
-                 globals=None):
+                 globals=None, max_time_taken=default_time_taken):
         """Constructor.  See class doc string."""
         self.timer = timer
+        self.max_time_taken = max_time_taken
         local_ns = {}
         global_ns = _globals() if globals is None else globals
         init = ''
@@ -169,6 +173,8 @@ def timeit(self, number=default_number):
         to one million.  The main statement, the setup statement and
         the timer function to be used are passed to the constructor.
         """
+        if not number:
+            return self.autorange()
         it = itertools.repeat(None, number)
         gcold = gc.isenabled()
         gc.disable()
@@ -206,11 +212,12 @@ def repeat(self, repeat=default_repeat, number=default_number):
         return r
 
     def autorange(self, callback=None):
-        """Return the number of loops and time taken so that total time >= 0.2.
+        """Return the number of loops and time taken so that total time >= max_time_taken
+        (default is 0.2 seconds).
 
         Calls the timeit method with increasing numbers from the sequence
-        1, 2, 5, 10, 20, 50, ... until the time taken is at least 0.2
-        second.  Returns (number, time_taken).
+        1, 2, 5, 10, 20, 50, ... until the max_time_taken is reached.
+        Returns (number, time_taken).
 
         If *callback* is given and is not None, it will be called after
         each trial with two arguments: ``callback(number, time_taken)``.
@@ -222,19 +229,22 @@ def autorange(self, callback=None):
                 time_taken = self.timeit(number)
                 if callback:
                     callback(number, time_taken)
-                if time_taken >= 0.2:
+                if time_taken >= self.max_time_taken:
                     return (number, time_taken)
             i *= 10
 
+
 def timeit(stmt="pass", setup="pass", timer=default_timer,
-           number=default_number, globals=None):
+           number=default_number, globals=None, max_time_taken=default_time_taken):
     """Convenience function to create Timer object and call timeit method."""
-    return Timer(stmt, setup, timer, globals).timeit(number)
+    return Timer(stmt, setup, timer, globals, max_time_taken).timeit(number)
+
 
 def repeat(stmt="pass", setup="pass", timer=default_timer,
-           repeat=default_repeat, number=default_number, globals=None):
+           repeat=default_repeat, number=default_number, globals=None, max_time_taken=default_time_taken):
     """Convenience function to create Timer object and call repeat method."""
-    return Timer(stmt, setup, timer, globals).repeat(repeat, number)
+    return Timer(stmt, setup, timer, globals, max_time_taken).repeat(repeat, number)
+
 
 def main(args=None, *, _wrap_timer=None):
     """Main program, used when run as a script.
@@ -259,7 +269,7 @@ def main(args=None, *, _wrap_timer=None):
     try:
         opts, args = getopt.getopt(args, "n:u:s:r:tcpvh",
                                    ["number=", "setup=", "repeat=",
-                                    "time", "clock", "process",
+                                    "time", "clock", "process", "max_time_taken="
                                     "verbose", "unit=", "help"])
     except getopt.error as err:
         print(err)
@@ -269,6 +279,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
     setup = []
     repeat = default_repeat
     verbose = 0
@@ -293,6 +304,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 ("-v", "--verbose"):
             if verbose:
                 precision += 1
@@ -310,7 +323,7 @@ def main(args=None, *, _wrap_timer=None):
     if _wrap_timer is not None:
         timer = _wrap_timer(timer)
 
-    t = Timer(stmt, setup, timer)
+    t = Timer(stmt, setup, timer, max_time_taken=max_time_taken)
     if number == 0:
         # determine number so that 0.2 <= total time < 2.0
         callback = None
@@ -370,5 +383,6 @@ def format_time(dt):
                                UserWarning, '', 0)
     return None
 
+
 if __name__ == "__main__":
     sys.exit(main())