timeit is cool, but it's not appropriate for all performance testing.  For example, since it uses only a single Python process, anything that's cached is not a good candidate for timeit profiling.  The classic example is timing imports.  E.g. these are not the stats you're looking for:

$ python3 -mtimeit "import my.slow.module"

The timeit documentation should describe this caveat (are there others?) and possibly point to both cProfile and the 3rd party perf package as alternative ways to gather performance information.

Other caveats:

* The tight, repeated loops tend to have perfect branch prediction rates and 100% L1 cache hit rates that are rarely present in real code.  

  There should be links to why this matters:

   - https://stackoverflow.com/questions/11227809
   - https://www.extremetech.com/extreme/188776-how-l1-and-l2-cpu-caches-work-and-why-theyre-an-essential-part-of-modern-chips

* Code timing list.append() or anything else that uses realloc() internally tends to be timing in clean environments where the realloc() extends in-place rather than recopying all the data.  This is almost never true in real code.

* Constant folding can produce misleading results.  

  To time addition, use:

      python -m timeit -s "x=2" "x+3"

  rather than:

      python -m timeit "2+3"

* Timings include global lookups, attribute lookups, and function call overhead in addition to the operation being timed.

  Use:

      python -m timeit -s "s=list(range(20))" -s "s_index=s.index" "s_index(5)"

  rather than:

      python -m timeit -s "s=list(range(20))"  "s.index(5)"

* Comparative timings should be repeated and interleaved to show whether the timings are noisy or have been affected the processor switching to a lower clock speed to avoid overheating:

      time a
      time b
      time a         # expect this to be consistent with the first *a* timing
      time b         # expect this to be consistent with the first *b* timing

+1 to all said by Raymond. But this is rather the matter of a special article or blog post than a note in the documentation.

Other example of caching is regular expressions.

Mistakes:

python3 -m timeit -s "it = iter(range(1000000000))" "next(it)"

python3 -m timeit -s "a = []" "a.append(1)"

I remember one non-obvious trap in which I got caught. The performance of the iteration of a dict was influenced by the fact that in new dicts the order of iteration coincided with the order of creating keys, which were allocated sequentially in memory. Thus refcounts were touched in adjacent objects. This usually is not happen in real programs.

On Nov 15, 2017, at 17:00, Serhiy Storchaka <report@bugs.python.org> wrote:
> 
> +1 to all said by Raymond. But this is rather the matter of a special article or blog post than a note in the documentation.

Maybe a HOWTO on performance testing and analysis?  We already have one on instrumenting with DTRACE/SystemTap, and we could point the timeit docs to this new HOWTO.

Barry: "... possibly point to both cProfile and the 3rd party perf package as alternative ways to gather performance information."

FYI the timeit module of PyPy now emits a warning and points to the perf module: http://perf.readthedocs.io/

Yet one mistake: https://stackoverflow.com/questions/35014951/why-is-max-slower-than-sort

$ python3 -m timeit -s 'import random;a=list(range(10000));random.shuffle(a)' 'a.sort();a[-1]'

Here the list is sorted at first iteration, and all following iterations measure the speed of sorting a sorted list.