https://github.com/python/cpython/commit/cb6a4bbe5f9248d489d11840ebd90621611da4e5 commit: cb6a4bbe5f9248d489d11840ebd90621611da4e5 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-20T17:59:47Z summary:
[3.14] gh-141004: Document `Py_FrozenMain` (GH-159724) (GH-159923) (cherry picked from commit 6f439ee069c0e0f9e41865961ceaae8b0544fcbc) Co-authored-by: Peter Bierma <[email protected]> files: M Doc/c-api/interp-lifecycle.rst M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/interp-lifecycle.rst b/Doc/c-api/interp-lifecycle.rst index f8c8fdaa05b46f..82d13b7701c9b1 100644 --- a/Doc/c-api/interp-lifecycle.rst +++ b/Doc/c-api/interp-lifecycle.rst @@ -531,6 +531,48 @@ 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 <init-python-config>`, 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. + + .. 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 b875ad066e0089..ddb4ad368a2509 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -55,8 +55,6 @@ PyDescr_COMMON PyDescr_NAME PyDescr_TYPE PyWrapperFlag_KEYWORDS -# cpython/pylifecycle.h -Py_FrozenMain # cpython/objimpl.h PyObject_GET_WEAKREFS_LISTPTR # cpython/pythonrun.h _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
