On Tue, Jul 20, 2021 at 4:52 AM Nick Coghlan <ncoghlan@gmail.com> wrote:
[Petr]
>> int PyLocals_GetReturnBehavior();  # better name?
[Nick]
> We've used "Kind" for similar APIs elsewhere, so calling this API "PyLocals_Kind()" would make sense to me.
>
> However, there's a potential point of confusion here, as there's already an implementation level "locals kind" that the runtime uses. This public kind is related to that internal kind, but they're not the same.

[Nick, responding to himself]
Now that I'm on my actual computer rather than my phone, some further
details on the new-in-Python-3.11 internal-only API that already
refers to "locals kind":

Typedef name: _PyLocals_Kind
Value flags: CO_FAST_LOCAL, CO_FAST_CELL, CO_FAST_FREE (with more
expected to be defined in the future)
Frame local variable lookup API: _PyLocals_GetKind, _PyLocals_SetKind

Rather than relating to the frame as a whole, these flags relate to
individual variables on the frame. CO_FAST_FREE can even be used on
non-optimised frames, since classes defined inside functions have
access to variables defined in the function scope.

Due to this, I'd definitely want to hear Mark Shannon's opinion before
we went down the path of using "PyLocals_Kind" (or variations on that
theme) as a public API, since we'd need to rename the internal APIs to
avoid confusion if we did that.

I don't think a rename would be too bad though - since the existing
flags relate to individual local variables, my suggestion would be to
use `LocalVar` instead of `Locals`, giving the revised enum name
_PyLocalVar_Kind, and _PyLocalVar_GetKind and _PyLocalVar_SetKind as
the access and update methods. (There are only 27 hits on the
_PyLocals prefix across the current 3.11 code base, all relating to
this internal API)

My name isn't Mark Shannon, but I was involved in picking this name. I think it's fine to rename this concept to "local variable kind" and spell the typedef as you propose, though I think I'd like it slightly better to switch from "Locals" to "Local", and to put the underscore after that: `_PyLocal_VarKind`, `_PyLocal_GetVarKind()`, `_PyLocal_SetVarKind()`. (The API for this is very much in flux -- we'll settle by 3.11 beta 1 though. I expect we'll also have some Python-level public (but unstable) API to access these flags, so people can play around with this stuff.)

--
--Guido van Rossum (python.org/~guido)