https://github.com/python/cpython/commit/6f439ee069c0e0f9e41865961ceaae8b0544fcbc
commit: 6f439ee069c0e0f9e41865961ceaae8b0544fcbc
branch: main
author: Peter Bierma <[email protected]>
committer: encukou <[email protected]>
date: 2026-10-20T17:44:33Z
summary:
gh-141004: Document `Py_FrozenMain` (#159724)
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 7cfde5cdae6c56..a4a5a53a620b06 100644
--- a/Doc/c-api/interp-lifecycle.rst
+++ b/Doc/c-api/interp-lifecycle.rst
@@ -265,6 +265,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 754b8959b2e5d5..aa57d70df25494 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -32,8 +32,6 @@ PyCFunction_GET_CLASS
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]
