gh-125590: Allow FrameLocalsProxy to delete and pop keys from extra locals

[gaogaotiantian]

It's okay for us to pop/delete the keys that were added to f_locals manually, just ban the real fast variables.
@ncoghlan not sure if there's any documentation that needs to be changed.

There are two types of exceptions that could be raised:

• RuntimeError when users trying to remove a local variable
• KeyError when users trying to remove a key that does not exist

• Issue: it's no longer possible to delete items from f_locals (FrameLocalsProxy) in 3.13+ #125590

[gaogaotiantian]

@terryjreedy the only tests failed were Idle on MacOS-13, which is a bit weird. I can imagine changing f_locals impacts Idle, but only on a specific platform? Do you have any idea why the test failed? I looked at the error messages and they do not quite make sense to me.

[ZeroIntensity]

A tiny optimization to consider (though, it's more complex--feel free to reject this):

Suggested change

	PyErr_Format(PyExc_KeyError, "'%R'", key);
	PyObject*repr=PyObject_Repr(key);
	if (repr==NULL) {
	returnNULL;
	}
	PyErr_SetObject(PyExc_KeyError, repr);

[gaogaotiantian]

I just realized I could've used _PyErr_SetKeyError(key) like dictobject.c. I'll switch to that.

[ZeroIntensity]

Oh, that sounds better. I wasn't aware of that, TIL!

[gaogaotiantian]

So I switched to _PyErr_SetKeyError(key) when the key does not exist. However, for local variables cases, I think RuntimeError would fit better. One important reason was KeyError actually expects the "key" to be the explanation string, and giving a reason is a bit weird. Also in this case we have the key, we just can't remove it, so RuntimeError might be better.

[terryjreedy]

MacOS versions after 10 have various odd interactions with tkinter and python. Without a saved reference to the now-overwritten failing test, I cannot comment other than to note the following:

Searching 'locals()' in C:\Programs\Python314\Lib\idlelib\*.py ...
C:\Programs\Python314\Lib\idlelib\debugger.py: 248: self.show_locals()
C:\Programs\Python314\Lib\idlelib\debugger_r.py: 214: return self._get_f_locals()

The first call must result in the second, which I have no memory of. There is no direct test of either function. I'm glad you found better code that worked on major systems

[markshannon]

I think this needs backporting to 3.13, as that's the version mentioned in the issue

[markshannon]

The exception types need changing from RuntimeError to KeyError.
Otherwise, looks good.

[markshannon]

I think this should be a KeyError.
Users will expect mapping types to raise a KeyError. https://docs.python.org/3/library/stdtypes.html#mapping-types-dict

[markshannon]

Ditto

[bedevere-app]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[markshannon]

FTR, from this PR, the potential additions to PEP 667 would be:

 def __delitem__(self, name):
if name in co._name_to_offset_mapping:
raise KeyError(f"Cannot delete local variable '{name}'")
del self._extra_locals[name]
def pop(self, name, default):
if name in co._name_to_offset_mapping:
raise KeyError(f"Cannot delete local variable '{name}'")
return self._extra_locals.pop(name, default)

I think this is what we want.
Although maybe instead of k = KeyError(f"Cannot delete local variable '{name}'"), we could do this:

k=KeyError(name)
k.add_note("Cannot delete local variable")

[gaogaotiantian]

From the documentation, it explains KeyError as

Raised when a mapping (dictionary) key is not found in the set of existing keys.

I think there's a distinctive difference here. The key is in the mapping, we can even read it, key in mapping == True. We fail the operation because we don't allow deleting this key, not the key does not exist. I think a RuntimeError would fit better in this case.

[markshannon]

I appreciate KeyError is not ideal.

I guess the question is do we want:

try:
delf.f_locals["local_name"]
exceptKeyError:
...

to handle the exception or not?

If not, then I think ValueError is better than RuntimeError.

exception ValueError
Raised when an operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as IndexError.

Other than that, the PR looks ready to merge.

[gaogaotiantian]

I guess the question is do we want:

try:
delf.f_locals["local_name"]
exceptKeyError:
...

to handle the exception or not?

I think we need two separate exceptions because I don't know what they would do in the except block here. Trying to remove a real local variable is very different than trying to remove an artificial variable. Even for a try ... except block, I think those should be separate cases.

ValueError is okay to me.

[ncoghlan]

I also agree ValueError makes sense.

For python/peps#3845, I've described this with prose rather than the equivalent Python code:

Extra keys (which do not correspond to local variables on the underlying
frame) may be removed as usual with del statements or the pop()
method.

Using del, or the pop() method, to remove keys that correspond to local
variables on the underlying frame is NOT supported, and attempting to do so
will raise ValueError.

Local variables can only be set to None (or some other value) via the proxy,
they cannot be unbound completely.

(and then linked back to this PR and the associated bug report from the "Implementation Notes" section)

For the main docs, looking at https://docs.python.org/dev/reference/datamodel.html#frame-objects there's nothing that currently goes into that level of detail. I've filed a separate docs issue (#125731) suggesting adding a 4th subsection there that talks more about the write-through proxy behaviour.

[markshannon]

Ok, let's go with ValueError.

[markshannon]

Thanks

[miss-islington-app]

Thanks @gaogaotiantian for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @gaogaotiantian for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

GH-125797 is a backport of this pull request to the 3.13 branch.