gh-141004: Document unstable executable kind macros in `pyframe.h` by Yashp002 · Pull Request #143490 · python/cpython · GitHub

gh-141004: Document unstable executable kind macros in pyframe.h

This PR documents the PyUnstable_EXECUTABLE_KIND_* macros and the PyUnstable_ExecutableKinds array in Doc/c-api/frame.rst. These were listed as undocumented in the parent issue.

📚 Documentation preview 📚: https://cpython-previews--143490.org.readthedocs.build/

9c03215 was not backported to 3.12?

These are rather useless without docs for PyUnstable_ExecutableKinds.
Once you document that, you can associate the macros with it, like for example Py_MOD_GIL_USED with Py_mod_gil.

@encukou ok, makes sense. I'll add the documentation for PyUnstable_ExecutableKinds and link these macros to it. Thanks :)

It's an array, not an enum.
Could you document what it's useful for or how to use it? That part isn't very clear to me.

Please go through what i've mentioned below and let me know if its perfectly appropriate, and as soon I recieve the heads up i'll update and commit:

.. c:var:: PyUnstable_ExecutableKinds

An array of executable kinds (executor types) for frames, used for internal
debugging and tracing. The entries are indexed by the constants
:c:macro:PyUnstable_EXECUTABLE_KIND_SKIP or
:c:macro:PyUnstable_EXECUTABLE_KIND_PY_FUNCTION.

This can be used to identify the type of the code object associated with a frame.

.. versionadded:: 3.13

Could @encukou or @StanFromIreland please review my suggestion above and correct it if its wrong or gimme the green light to commit this ⬆️

I'd prefer some words on why/how you'd use this.

You can say “The entries are indexed by the following constants:”, and indent the docs for the constants. Since the entries are all similar, you could even use a compact table, like in code object flags.

You need to update ignored_c_api.txt here too.

Too many blank lines.

These should be links via :c:data:`PyUnstable_ExecutableKinds`

test_asyncio.test_sendfile port conflict - unrelated to docs.

We don't need those tests to run at all really, we can (I think) exclude the ignore file from triggering the run-tests condition.

Edit: See #143583.

We don't need those tests to run at all really, we can (I think) exclude the ignore file from triggering the run-tests condition.

Edit: See #143583.

Can the same be said for #143492
and #143494 then? @StanFromIreland

@StanFromIreland @encukou Here too, do I need to make any more changes?

This part is not clear to me:

Tools like debuggers and profilers can use this to identify the type of execution
context associated with a frame (e.g. to filter out internal frames).

I assume “frame” refers to PyFrameObject?
How do you use this array to filter out internal frames?

Once the docs say what the function is for and how to use it, there are some presentation issues to fix up:

There are now two descriptions for PyUnstable_EXECUTABLE_KIND_SKIP: on in list-table and one below. Choose one. If you need a full/sentence, use individual entries; if you only need a few words then the table makes sense.
Either way, indent the macro docs so they're under PyUnstable_ExecutableKinds, and use .. c:namespace:: NULL (see elsewhere in the docs for examples).

@encukou Since PyUnstable_EXECUTABLE_KIND_SKIP has only a couple words, should I just keep the list-table description and remove the one below completely?

as in the description of it below.

Also, Yes the frame refers to PyFrameObject and I'll be adding a sentence below saying "The frame should be skipped by tools.
- The frame corresponds to a standard Py function"

    Also, to check for internal frames:
    perf_map = PyUnstable_GetPerfMapFile()
    for i, kind in enumerate(perf_map):
       if kind == PyUnstable_EXECUTABLE_KIND_SKIP:
          skip_frame(i) 
          
          It's from the Cpython source code

Should i go ahead with above mentioned changes?
Also, my indents with c:macro: are fine right? or have i missed something

Since PyUnstable_EXECUTABLE_KIND_SKIP has only a couple words, should I just keep the list-table description and remove the one below completely?

Yes. But switch to the .. c:macro: syntax rather than :c:macro:, so this is a definition.

Example code would be very helpful, yes. Please test that it works, though.

Please do not use latin abbreviations, see our style guide for more information.

Yeah you mentioned this before, I'm sorry it slipped my mind, fixing now.

The .. versionadded:: ... should be the last thing in a function's/macro's/type's/etc. doc, please move it after the example.

What is kind? How do you get it?

