timeit.main has a _very_ handy autoranging facility to pick an
appropriate number of repetitions when not specified.  The autoranging
code should be lifted to a method on Timer instances (so non-main code
can use it).  If number is specified as 0 or None, I would like to use
the results of that autoranging code in Timer.repeat and Timer.timeit.

Patch to follow.

I've got the code "working" on trunk2 for my tests.
Should I port to py3K before checking in, and give diffs from there, or 
what?

You can still upload available patches to this tracker.

I would like to look at this in context of all the other proposed build-
outs to timeit.

This does not conflict with the other proposed changes to timeit and it is in-line with Guido's desire that to expose useful parts currently buried in the command-line logic.

Amaury, you've shown an interest.  Would you like to apply it?

Not sure why you chose 0.11 here. It should probably be 0.2 as in the command-line code.
As for applying the patch, this can't be done before 3.2 is released.

Looking at this again after more time has passes, I still think exposing autoranging is a good idea but I don't like the patch as it stands.  It "infects" the API in a number of places and makes the overall module harder to use and learn.   

Ideally, there should be a cleaner interface, or more limited API change, or a separate high level function that can autorange existing functions without changing their API.

Anyone care to propose a cleaner API?

In #5442, I proposed leaving the architecture of the module alone, and simply exposing the main module functionality as a high level helper function:

def measure(stmt="pass", setup="pass", timer=default_timer,
            repeat=default_repeat, number=default_number,
            verbosity=0, precision=3)

The return value would simply be a (number, results) 2-tuple with the number of iterations per test (which may have been calculated automatically), and then a list of the results. To get "timeit" style behavior, simply set "repeat=1".

Oops, that link reference should have been to #5441.

Hi, I wrote recently a similar function because timeit is not reliable by default. Results look random and require to run the same benchmark 3 times or more on the command line.

https://bitbucket.org/haypo/misc/src/tip/python/benchmark.py

By default, the benchmark takes at least 5 measures, one measure should be greater than 100 ms, and the benchmark should not be longer than 1 second. I chose these parameters to get reliable results on microbenchmarks like "abc".encode("utf-8").

The calibration function uses also the precision of the timer. The user may define a minimum time (of one measure) smaller than the timer precision, so the calibration function tries to solve such issue. The calibration computes the number of loops and the number of repetitions.

Look at BenchmarkRunner.calibrate_timer() and BenchmarkRunner.run_benchmark().
https://bitbucket.org/haypo/misc/src/bfacfb9a1224/python/benchmark.py#cl-362

> The calibration function uses also the precision of the timer.

Oh, I forgot to mention that it computes the precision in Python, it doesn't read the precision announced by the OS or the precision of the C structure.
https://bitbucket.org/haypo/misc/src/bfacfb9a1224/python/benchmark.py#cl-66

> In #5442, I proposed leaving the architecture of the module alone, and 
> simply exposing the main module functionality as a high level helper
> function:

Agreed with Nick's approach above.

Victor, if you want to improve timeit's reliability, please open a separate issue.