What is __return__?

The __return__ keyword only appears in the debugger code:

matt@stanley:~/src/Python-3.2$ grep -R __return__ .
./Lib/pdb.py:        frame.f_locals['__return__'] = return_value
./Lib/pdb.py:        if '__return__' in self.curframe_locals:
./Lib/pdb.py:            self.message(repr(self.curframe_locals['__return__']))
./Lib/bdb.py:        if '__return__' in frame.f_locals:
./Lib/bdb.py:            rv = frame.f_locals['__return__']

It is a return value of a function call when the pdb debugger stops after evaluating the return command. Is is very important for a return expressions with any side effect (that can't be reproduced like e.g. reading a line from pipe).

(Pdb) ...                       # stop somewhere in the debugger ...
> test.py(3)f()
-> return x + 1
(Pdb) l                         # list source: I'm just before return
1      def f():
2        x = 7
3  ->    return x + 1
(Pdb) '__return__' in locals()  # __return__ is still undefined
False
(Pdb) s
--Return--
> test.py(3)f()->8              # This printed 8 is a simple case, but frequently
(Pdb) '__return__' in locals()  # the value is an object or line shortened to 80 ch.
True                            # __return__ has the value after return
(Pdb) __return__
8

If the function exits without executing return command then is __return__ == None everytimes.