Example:

>>> dis(pickle.dumps(T, 3), annotate=1)                                                                                                                                         
    0: \x80 PROTO      3 | Protocol version indicator.                                                                                                                          
    2: ]    EMPTY_LIST   | Push an empty list.                                                                                                                                  
    3: q    BINPUT     0 | Store the stack top into the memo.  The stack is not popped.                                                                                         
    5: h    BINGET     0 | Read an object from the memo and push it on the stack.                                                                                               
    7: \x85 TUPLE1       | One-tuple.                                                                                                                                           
    8: q    BINPUT     1 | Store the stack top into the memo.  The stack is not popped.                                                                                         
   10: a    APPEND       | Append an object to a list.                                                                                                                          
   11: 0    POP          | Discard the top stack item, shrinking the stack by one item.                                                                                         
   12: h    BINGET     1 | Read an object from the memo and push it on the stack.                                                                                               
   14: .    STOP         | Stop the unpickling machine.

Perhaps the annotations should be wrapped at 78 chars/line, for improved readability?

> Perhaps the annotations should be wrapped at 78 chars/line ..

I don't know.  With deeply nested pickles, annotations may not even start before column 80.  I think further improvement in alignment and layout algorithms will show diminishing returns.  If I were to invest an effort into this, I would share it with dis.dis.

You can see how larger pickles look by running pickletools -a 27.bench with a pickle from issue5180.

LGTM

Committed in r82931 with small changes based on comments here and on IRC:

1. Annotations are separated from disassembly by spaces without '|'.
2. Made a small improvement to the annotation alignment algorithm.  Excessively long lines do not force the rest of the annotations off the screen.
3. Added ReST documentation for the new dis() argument.  The command line behavior is still undocumented.  I am watching python-dev discussion on how it should be presented in ReST.

Reopening as a documentation issue:

- manual entry should have a versionchanged
- use *arg* instead of 'arg'
- add a ReST entry describing -m pickletools

Committed documentation changes in revision 87990.