[3.11] gh-105052:update timeit function's description (GH-105060) (#108535)

---------
Co-authored-by: Terry Jan Reedy tjreedy@udel.edu
Co-authored-by: R <cherrymelon@foxmail.com>
(cherry picked from commit 7096a2be33619dc02c06a6dc30aac414a9eba462)

diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst
index 660a546e721892a89a7ca50047ff2322829a006d..b59a6bc3742ae41f4630bca8095568678c4faec1 100644 (file)
--- a/Doc/library/timeit.rst
+++ b/Doc/library/timeit.rst
@@ -86,9 +86,11 @@ The module defines three convenience functions and a public class:
    .. versionchanged:: 3.7
       Default value of *repeat* changed from 3 to 5.
 
+
 .. function:: default_timer()
 
-   The default timer, which is always :func:`time.perf_counter`.
+   The default timer, which is always time.perf_counter(), returns float seconds.
+   An alternative, time.perf_counter_ns, returns integer nanoseconds.
 
    .. versionchanged:: 3.3
       :func:`time.perf_counter` is now the default timer.
@@ -124,7 +126,7 @@ The module defines three convenience functions and a public class:
 
       Time *number* executions of the main statement.  This executes the setup
       statement once, and then returns the time it takes to execute the main
-      statement a number of times, measured in seconds as a float.
+      statement a number of times.  The default timer returns seconds as a float.
       The argument is the number of times through the loop, defaulting to one
       million.  The main statement, the setup statement and the timer function
       to be used are passed to the constructor.

diff --git a/Lib/timeit.py b/Lib/timeit.py
index 9dfd454936e6b8c790297f2020d1295fc447dde6..3250563f4222ddfd49b4ccc3b16c30ab3628f62c 100755 (executable)
--- a/Lib/timeit.py
+++ b/Lib/timeit.py
@@ -50,9 +50,9 @@ Functions:
 """
 
 import gc
+import itertools
 import sys
 import time
-import itertools
 
 __all__ = ["Timer", "timeit", "repeat", "default_timer"]
 
@@ -77,9 +77,11 @@ 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)
+    return src.replace("\n", "\n" + " " * indent)
+
 
 class Timer:
     """Class for timing execution speed of small code snippets.
@@ -166,7 +168,7 @@ class Timer:
 
         To be precise, this executes the setup statement once, and
         then returns the time it takes to execute the main statement
-        a number of times, as a float measured in seconds.  The
+        a number of times, as float seconds if using the default timer.   The
         argument is the number of times through the loop, defaulting
         to one million.  The main statement, the setup statement and
         the timer function to be used are passed to the constructor.
@@ -228,16 +230,19 @@ class Timer:
                     return (number, time_taken)
             i *= 10
 
+
 def timeit(stmt="pass", setup="pass", timer=default_timer,
            number=default_number, globals=None):
     """Convenience function to create Timer object and call timeit method."""
     return Timer(stmt, setup, timer, globals).timeit(number)
 
+
 def repeat(stmt="pass", setup="pass", timer=default_timer,
            repeat=default_repeat, number=default_number, globals=None):
     """Convenience function to create Timer object and call repeat method."""
     return Timer(stmt, setup, timer, globals).repeat(repeat, number)
 
+
 def main(args=None, *, _wrap_timer=None):
     """Main program, used when run as a script.
 
@@ -270,7 +275,7 @@ def main(args=None, *, _wrap_timer=None):
 
     timer = default_timer
     stmt = "\n".join(args) or "pass"
-    number = 0 # auto-determine
+    number = 0  # auto-determine
     setup = []
     repeat = default_repeat
     verbose = 0
@@ -287,7 +292,7 @@ def main(args=None, *, _wrap_timer=None):
                 time_unit = a
             else:
                 print("Unrecognized unit. Please select nsec, usec, msec, or sec.",
-                    file=sys.stderr)
+                      file=sys.stderr)
                 return 2
         if o in ("-r", "--repeat"):
             repeat = int(a)
@@ -321,7 +326,7 @@ def main(args=None, *, _wrap_timer=None):
                 msg = "{num} loop{s} -> {secs:.{prec}g} secs"
                 plural = (number != 1)
                 print(msg.format(num=number, s='s' if plural else '',
-                                  secs=time_taken, prec=precision))
+                                 secs=time_taken, prec=precision))
         try:
             number, _ = t.autorange(callback)
         except:
@@ -372,5 +377,6 @@ def main(args=None, *, _wrap_timer=None):
                                UserWarning, '', 0)
     return None
 
+
 if __name__ == "__main__":
     sys.exit(main())

diff --git a/Misc/NEWS.d/next/Documentation/2023-05-29-14-10-24.gh-issue-105052.MGFwbm.rst b/Misc/NEWS.d/next/Documentation/2023-05-29-14-10-24.gh-issue-105052.MGFwbm.rst
new file mode 100644 (file)
index 0000000..8fdc38d
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2023-05-29-14-10-24.gh-issue-105052.MGFwbm.rst
@@ -0,0 +1 @@
+Update ``timeit`` doc to specify that time in seconds is just the default.