Documentation of `timeit.Timer.timeit` should mention that the return value depends on the timer

[tfpf]

Documentation

At the moment, it is as follows.

cpython/Lib/timeit.py

Lines 164 to 169 in cb4615f

	def timeit(self, number=default_number):
	"""Time 'number' executions of the main statement.
	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

The return value may not always be a float measured in seconds. If a different timer function is used:

timeit.timeit(timer=time.perf_counter_ns)

then it is an integer measured in nanoseconds.

Not entirely sure how to document it unambiguously, but perhaps it can be reworded to say something like: '… as a number measured in the time unit returned by the timer argument of the constructor (by default: a float measured in seconds).' Or similar?

Linked PRs

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

[Cherrymelon]

Yes, the function docstring and doc page need update

[terryjreedy]

How about replacing

a number of times, as a float measured in seconds. The
with
a number of times. The time is float seconds unless integer nanoseconds for perf_counter_ns. The

[terryjreedy]

I suggest timeit doc

timeit.default_timer()

    The default timer, which is always time.perf_counter().

be expanded to

timeit.default_timer()

    The default timer, which is always time.perf_counter(), returns float seconds.
    The alternative time.perf_counter_ns returns integer nanoseconds.

[tfpf]

How about replacing

a number of times, as a float measured in seconds. The

with

a number of times. The time is float seconds unless integer nanoseconds for perf_counter_ns. The

This sounds very clear to me. But since the module lets use any of monotonic, monotonic_ns, perf_counter, perf_counter_ns, process_time, process_time_ns, thread_time, thread_time_ns, time and time_ns, maybe this could say:

… returns the time it takes to execute the main statement a number of times. The time returned is a float measured in seconds, unless a timer function returning nanoseconds is used, in which case, the time returned is an integer measured in nanoseconds.

A bit wordy. Perhaps an example can be inserted in the main documentation?

[Cherrymelon]

So,the update description:

timeit.default_timer()

    The default timer, which is  used time.perf_counter(), returns float seconds.
    However,other timer is permitted to substitute,like perf_counter_ns or custom function.
    Note that the time unit of retrun value  depend on the function what used.

Any good advice?

[tfpf]

I think a few examples are necessary to clear all bases. In addition to terryjreedy's idea:

… returns the time it takes to execute the main statement a number of times. The return type is a float measured in seconds, unless a different timer function is used. See the examples section for more information.

And maybe just above

cpython/Doc/library/timeit.rst

Line 310 in cb4615f

The following examples show how to time expressions that contain multiple lines.

one could insert an example of what pochmann pointed out:

You can specify a different timer function to measure the time in different units.

>>> import time
>>> import timeit
>>> timeit.timeit('True != False')  # uses time.perf_counter by default, hence returns a float measured in seconds
0.020857657000306062
>>> timeit.timeit('True != False', timer=time.perf_counter_ns)  # returns an integer measured in nanoseconds
20996968
>>> timeit.timeit('True != False', timer=lambda: time.perf_counter() * 1000)  # returns a float measured in milliseconds
20.884455997496843

The docstring could probably just say that the return value depends on the timer specified.

[tfpf]

Is there any progress on this issue? The linked pull does not seem to have been updated.

[terryjreedy]

I plan on choosing from among the alternatives tomorrow to update.

[Cherrymelon]

I'm busy with new job recently,thx your work @terryjreedy

[tfpf]

The documentation hasn't been updated yet?

I am not proficient with reST, but would be willing to give this a shot using the suggestions here and in #105060.

[terryjreedy]

I have edited the PR and will merge when CI passes.