From dbfa39f6d93e344f973ef56aaa0882342cc17080 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 19 Oct 2026 13:25:28 -0400 Subject: [PATCH 1/2] Document Py_FrozenMain(). --- Doc/c-api/interp-lifecycle.rst | 45 ++++++++++++++++++++++++ Tools/check-c-api-docs/ignored_c_api.txt | 2 -- 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/interp-lifecycle.rst b/Doc/c-api/interp-lifecycle.rst index 7cfde5cdae6c56..c562d65f836474 100644 --- a/Doc/c-api/interp-lifecycle.rst +++ b/Doc/c-api/interp-lifecycle.rst @@ -265,6 +265,51 @@ Initializing and finalizing the interpreter first initialized). +.. c:function:: int Py_FrozenMain(int argc, char **argv) + + .. index:: single: freeze utility + + The main program for a "frozen" Python program (an executable that embeds + the interpreter together with the bytecode of the program's modules, as + produced by the :program:`freeze` utility; see :source:`Tools/freeze`). + + This function initializes the interpreter, imports the frozen module named + ``__main__``, and finalizes the interpreter. + The frozen modules must have been registered in + :c:var:`PyImport_FrozenModules` before calling this function; + it is a fatal error if ``__main__`` is not among them. + + *argc* and *argv* are byte strings like the arguments of a C program's + ``main`` function, and are passed to the interpreter with + :c:func:`PyConfig_SetBytesArgv`. + Unlike :c:func:`Py_Main`, the arguments are not parsed as Python command + line options (:c:member:`PyConfig.parse_argv` is ``0``), so all of them + are made available to the program in :data:`sys.argv`. + Apart from that, the interpreter uses the + :ref:`Python Configuration `, so environment variables + such as :envvar:`PYTHONPATH` are honored. + Warnings about the path configuration + (:c:member:`PyConfig.pathconfig_warnings`) are suppressed. + If :envvar:`PYTHONINSPECT` is set and standard input is a terminal, an + interactive prompt is run after ``__main__`` has finished, as with the + :option:`-i` option. + + Return ``0`` if ``__main__`` ran without an unhandled exception, ``1`` + otherwise, and ``120`` if finalizing the interpreter failed (see + :c:func:`Py_FinalizeEx`). + An unhandled :exc:`SystemExit` terminates the process. + If the interpreter cannot be initialized, the process exits via + :c:func:`Py_ExitStatusException`. + + On Windows, this function is not exported by the Python DLL. + The :program:`freeze` utility compiles :file:`Python/frozenmain.c` into the + frozen program instead, together with the Windows-specific hooks that the + function requires. + + .. versionchanged:: 3.10 + This function is no longer part of the :ref:`limited API `. + + .. c:function:: int Py_RunMain(void) Executes the main module in a fully configured CPython runtime. diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index af7b2772ef5e08..0944a80bfbcdd3 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -35,8 +35,6 @@ PyDescr_TYPE PyWrapperFlag_KEYWORDS # cpython/fileobject.h Py_UniversalNewlineFgets -# cpython/pylifecycle.h -Py_FrozenMain # cpython/objimpl.h PyObject_GET_WEAKREFS_LISTPTR # cpython/pythonrun.h From d427d745515caece462b84f683675e2e36a72d08 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 19 Oct 2026 17:35:50 -0400 Subject: [PATCH 2/2] Update Doc/c-api/interp-lifecycle.rst Co-authored-by: Petr Viktorin --- Doc/c-api/interp-lifecycle.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/c-api/interp-lifecycle.rst b/Doc/c-api/interp-lifecycle.rst index c562d65f836474..a4a5a53a620b06 100644 --- a/Doc/c-api/interp-lifecycle.rst +++ b/Doc/c-api/interp-lifecycle.rst @@ -306,9 +306,6 @@ Initializing and finalizing the interpreter frozen program instead, together with the Windows-specific hooks that the function requires. - .. versionchanged:: 3.10 - This function is no longer part of the :ref:`limited API `. - .. c:function:: int Py_RunMain(void)