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

Yashp002 · 2026-01-06T18:14:18Z

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/

StanFromIreland · 2026-01-06T18:42:52Z

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


9c03215 was not backported to 3.12?

encukou · 2026-01-07T07:42:00Z

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.

Yashp002 · 2026-01-07T10:12:44Z

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

encukou · 2026-01-07T12:18:13Z

+   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`.


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.

ZeroIntensity

You need to update ignored_c_api.txt here too.

ZeroIntensity · 2026-01-08T13:19:28Z

+
+
+


Too many blank lines.

ZeroIntensity · 2026-01-08T13:19:54Z

+
+.. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
+
+   Index for the "Python function" kind in ``PyUnstable_ExecutableKinds``.


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

Yashp002 · 2026-01-08T19:18:49Z

test_asyncio.test_sendfile port conflict - unrelated to docs.

StanFromIreland · 2026-01-08T20:42:12Z

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.

Yashp002 · 2026-01-08T21:13:49Z

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

Yashp002 · 2026-01-17T21:18:43Z

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

encukou · 2026-01-19T10:31:41Z

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).

Yashp002 · 2026-01-19T19:15:32Z

@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

encukou · 2026-01-22T10:17:31Z

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.

StanFromIreland · 2026-01-22T11:31:41Z

+   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).


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.

StanFromIreland · 2026-01-22T11:33:03Z

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


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

encukou · 2026-01-30T13:38:52Z

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


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+.

ZeroIntensity

I'm going to merge this for completeness. If we decide to remove this (see #152105), we can remove only the docs for 3.16.

miss-islington-app · 2026-07-18T14:50:44Z

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.
🐍🍒⛏🤖

miss-islington-app · 2026-07-18T14:50:53Z

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

bedevere-app · 2026-07-18T14:50:56Z

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

miss-islington-app · 2026-07-18T14:50:58Z

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

bedevere-app · 2026-07-18T14:53:04Z

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

bedevere-app · 2026-07-18T14:56:28Z

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>

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

ZeroIntensity added 3 commits June 24, 2026 12:15

Address feedback.

2cffd86

Fix stray newline change.

a92546c

Fix stupid lint.

561c580

ZeroIntensity mentioned this pull request Jun 24, 2026

PyUnstable_ExecutableKinds is useless #152105

Open

Fix missing type.

5c56ebb

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Jul 4, 2026

Merge branch 'main' into doc-pyframe-unstable

e5e6937

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jul 18, 2026

ZeroIntensity approved these changes Jul 18, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels 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>


		.. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION

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

Uh oh!

Uh oh!

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!

ZeroIntensity left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Yashp002 commented Jan 6, 2026 •

edited by github-actions Bot

Loading

StanFromIreland commented Jan 8, 2026 •

edited

Loading

encukou Feb 3, 2026 •

edited

Loading