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