gh-80642: timeit - make target time of autorange configurable

[miikka]

This is an updated version of PR #12954 with latest main merged in. I also fixed a few issues in the original (it's now consistently called target_time, there was a float conversion missing, etc.).

To quote the original PR:

• 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.

• Issue: timeit: Additional changes for autorange #80642

---

📚 Documentation preview 📚: https://cpython-previews--140283.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[picnixz]

Previously timeit returned a single value. Now it can return a pair if number is 0. This should be better documented because it coule be breaking existing code (I do not know if 0 was a legit value beforehand). I do not think we should expose the handling of number=0 to the timeit method itself. Or if this is the case we should first determine the number by autorange and then pass it to timeit() for the "real" test.

I cannot comment on the PR because the mobile app is not working well so I am only commenting here, but please consider this as me requesting changes.

[miikka]

Previously timeit returned a single value. Now it can return a pair if number is 0. This should be better documented because it coule be breaking existing code (I do not know if 0 was a legit value beforehand). I do not think we should expose the handling of number=0 to the timeit method itself. Or if this is the case we should first determine the number by autorange and then pass it to timeit() for the "real" test.

When I resurrected this PR, I thought this was a plausibly-useful convenience feature. However, I'm not so sure anymore:

• 0 was a legit value beforehand in the sense that it'd run the timing logic but it would not execute stmt at all. There's an unit test for the case, too. Is this useful? I browsed through a GitHub code search and it seems there are people using number=0 to essentially disable the timeit call. Returning a pair would break this usage.
• You have to return the pair, though, because you can't really use the result for anything without knowing both how long it took and the iteration count.

I'm inclined to undo the change. An alternative option would be to provide a new top level convenience method timeit.autorange() that would create a Timer instance and call autorange, like the other convenience methods work. I'm not sure if this would be appropriate.

[miikka]

Looking back at @stevendaprano's original idea, the proposal was that the autorange fallback would be used when number is 0 or None. A non-breaking alternative would be to use autorange when number is None. None has not been a legit value before (using it raises a TypeError).

[hugovk]

@picnixz Do you have any preferences here?

[picnixz]

FTR, I've seen your ping Hugo and will reply to this tomorrow or on Saturday (just need some time)

[hugovk]

@picnixz reminder :)

[picnixz]

Sorry Hugo, I saw the ping, then forgot about it. You can usually ping me earlier in general as well :) Now:

• Whatever choice we do, we can't change the return type of a public method. And we should not mix return types depending on the arguments either.
• I still don't understand why we should alter the timeit method itself. What we want is removing the hardcoded 0.2 in autorange(). Adding a parameter to autorange() is fine. The change in timeit() does not seem related (or am I just missing something?)

So I'm inclined to accept the change for configuring the hardcoded 0.2 (it's not an issue there) but I want another discussion about using None or 0 in timeit() and other methods to have "empty" loop.

[hugovk]

So I'm inclined to accept the change for configuring the hardcoded 0.2 (it's not an issue there) but I want another discussion about using None or 0 in timeit() and other methods to have "empty" loop.

Yes, sounds reasonable.

Once this PR is done, I think we could prompt for further discussion in the issue, and even put pending on it and close it if there's not much further interest for the extra stuff.

@miikka Please can you update this PR?

Thanks both!

[miikka]

Hi, sorry for taking a while to get back to this. To recap: the main goal of the PR is make the hardcoded 0.2 seconds configurable in autorange(). I've undone the changes to the timeit(). However, I did keep the non-breaking change to add --target-time parameter to the python -m timeit CLI tool.

[picnixz]

Thanks. Could you also add a What's New entry for this new feature please?

[StanFromIreland]

Suggested change

Please preserve the spacing

[StanFromIreland]

[-t T] is missing

[StanFromIreland]

Suggested change

	:mod:`timeit`:.
	:mod:`timeit`.