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

Doc/c-api/frame.rst

+   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

Doc/c-api/frame.rst

+   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

Doc/c-api/frame.rst

+
+
+


Too many blank lines.

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

Doc/c-api/frame.rst

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

Doc/c-api/frame.rst

+   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

Doc/c-api/frame.rst

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

Doc/c-api/frame.rst

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

Yashp002 · 2026-02-05T18:11:13Z

@encukou could u check if these changes are satisfactory

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

pyframe fix 8

43e9c9f


		.. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION

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

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!

Yashp002 commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Yashp002 commented Jan 6, 2026 •

edited by github-actions bot

Loading

StanFromIreland commented Jan 8, 2026 •

edited

Loading

encukou Feb 3, 2026 •

edited

Loading