[doc] pdb access to return value

[romuald]

BPO	42524
Nosy	@romuald, @iritkatriel
PRs	bpo-42524: Add retval [variable] option to pdb #23601 bpo-42524: pdb: additional documentation on retval #27612

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-12-01.15:13:18.533>
labels = ['type-feature', 'library', '3.9', '3.10', '3.11']
title = '[doc] pdb access to return value'
updated_at = <Date 2021-08-05.08:10:47.486>
user = 'https://github.com/romuald'

bugs.python.org fields:

activity = <Date 2021-08-05.08:10:47.486>
actor = 'Romuald'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2020-12-01.15:13:18.533>
creator = 'Romuald'
dependencies = []
files = []
hgrepos = []
issue_num = 42524
keywords = ['patch']
message_count = 5.0
messages = ['382259', '398853', '398855', '398894', '398896']
nosy_count = 2.0
nosy_names = ['Romuald', 'iritkatriel']
pr_nums = ['23601', '27612']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42524'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[romuald]

When using the pdb module, there is currently no way to easy access the current return value of the stack

This return value is accessed by the 'retval command'

I propose using the currently unused argument to allow storing the return value in the local variables, accessible via the debugger

For example:

    def foo():
        debugger()
        return ComplexObject()

    def bar():
        return foo()

(pdb) retval
<ComplexObject instance at 0x1234>
(pdb) retval zz
(pdb) zz.attribute
'some value'

[iritkatriel]

It actually is in the locals, and it's called __return__. So you can access it with

locals()['__return__']

I'll try to see where that can be documented.

[iritkatriel]

I just noticed your PR. Would you like to continue working on this?

I think we should update the documentation of retval (in the doc and in the function's doctring) to say:

"""
retval
Print the return value for the last return of a function. Alternatively, the return value can be accessed with locals()['__return__'].
"""

Then add unit tests and examples as you did.

[romuald]

I'm not sure I follow.

You wish to "simply" update the doc? (and not update the retval to allow storing it into a varible. I'm OK with that)

But if we choose this, I'm not sure what needs changing in the doctests :-?

Another interrogation: is the use locals() really necessary? I can see that I can simply use __return__ to access the return object.
Is there a reason to access it via locals() inside pdb?

[iritkatriel]

Yes, exactly - to update the doc so that the next person who needs it will easily find a way to do it (which was not available to you when you created this issue).

The test should assert that what the doc says, so that if someone breaks documented functionality we will immediately know.

Your point about accessing __return__ directly from the prompt is interesting - sure, if that works just document that and make sure the test fails if we make a change that breaks it.

[gaogaotiantian]

The return value can be accessed with $_retval now.