What is __return__?

Question

I am debugging a script in Python 3.1 and discovered this:

(Pdb) p locals() {'count': 264, 'self': , 'depth': 1, 'offset': 0, '__return__': None, 'blkno': 4, 'size': 264}

I found deferred PEP that mentions it, and little else.

What is __return__? When was it added? How is it useful?

Answer 1

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.

Answer 2

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__']

Answer 3

It's a common or garden local name, possibly a name for a function or a value, as you can tell from the fact that its name is in locals(). You would need to look at the code that defines it to see what it's used for. The fact that it starts with a double-underscore hints that it is a special value of some sort; perhaps it's used to hold the return value for some function. However, Python itself does not give any special meaning to the name __return__, so it could really be anything.

Knowing where you found it would be a nice start...