Bug report

Bug description:

There are a few technical constraints on callingPy_Finalize() currently aren't enforced, well-documented, or widely recognized. This is partly due to the relatively small number of embedders and the even smaller number of them that might violate the constraints through the use of threads or subinterpreters.

The constraints are:

• should be called only in the main thread
• should be called only with the main interpreter active
• should be called only using the same thread state used forPy_Initialize()

(That last one is potentially less critical.)

There are several reasons these matter:

• the main thread of the main interpreter has a special role in the runtime's lifecycle
• the main thread of the main interpreter has unique responsibilities that must be synchronized with finalization
• conceptually, runtime lifecycle is an app-level function, and the app is typically driven through the "main" thread

The constraints should be documented, tested, and (possibly) enforced.

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

• gh-120838: Add a Note in the Docs About Expectations for Py_Finalize() #120839
• gh-120838: Add Tests For "Bad" Usage in Runtime Lifecycle Operations #120840
• gh-120838: Disallow Py_Finalize() if Py_RunMain() is Running #120841
• [3.13] gh-120838: Add a Note in the Docs About Expectations for Py_Finalize() (gh-120839) #120852
• [3.12] gh-120838: Add a Note in the Docs About Expectations for Py_Finalize() (gh-120839) #120853
• gh-120838: Add _PyThreadState_WHENCE_FINI #121010
• [3.13] gh-120838: Add _PyThreadState_WHENCE_FINI (gh-121010) #121013
• gh-120838: Make Sure Py_Finalize() Always Runs Against the Main Interpreter #121063