@encukou kind here refers to the executable kind field stored in the frame's executor (e.g. _PyFrame_GetExecutableKind(frame))
Do you think it's better to explicitly show _PyFrame_GetExecutableKind (if exposed), or should I just remove the example block to avoid confusion?

Yes, explicitly show your _PyFrame_GetExecutableKind. We'll also need to make it public (or at least unstable) if we want users to use it.

Yeah, there's no API for getting kind. The only way to get the right thing is to check the type, but at that point, you don't need PyUnstable_ExecutableKinds anyway (because the whole point of it is that you're not supposed to know the type in advance). This API is quite literally useless. I think we should remove it in 3.16, but for completeness, I want this documented in 3.13+.

Thanks @Yashp002 for the PR, and @ZeroIntensity for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

Sorry, @Yashp002 and @ZeroIntensity, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker dc62ba84ab2b83d70dee111d3feec1a6f1c3f69d 3.14

GH-153988 is a backport of this pull request to the 3.15 branch.

Sorry, @Yashp002 and @ZeroIntensity, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker dc62ba84ab2b83d70dee111d3feec1a6f1c3f69d 3.13

GH-153991 is a backport of this pull request to the 3.14 branch.

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

…ame.h` (GH-143490) (GH-153988) (cherry picked from commit dc62ba8) Co-authored-by: Yashraj <yashrajpala8@gmail.com> Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

…ame.h` (GH-143490) (GH-153991) (cherry picked from commit dc62ba8) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

…ame.h` (GH-143490) (GH-153993) (cherry picked from commit dc62ba8) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

Just getting back to this.
The snippet won't work, since PyStackRef_AsPyObjectBorrow and f_executable aren't in the public API. You need Py_BUILD_CORE; f_executable can change to something else than a StackRef at any time, etc.
@ZeroIntensity, would you be OK with removing the snippet?

I would be much more comfortable with removing the API entirely.

Yeah, for 3.16. But what about the older branches?

Yeah, let's remove the snippet there, or add a note saying "you need Py_BUILD_CORE for this." Realistically, we're not going to change the type of f_executable on 3.13-3.15 (and if we were, this API wouldn't be a huge concern -- the debuggers we'd break would be a much bigger problem).

Follow-up to GH-143490. `_PyInterpreterFrame.f_executable` and `PyStackRef_AsPyObjectBorrow` are undocumented and only available in the internal API. Docs should not suggest using them, even if `PyUnstable_ExecutableKinds` is unusable without them. Co-authored-by: Stan Ulbrych <stan@python.org>

…5122) (GH-155242) Follow-up to GH-143490. `_PyInterpreterFrame.f_executable` and `PyStackRef_AsPyObjectBorrow` are undocumented and only available in the internal API. Docs should not suggest using them, even if `PyUnstable_ExecutableKinds` is unusable without them. (cherry picked from commit c5d4946) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

…5122) (GH-155240) Follow-up to GH-143490. `_PyInterpreterFrame.f_executable` and `PyStackRef_AsPyObjectBorrow` are undocumented and only available in the internal API. Docs should not suggest using them, even if `PyUnstable_ExecutableKinds` is unusable without them. (cherry picked from commit c5d4946) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>

…GH-155122) Follow-up to pythonGH-143490. `_PyInterpreterFrame.f_executable` and `PyStackRef_AsPyObjectBorrow` are undocumented and only available in the internal API. Docs should not suggest using them, even if `PyUnstable_ExecutableKinds` is unusable without them. Co-authored-by: Stan Ulbrych <stan@python.org>

first unstable py

1efbe41

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Jan 6, 2026

github-project-automation Bot added this to Docs PRs Jan 6, 2026

github-project-automation Bot moved this to Todo in Docs PRs Jan 6, 2026

bedevere-app Bot added the awaiting review label Jan 6, 2026

bedevere-app Bot mentioned this pull request Jan 6, 2026

Document the entire C API #141004

Open

fix 1

4572008

StanFromIreland reviewed Jan 6, 2026

View reviewed changes

fix 2(version)

54495a2

fix 2 pyframe

e8097b1

encukou reviewed Jan 7, 2026

View reviewed changes

ZeroIntensity reviewed Jan 8, 2026

View reviewed changes

Yashp002 added 2 commits January 8, 2026 22:04

fix 3 pyframe

9c1492f

fix 4 pyframe

a0b1951

Yashp002 added 3 commits January 22, 2026 16:26

fix 5 pyframe

927383b

Merge branch 'main' into doc-pyframe-unstable

e51340a

fix 6 pyframe

3fafd77

StanFromIreland reviewed Jan 22, 2026

View reviewed changes

pyframe fix 7

45e9a6d

encukou reviewed Jan 30, 2026

View reviewed changes

bedevere-app Bot added the awaiting merge label Jul 18, 2026

ZeroIntensity enabled auto-merge (squash) July 18, 2026 14:47

ZeroIntensity merged commit dc62ba8 into python:main Jul 18, 2026
69 of 72 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Jul 18, 2026

bedevere-app Bot removed the awaiting merge label Jul 18, 2026

miss-islington-app Bot assigned ZeroIntensity Jul 18, 2026

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 18, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 18, 2026

bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Jul 18, 2026

ZeroIntensity added a commit that referenced this pull request Jul 18, 2026

[3.14] gh-141004 : Document unstable executable kind macros from `pyfr…

6c225e0

…ame.h` (GH-143490) (GH-153991) (cherry picked from commit dc62ba8) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

ZeroIntensity added a commit that referenced this pull request Jul 18, 2026

[3.13] gh-141004 : Document unstable executable kind macros from `pyfr…

291063f

…ame.h` (GH-143490) (GH-153993) (cherry picked from commit dc62ba8) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

encukou mentioned this pull request Aug 3, 2026

gh-152105: Remove docs snippet that uses internal C API #155122

Merged

+                 Index for the "skip" kind in ``PyUnstable_ExecutableKinds``.
+                 Indicates that the frame's code object should be skipped.
+                 .. versionadded:: 3.12

+                 An enumeration of the different kinds of executables (code objects) in a frame.
+                 This can be one of the constants :c:macro:`PyUnstable_EXECUTABLE_KIND_SKIP`
+                 or :c:macro:`PyUnstable_EXECUTABLE_KIND_PY_FUNCTION`.


		.. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION

		Index for the "Python function" kind in ``PyUnstable_ExecutableKinds``.

+                 debugging and tracing.
+                 Tools like debuggers and profilers can use this to identify the type of execution
+                 context associated with a frame (e.g. to filter out internal frames).

+                    * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
+                      - The frame corresponds to a standard Python function.
+                 .. versionadded:: 3.13

+                 .. code-block:: c
+                    // Check if a frame should be skipped
+                    if (kind == PyUnstable_EXECUTABLE_KIND_SKIP) {

gh-141004: Document unstable executable kind macros in `pyframe.h` by Yashp002 · Pull Request #143490 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-141004: Document unstable executable kind macros in pyframe.h - #143490

gh-141004: Document unstable executable kind macros in pyframe.h#143490ZeroIntensity merged 19 commits intopython:mainpython/cpython:mainfrom Yashp002:doc-pyframe-unstableYashp002/cpython:doc-pyframe-unstableCopy head branch name to clipboard

Conversation

Yashp002 commented Jan 6, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou commented Jan 7, 2026

Uh oh!

Yashp002 commented Jan 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Yashp002 commented Jan 8, 2026

Uh oh!

StanFromIreland commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Yashp002 commented Jan 8, 2026

Uh oh!

Yashp002 commented Jan 17, 2026

Uh oh!

encukou commented Jan 19, 2026

Uh oh!

Yashp002 commented Jan 19, 2026

Uh oh!

encukou commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Jul 18, 2026

Uh oh!

miss-islington-app Bot commented Jul 18, 2026

Uh oh!

bedevere-app Bot commented Jul 18, 2026

Uh oh!

miss-islington-app Bot commented Jul 18, 2026

Uh oh!

bedevere-app Bot commented Jul 18, 2026

Uh oh!

bedevere-app Bot commented Jul 18, 2026

Uh oh!

encukou commented Jul 30, 2026

Uh oh!

ZeroIntensity commented Jul 30, 2026

Uh oh!

encukou commented Jul 30, 2026

Uh oh!

gh-141004: Document unstable executable kind macros in pyframe.h#143490
ZeroIntensity merged 19 commits into
python:mainfrom
Yashp002:doc-pyframe-unstable

Yashp002 commented Jan 6, 2026 •
edited by github-actions Bot
Loading

StanFromIreland commented Jan 8, 2026 •
edited
Loading

encukou Feb 3, 2026 •
edited
Loading