[Python-Dev] trace.py and the obscurity of Tools/scripts/ (was: Unittest list)

[Tim Peters]

[Zooko]
> ...
> It would require better docs regarding the programmatic usage.

I believe it needs much better docs period.  I've tried to steer people
toward it, but they just can't figure out how to use it.

> Anything else that would be required for trace to make this transition?

It would help if the bugs were fixed, or identified as common gotchas and
explained in the hypothesized better docs <wink>.  For example,

def f(n):
    sum = 0
    for i in range(n):
        sum
        for j in range(n):
            sum += 1
    return sum

print f(10)

produces a .cover file containing

    2: def f(n):
    2:     sum = 0
   12:     for i in range(n):
   10:         sum
  120:         for j in range(n):
  100:             sum += 1
    1:     return sum
    .
    1: print f(10)

Half the counts reported are "a surprise" to the uninitiated in one way or
another; most people seem to expect

    1: def f(n):
    1:     sum = 0
    1:     for i in range(n):
   10:         sum
   10:         for j in range(n):
  100:             sum += 1
    1:     return sum
    .
    1: print f(10)

while a smaller but still significant number seem to expect

    1: def f(n):
    1:     sum = 0
   11:     for i in range(n):
   10:         sum
  110:         for j in range(n):
  100:             sum += 1
    1:     return sum
    .
    1: print f(10)

I realize "intuitive" counts are hard to achieve, but if it's in the
standard library I'm likely to become the one who has to try to explain
"non-intuitive" counts away year after year after year.  So, to save myself
a couple years of possibly otherwise happy life <wink>, I'm -1 unless the
docs do a great job of cutting off questions before they get asked.