From 6fd7a0205d926fe28a9d2dea1c1e6111329e3812 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 30 Jun 2018 21:39:20 +1000 Subject: [PATCH 01/23] bpo-34008: Py_Main and Py_IsInitialized are preinit functions - move the Py_Main documentation from the very high level API section to the initialization and finalization section - make it clear that it encapsulates a full Py_Initialize/Finalize cycle of its own - point out that exactly which settings will be read and applied correctly when called after a separate Py_Initialize or Py_InitalizeEx call is version dependent - be explicit that Py_IsInitialized can be called prior to initialization - actually test that Py_IsInitialized can be called prior to initialization --- Doc/c-api/init.rst | 35 +++++++++++++++++++++++++++++++++++ Doc/c-api/veryhigh.rst | 18 +++--------------- Lib/test/test_embed.py | 8 ++++++++ Programs/_testembed.c | 7 +++++++ 4 files changed, 53 insertions(+), 15 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 694b4669eea897..35647ab4716b66 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -19,6 +19,12 @@ a few functions and the :ref:`global configuration variables The following functions can be safely called before Python is initialized: +* Functions that initialize the interpreter: + + * :c:func:`Py_Initialize` + * :c:func:`Py_InitializeEx` + * :c:func:`Py_Main` + * Configuration functions: * :c:func:`PyImport_AppendInittab` @@ -44,6 +50,7 @@ The following functions can be safely called before Python is initialized: * :c:func:`Py_GetCopyright` * :c:func:`Py_GetPlatform` * :c:func:`Py_GetVersion` + * :c:func:`Py_IsInitialized` * Utilities: @@ -307,6 +314,34 @@ Initializing and finalizing the interpreter disregards the return value. +.. c:function:: int Py_Main(int argc, wchar_t **argv) + + The main program for the standard interpreter, encapsulating a full + ``Py_Initalize()/Py_Finalize()`` cycle, as well as additional behaviour + to implement reading configurations settings from the standard environment. + This is made available for programs which wish to emulate the full Python + CLI, rather than just embedding a Python runtime in a larger application. + + The *argc* and *argv* parameters should be + prepared exactly as those which are passed to a C program's :c:func:`main` + function (converted to wchar_t according to the user's locale). It is + important to note that the argument list may be modified (but the contents of + the strings pointed to by the argument list are not). The return value will + be ``0`` if the interpreter exits normally (i.e., without an exception), + ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter + list does not represent a valid Python command line. + + Note that if an otherwise unhandled :exc:`SystemExit` is raised, this + function will not return ``1``, but exit the process, as long as + ``Py_InspectFlag`` is not set (if ``Py_InspectFlag`` is set it will drop + into interactive Python prompt, at which point a second otherwise unhandled + :exc:`SystemExit` will still exit the process). + + If this function is called after a separate :c:func:`Py_Initialize` or + :c:func:`Py_InitializeEx` call, then exactly which environmental and + command line configuration settings will be respected is version dependent. + + Process-wide parameters ======================= diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index cefe9d44bf45a2..6b5d5ac64b6b8e 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -24,22 +24,10 @@ use different libraries, so care should be taken that :c:type:`FILE\*` parameter are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using. +.. note: -.. c:function:: int Py_Main(int argc, wchar_t **argv) - - The main program for the standard interpreter. This is made available for - programs which embed Python. The *argc* and *argv* parameters should be - prepared exactly as those which are passed to a C program's :c:func:`main` - function (converted to wchar_t according to the user's locale). It is - important to note that the argument list may be modified (but the contents of - the strings pointed to by the argument list are not). The return value will - be ``0`` if the interpreter exits normally (i.e., without an exception), - ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter - list does not represent a valid Python command line. - - Note that if an otherwise unhandled :exc:`SystemExit` is raised, this - function will not return ``1``, but exit the process, as long as - ``Py_InspectFlag`` is not set. + The documentation for :c:func:`Py_Main` that previously appeared in this + section has been moved to :ref:`initialization`. .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py index f3b60433ccc131..3033de232a28b0 100644 --- a/Lib/test/test_embed.py +++ b/Lib/test/test_embed.py @@ -195,6 +195,10 @@ def test_pre_initialization_api(self): """ env = dict(os.environ, PYTHONPATH=os.pathsep.join(sys.path)) out, err = self.run_embedded_interpreter("pre_initialization_api", env=env) + if support.verbose > 1: + print() + print(out) + print(err) if sys.platform == "win32": expected_path = self.test_exe else: @@ -211,6 +215,10 @@ def test_pre_initialization_sys_options(self): env = dict(os.environ, PYTHONPATH=os.pathsep.join(sys.path)) out, err = self.run_embedded_interpreter( "pre_initialization_sys_options", env=env) + if support.verbose > 1: + print() + print(out) + print(err) expected_output = ( "sys.warnoptions: ['once', 'module', 'default']\n" "sys._xoptions: {'not_an_option': '1', 'also_not_an_option': '2'}\n" diff --git a/Programs/_testembed.c b/Programs/_testembed.c index b8827f074b9cce..d54b06982a4325 100644 --- a/Programs/_testembed.c +++ b/Programs/_testembed.c @@ -149,6 +149,13 @@ static int test_pre_initialization_api(void) _Py_EMBED_PREINIT_CHECK("Checking Py_SetProgramName\n"); Py_SetProgramName(program); + _Py_EMBED_PREINIT_CHECK("Checking Py_IsInitialized\n"); + if (Py_IsInitialized()) { + fprintf(stderr, "Fatal error: initialized before initialization!\n"); + return 1; + } + + _Py_EMBED_PREINIT_CHECK("Initializing interpreter\n"); Py_Initialize(); _Py_EMBED_PREINIT_CHECK("Check sys module contents\n"); From 90aea9246c7ec41dcd54dd433996d3b3acf1b663 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 30 Jun 2018 21:49:20 +1000 Subject: [PATCH 02/23] Add news entry --- .../2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst diff --git a/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst b/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst new file mode 100644 index 00000000000000..1e8dc28abd5ea3 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst @@ -0,0 +1,6 @@ +Clearly document that we expect Py_Main to be called instead of +Py_Initialize rather than after it (since Py_Main makes its own call to +Py_Initialize). + +Add Py_IsInitialized to the list of APIs that are safe to call before the +interpreter is initialized. From 670854550a1cfa893d41b2a6752ec8f06b9b0019 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 30 Jun 2018 22:02:04 +1000 Subject: [PATCH 03/23] Fix directive markup --- Doc/c-api/veryhigh.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 6b5d5ac64b6b8e..5446187afe7ba1 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -24,7 +24,7 @@ use different libraries, so care should be taken that :c:type:`FILE\*` parameter are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using. -.. note: +.. _note: The documentation for :c:func:`Py_Main` that previously appeared in this section has been moved to :ref:`initialization`. From c2e12cc4e871260378771967f0bae487cf53eaaf Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 30 Jun 2018 22:27:36 +1000 Subject: [PATCH 04/23] Reword Py_Main docs --- Doc/c-api/init.rst | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 35647ab4716b66..abbeb369f74ef7 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -317,29 +317,39 @@ Initializing and finalizing the interpreter .. c:function:: int Py_Main(int argc, wchar_t **argv) The main program for the standard interpreter, encapsulating a full - ``Py_Initalize()/Py_Finalize()`` cycle, as well as additional behaviour - to implement reading configurations settings from the standard environment. - This is made available for programs which wish to emulate the full Python - CLI, rather than just embedding a Python runtime in a larger application. - - The *argc* and *argv* parameters should be - prepared exactly as those which are passed to a C program's :c:func:`main` - function (converted to wchar_t according to the user's locale). It is - important to note that the argument list may be modified (but the contents of - the strings pointed to by the argument list are not). The return value will - be ``0`` if the interpreter exits normally (i.e., without an exception), - ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter - list does not represent a valid Python command line. + :c:func:`Py_Initialize`/:c:func:`Py_Finalize` cycle, as well as additional + behaviour to implement reading configurations settings from the environment + and command line, and then executing ``__main__`` in accordance with + :ref:`using-on-cmdline`. + + This is made available for programs which wish to support the full CPython + command line interface, rather than just embedding a Python runtime in a + larger application. + + The *argc* and *argv* parameters should be prepared exactly as those which + are passed to a C program's :c:func:`main` function (converted to ``wchar_t`` + :c:func:`Py_DecodeLocale`). It is important to note that the argument list + may be modified (but the contents of the strings pointed to by the argument + list are not). + + The return value will be ``0`` if the interpreter exits normally (i.e., + without an exception), ``1`` if the interpreter exits due to an exception, + or ``2`` if the argument list does not represent a valid Python command + line. Note that if an otherwise unhandled :exc:`SystemExit` is raised, this function will not return ``1``, but exit the process, as long as - ``Py_InspectFlag`` is not set (if ``Py_InspectFlag`` is set it will drop - into interactive Python prompt, at which point a second otherwise unhandled - :exc:`SystemExit` will still exit the process). + ``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will + drop into interactive Python prompt, at which point a second otherwise + unhandled :exc:`SystemExit` will still exit the process, while any other + means of exiting will set the return value as described above. If this function is called after a separate :c:func:`Py_Initialize` or :c:func:`Py_InitializeEx` call, then exactly which environmental and - command line configuration settings will be respected is version dependent. + command line configuration settings will be respected is version dependent + (since it depends on which settings are handled in the now skipped implicit + call to ``Py_Initialize``, and which are handled directly in ``Py_Main`` + itself). Process-wide parameters From eb855e173575864940c0f5dcb10611d08d0ddafc Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Wed, 4 Jul 2018 20:45:42 +1000 Subject: [PATCH 05/23] Replace note with NEWS entry for Py_Main docs move --- Doc/c-api/veryhigh.rst | 5 ----- .../Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst | 2 ++ 2 files changed, 2 insertions(+), 5 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 5446187afe7ba1..853b8acb2cc63a 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -24,11 +24,6 @@ use different libraries, so care should be taken that :c:type:`FILE\*` parameter are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using. -.. _note: - - The documentation for :c:func:`Py_Main` that previously appeared in this - section has been moved to :ref:`initialization`. - .. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename) diff --git a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst new file mode 100644 index 00000000000000..d050b4a366b519 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst @@ -0,0 +1,2 @@ +The Py_Main documentation moved from the Very High Level API section to the +Initializationa and Finalization section. From 68e37d18f80b9cfd936e0f30edfa4ce13b56662d Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Wed, 4 Jul 2018 20:50:05 +1000 Subject: [PATCH 06/23] Further pre-initialization test improvements - also check Py_IsInitialized while the interpreter is initialized and after it is finalized - flush stdout in the embedding tests that run code so it appears in the expected order when running with "-vv" - make "-vv" on the subinterpreter embedding tests less spammy --- Lib/test/test_embed.py | 3 ++- Programs/_testembed.c | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py index 3033de232a28b0..cf4bb7bb75dea4 100644 --- a/Lib/test/test_embed.py +++ b/Lib/test/test_embed.py @@ -96,7 +96,8 @@ def run_repeated_init_and_subinterpreters(self): # Parse the line from the loop. The first line is the main # interpreter and the 3 afterward are subinterpreters. interp = Interp(*match.groups()) - if support.verbose > 1: + if support.verbose > 2: + # 5 lines per pass is super-spammy, so limit that to -vvv print(interp) self.assertTrue(interp.interp) self.assertTrue(interp.tstate) diff --git a/Programs/_testembed.c b/Programs/_testembed.c index d54b06982a4325..edd5bd2a8ffe98 100644 --- a/Programs/_testembed.c +++ b/Programs/_testembed.c @@ -149,21 +149,36 @@ static int test_pre_initialization_api(void) _Py_EMBED_PREINIT_CHECK("Checking Py_SetProgramName\n"); Py_SetProgramName(program); - _Py_EMBED_PREINIT_CHECK("Checking Py_IsInitialized\n"); + _Py_EMBED_PREINIT_CHECK("Checking !Py_IsInitialized pre-initialization\n"); if (Py_IsInitialized()) { fprintf(stderr, "Fatal error: initialized before initialization!\n"); return 1; } - _Py_EMBED_PREINIT_CHECK("Initializing interpreter\n"); Py_Initialize(); + + _Py_EMBED_PREINIT_CHECK("Checking Py_IsInitialized post-initialization\n"); + if (!Py_IsInitialized()) { + fprintf(stderr, "Fatal error: not initialized after initialization!\n"); + return 1; + } + _Py_EMBED_PREINIT_CHECK("Check sys module contents\n"); - PyRun_SimpleString("import sys; " - "print('sys.executable:', sys.executable)"); + PyRun_SimpleString( + "import sys; " + "print('sys.executable:', sys.executable); " + "sys.stdout.flush(); " + ); _Py_EMBED_PREINIT_CHECK("Finalizing interpreter\n"); Py_Finalize(); + _Py_EMBED_PREINIT_CHECK("Checking !Py_IsInitialized post-finalization\n"); + if (Py_IsInitialized()) { + fprintf(stderr, "Fatal error: still initialized after finalization!\n"); + return 1; + } + _Py_EMBED_PREINIT_CHECK("Freeing memory allocated by Py_DecodeLocale\n"); PyMem_RawFree(program); return 0; @@ -209,12 +224,15 @@ static int test_pre_initialization_sys_options(void) _Py_EMBED_PREINIT_CHECK("Initializing interpreter\n"); _testembed_Py_Initialize(); _Py_EMBED_PREINIT_CHECK("Check sys module contents\n"); - PyRun_SimpleString("import sys; " - "print('sys.warnoptions:', sys.warnoptions); " - "print('sys._xoptions:', sys._xoptions); " - "warnings = sys.modules['warnings']; " - "latest_filters = [f[0] for f in warnings.filters[:3]]; " - "print('warnings.filters[:3]:', latest_filters)"); + PyRun_SimpleString( + "import sys; " + "print('sys.warnoptions:', sys.warnoptions); " + "print('sys._xoptions:', sys._xoptions); " + "warnings = sys.modules['warnings']; " + "latest_filters = [f[0] for f in warnings.filters[:3]]; " + "print('warnings.filters[:3]:', latest_filters); " + "sys.stdout.flush(); " + ); _Py_EMBED_PREINIT_CHECK("Finalizing interpreter\n"); Py_Finalize(); From f0c8c9d4d12414933236480163558f45c09a5fb1 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 23 Aug 2019 22:53:01 +1000 Subject: [PATCH 07/23] Adjust wording to be more accurate for 3.6 and 3.7 --- Doc/c-api/init.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index abbeb369f74ef7..c378131e59029c 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -344,12 +344,15 @@ Initializing and finalizing the interpreter unhandled :exc:`SystemExit` will still exit the process, while any other means of exiting will set the return value as described above. - If this function is called after a separate :c:func:`Py_Initialize` or - :c:func:`Py_InitializeEx` call, then exactly which environmental and - command line configuration settings will be respected is version dependent - (since it depends on which settings are handled in the now skipped implicit - call to ``Py_Initialize``, and which are handled directly in ``Py_Main`` - itself). + In normal usage, an embedding application will call this function + *instead* of calling :c:func:`Py_Initialize` or :c:func:`Py_InitializeEx` + directly, and all settings will be applied as described elsewhere in this + documentation. If this function is instead called *after* a preceding + ``Py_Initialize`` or ``Py_InitializeEx`` call, then exactly which + environmental and command line configuration settings will be updated is + version dependent (as it depends on which settings correctly support being + modified after they have already been set once in the first call to + ``Py_Initialize`` or ``Py_InitializeEx``). Process-wide parameters From e652a86d8009ca8bd839b194bf1aa2c5d63885e9 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 23 Aug 2019 22:55:33 +1000 Subject: [PATCH 08/23] Add missing word --- Doc/c-api/init.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index c378131e59029c..f4e710642ab1c9 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -328,9 +328,9 @@ Initializing and finalizing the interpreter The *argc* and *argv* parameters should be prepared exactly as those which are passed to a C program's :c:func:`main` function (converted to ``wchar_t`` - :c:func:`Py_DecodeLocale`). It is important to note that the argument list - may be modified (but the contents of the strings pointed to by the argument - list are not). + with :c:func:`Py_DecodeLocale`). It is important to note that the argument + list may be modified (but the contents of the strings pointed to by the + argument list are not). The return value will be ``0`` if the interpreter exits normally (i.e., without an exception), ``1`` if the interpreter exits due to an exception, @@ -350,8 +350,8 @@ Initializing and finalizing the interpreter documentation. If this function is instead called *after* a preceding ``Py_Initialize`` or ``Py_InitializeEx`` call, then exactly which environmental and command line configuration settings will be updated is - version dependent (as it depends on which settings correctly support being - modified after they have already been set once in the first call to + version dependent (as it depends on which settings correctly support + being modified after they have already been set once in the first call to ``Py_Initialize`` or ``Py_InitializeEx``). From 225bc429f504d15580ca22fbffb35e6638a05957 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 23 Aug 2019 22:56:45 +1000 Subject: [PATCH 09/23] Fix typo --- .../next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst index d050b4a366b519..ba3b5a91cdeb38 100644 --- a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst +++ b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst @@ -1,2 +1,2 @@ The Py_Main documentation moved from the Very High Level API section to the -Initializationa and Finalization section. +Initialization and Finalization section. From 036f6f30aaa9b376ba91a7ddcd377dcf78f05489 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 23 Aug 2019 23:01:09 +1000 Subject: [PATCH 10/23] Update NEWS entry --- .../2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst b/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst index 1e8dc28abd5ea3..714b46bc0c9194 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst @@ -1,6 +1,8 @@ -Clearly document that we expect Py_Main to be called instead of -Py_Initialize rather than after it (since Py_Main makes its own call to -Py_Initialize). +Make it explicit that we expect ``Py_Main`` to typically be called instead +of ``Py_Initialize`` rather than after it (since ``Py_Main`` makes its own +call to ``Py_Initialize``). However, also document that calling both is +supported, but it's version dependent as to exactly which settings +will be applied correctly in that case. -Add Py_IsInitialized to the list of APIs that are safe to call before the -interpreter is initialized. +Also add Py_IsInitialized to the list of APIs that are safe to call before +the interpreter is initialized, and update the embedding tests to cover it. From 8310a1a7e9783a52b2b8cf71b30645f9fed6e7da Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 25 Aug 2019 22:47:16 +1000 Subject: [PATCH 11/23] Tweak wording of Py_Main and Py_BytesMain docs --- Doc/c-api/init.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 645571e7762445..fe620a532e2a88 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -331,9 +331,10 @@ Initializing and finalizing the interpreter The *argc* and *argv* parameters should be prepared exactly as those which are passed to a C program's :c:func:`main` function (converted to ``wchar_t`` - :c:func:`Py_DecodeLocale`). It is important to note that the argument list - may be modified (but the contents of the strings pointed to by the argument - list are not). + :c:func:`Py_DecodeLocale`). It is important to note that the argument list + entries may be modified to point to strings other than those passed in + (however, the contents of the strings pointed to by the argument list are + not modified). The return value will be ``0`` if the interpreter exits normally (i.e., without an exception), ``1`` if the interpreter exits due to an exception, @@ -357,7 +358,9 @@ Initializing and finalizing the interpreter .. c:function:: int Py_BytesMain(int argc, char **argv) - Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings. + Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, + allowing the calling application to delegate the text decoding step to + the CPython runtime. .. versionadded:: 3.8 From f3d9713cbe21fe1f86bf72b890d8a00c9090fe31 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 25 Aug 2019 22:49:32 +1000 Subject: [PATCH 12/23] Tweak presentation order of init functions --- Doc/c-api/init.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index fe620a532e2a88..612d76cd26930a 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -25,6 +25,7 @@ The following functions can be safely called before Python is initialized: * :c:func:`Py_Initialize` * :c:func:`Py_InitializeEx` + * :c:func:`Py_BytesMain` * :c:func:`Py_Main` * Configuration functions: @@ -278,6 +279,12 @@ Initializing and finalizing the interpreter :c:func:`Py_Initialize` is called again. +.. c:function:: void Py_Finalize() + + This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that + disregards the return value. + + .. c:function:: int Py_FinalizeEx() Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of @@ -311,10 +318,13 @@ Initializing and finalizing the interpreter .. versionadded:: 3.6 -.. c:function:: void Py_Finalize() +.. c:function:: int Py_BytesMain(int argc, char **argv) - This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that - disregards the return value. + Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, + allowing the calling application to delegate the text decoding step to + the CPython runtime. + + .. versionadded:: 3.8 .. c:function:: int Py_Main(int argc, wchar_t **argv) @@ -356,15 +366,6 @@ Initializing and finalizing the interpreter itself). -.. c:function:: int Py_BytesMain(int argc, char **argv) - - Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, - allowing the calling application to delegate the text decoding step to - the CPython runtime. - - .. versionadded:: 3.8 - - Process-wide parameters ======================= From e32d4581a430b6fff75abb188683b606c0087b18 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 25 Aug 2019 23:26:10 +1000 Subject: [PATCH 13/23] Further integrate old and new init API docs --- Doc/c-api/init.rst | 81 +++++++++++++++++++++++++++++++-------- Doc/c-api/init_config.rst | 34 ++++++---------- 2 files changed, 77 insertions(+), 38 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 612d76cd26930a..99f91d9e4647fa 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -7,7 +7,10 @@ Initialization, Finalization, and Threads ***************************************** -See also :ref:`Python Initialization Configuration `. +This section covers the traditional global variable based approach to +configuring the CPython runtime. See :ref:`init-config` for an alternate +struct based configuration approach introduced in CPython 3.8. + .. _pre-init-safe: @@ -27,6 +30,7 @@ The following functions can be safely called before Python is initialized: * :c:func:`Py_InitializeEx` * :c:func:`Py_BytesMain` * :c:func:`Py_Main` + * the runtime initialization functions covered in :ref:`init-config` * Configuration functions: @@ -43,6 +47,7 @@ The following functions can be safely called before Python is initialized: * :c:func:`PySys_AddWarnOption` * :c:func:`PySys_AddXOption` * :c:func:`PySys_ResetWarnOptions` + * the configuration functions covered in :ref:`init-config` * Informative functions: @@ -59,6 +64,7 @@ The following functions can be safely called before Python is initialized: * Utilities: * :c:func:`Py_DecodeLocale` + * the status reporting and utility functions covered in :ref:`init-config` * Memory allocators: @@ -69,11 +75,13 @@ The following functions can be safely called before Python is initialized: .. note:: - The following functions **should not be called** before + Despite their apparent similarity to some of the functions listed above, + the following functions **should not be called** before :c:func:`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, - :c:func:`Py_GetProgramName` and :c:func:`PyEval_InitThreads`. + :c:func:`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and + :c:func:`Py_RunMain`. .. _global-conf-vars: @@ -252,24 +260,27 @@ Initializing and finalizing the interpreter this should be called before using any other Python/C API functions; see :ref:`Before Python Initialization ` for the few exceptions. - This initializes - the table of loaded modules (``sys.modules``), and creates the fundamental - modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes - the module search path (``sys.path``). It does not set ``sys.argv``; use - :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time - (without calling :c:func:`Py_FinalizeEx` first). There is no return value; it is a - fatal error if the initialization fails. + This initializes the table of loaded modules (``sys.modules``), and creates + the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It + also initializes the module search path (``sys.path``). It does not set + ``sys.argv``; use :c:func:`PySys_SetArgvEx` for that. This is a no-op when + called for a second time (without calling :c:func:`Py_FinalizeEx` first). + There is no return value; it is a fatal error if the initialization fails. + + See :c:func:`Py_InitializeFromConfig` and the :ref:`init-config` section for + an alternative configuration approach based on passed in C structs rather + than global process state. .. note:: - On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which will - also affect non-Python uses of the console using the C Runtime. + On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, + which will also affect non-Python uses of the console using the C Runtime. .. c:function:: void Py_InitializeEx(int initsigs) This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If - *initsigs* is ``0``, it skips initialization registration of signal handlers, which - might be useful when Python is embedded. + *initsigs* is ``0``, it skips initialization registration of signal handlers, + which may be useful when CPython is embedded as part of a larger application. .. c:function:: int Py_IsInitialized() @@ -354,10 +365,22 @@ Initializing and finalizing the interpreter Note that if an otherwise unhandled :exc:`SystemExit` is raised, this function will not return ``1``, but exit the process, as long as ``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will - drop into interactive Python prompt, at which point a second otherwise + drop into the interactive Python prompt, at which point a second otherwise unhandled :exc:`SystemExit` will still exit the process, while any other means of exiting will set the return value as described above. + In terms of the CPython runtime configuration APIs documented in the + :ref:`runtime configuration ` section (and without accounting + for error handling), ``Py_Main`` is approximately equivalent to:: + + PyConfig config; + PyConfig_InitPythonConfig(&config); + PyConfig_SetArgv(&config, argc, argv); + Py_InitializeFromConfig(&config); + PyConfig_Clear(&config); + + Py_RunMain(); + If this function is called after a separate :c:func:`Py_Initialize` or :c:func:`Py_InitializeEx` call, then exactly which environmental and command line configuration settings will be respected is version dependent @@ -366,6 +389,34 @@ Initializing and finalizing the interpreter itself). +.. c:function:: int Py_RunMain(void) + + Executes the main module in a fully configured CPython runtime. + + Executes the command (:c:member:`PyConfig.run_command`), the script + (:c:member:`PyConfig.run_filename`) or the module + (:c:member:`PyConfig.run_module`) specified on the command line or in the + configuration. If none of these values are set, runs the interactive Python + prompt. + + The return value will be ``0`` if the interpreter exits normally (i.e., + without an exception), or ``1`` if the interpreter exits due to an exception. + + Note that if an otherwise unhandled :exc:`SystemExit` is raised, this + function will not return ``1``, but exit the process, as long as + :c:member:`PyConfig.inspect` is not set. If :c:member:`PyConfig.inspect` is + set, execution will drop into the interactive Python prompt, at which point + a second otherwise unhandled :exc:`SystemExit` will still exit the process, + while any other means of exiting will set the return value as described above. + + Finally, finalizes Python and returns an exit status that can be passed to + the ``exit()`` function. + + See :ref:`Python Configuration ` for an example of a + customized Python that always runs in isolated mode using + :c:func:`Py_RunMain`. + + Process-wide parameters ======================= diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 72bd8c37b435c8..5ad3294c353b89 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -15,7 +15,7 @@ Structures: * :c:type:`PyStatus` * :c:type:`PyWideStringList` -Functions: +Configuration functions: * :c:func:`PyConfig_Clear` * :c:func:`PyConfig_InitIsolatedConfig` @@ -28,6 +28,9 @@ Functions: * :c:func:`PyConfig_SetWideStringList` * :c:func:`PyPreConfig_InitIsolatedConfig` * :c:func:`PyPreConfig_InitPythonConfig` + +Status reporting functions: + * :c:func:`PyStatus_Error` * :c:func:`PyStatus_Exception` * :c:func:`PyStatus_Exit` @@ -35,14 +38,19 @@ Functions: * :c:func:`PyStatus_IsExit` * :c:func:`PyStatus_NoMemory` * :c:func:`PyStatus_Ok` +* :c:func:`Py_ExitStatusException` + +Utility functions: + * :c:func:`PyWideStringList_Append` * :c:func:`PyWideStringList_Insert` -* :c:func:`Py_ExitStatusException` + +Runtime initialization functions: + * :c:func:`Py_InitializeFromConfig` * :c:func:`Py_PreInitialize` * :c:func:`Py_PreInitializeFromArgs` * :c:func:`Py_PreInitializeFromBytesArgs` -* :c:func:`Py_RunMain` The preconfiguration (``PyPreConfig`` type) is stored in ``_PyRuntime.preconfig`` and the configuration (``PyConfig`` type) is stored in @@ -919,26 +927,6 @@ The following configuration files are used by the path configuration: * ``pybuilddir.txt`` (Unix only) -Py_RunMain() ------------- - -.. c:function:: int Py_RunMain(void) - - Execute the command (:c:member:`PyConfig.run_command`), the script - (:c:member:`PyConfig.run_filename`) or the module - (:c:member:`PyConfig.run_module`) specified on the command line or in the - configuration. - - By default and when if :option:`-i` option is used, run the REPL. - - Finally, finalizes Python and returns an exit status that can be passed to - the ``exit()`` function. - -See :ref:`Python Configuration ` for an example of -customized Python always running in isolated mode using -:c:func:`Py_RunMain`. - - Multi-Phase Initialization Private Provisional API -------------------------------------------------- From c6838cafa5e5f0ab45e855248d6a42e52cf7b0f6 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 26 Sep 2024 20:49:06 +1000 Subject: [PATCH 14/23] Fix merge error --- Doc/c-api/init.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 8f46b80baa3bcc..518e34a5a98307 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -369,7 +369,7 @@ Initializing and finalizing the interpreter :c:func:`Py_FinalizeEx` first). There is no return value; it is a fatal error if the initialization fails. - Use the :c:func:`Py_InitializeFromConfig` function to customize the + Use :c:func:`Py_InitializeFromConfig` to customize the :ref:`Python Initialization Configuration `. .. note:: @@ -383,6 +383,9 @@ Initializing and finalizing the interpreter *initsigs* is ``0``, it skips initialization registration of signal handlers, which may be useful when CPython is embedded as part of a larger application. + Use :c:func:`Py_InitializeFromConfig` to customize the + :ref:`Python Initialization Configuration `. + .. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config) @@ -392,9 +395,6 @@ Initializing and finalizing the interpreter interpreter, populating the runtime configuration structure, and querying the returned status structure. - Use the :c:func:`Py_InitializeFromConfig` function to customize the - :ref:`Python Initialization Configuration `. - .. c:function:: int Py_IsInitialized() From 634f1a0f21b01ef52abeca53767e1f2b72224fe3 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 26 Sep 2024 20:55:57 +1000 Subject: [PATCH 15/23] Fix up NEWS entries --- .../C API/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst | 2 ++ .../2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst | 8 -------- .../2018-07-04-20-35-25.bpo-34008.bqecIb.rst | 10 ++++++++-- 3 files changed, 10 insertions(+), 10 deletions(-) create mode 100644 Misc/NEWS.d/next/C API/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst diff --git a/Misc/NEWS.d/next/C API/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst b/Misc/NEWS.d/next/C API/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst new file mode 100644 index 00000000000000..1a01dafc758004 --- /dev/null +++ b/Misc/NEWS.d/next/C API/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst @@ -0,0 +1,2 @@ +Added ``Py_IsInitialized`` to the list of APIs that are safe to call before +the interpreter is initialized, and updated the embedding tests to cover it. diff --git a/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst b/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst deleted file mode 100644 index 714b46bc0c9194..00000000000000 --- a/Misc/NEWS.d/next/Core and Builtins/2018-06-30-21-48-16.bpo-34008.2Wjtm0.rst +++ /dev/null @@ -1,8 +0,0 @@ -Make it explicit that we expect ``Py_Main`` to typically be called instead -of ``Py_Initialize`` rather than after it (since ``Py_Main`` makes its own -call to ``Py_Initialize``). However, also document that calling both is -supported, but it's version dependent as to exactly which settings -will be applied correctly in that case. - -Also add Py_IsInitialized to the list of APIs that are safe to call before -the interpreter is initialized, and update the embedding tests to cover it. diff --git a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst index ba3b5a91cdeb38..a97597c359c398 100644 --- a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst +++ b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst @@ -1,2 +1,8 @@ -The Py_Main documentation moved from the Very High Level API section to the -Initialization and Finalization section. +The ``Py_Main`` documentation moved from the "Very High Level API" section to the +"Initialization and Finalization" section. + +Also make it explicit that we expect ``Py_Main`` to typically be called instead +of ``Py_Initialize`` rather than after it (since ``Py_Main`` makes its own +call to ``Py_Initialize``). However, also document that calling both is +supported, but it's version dependent as to exactly which settings +will be applied correctly in that case. From 2d75186fb0613197fd0df16653cf89a1387761d1 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 26 Sep 2024 20:59:10 +1000 Subject: [PATCH 16/23] Actually reference the init-from-config anchor --- Doc/c-api/init.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 518e34a5a98307..547a91cfdcb7f7 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -389,7 +389,8 @@ Initializing and finalizing the interpreter .. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config) - Initialize Python from *config* configuration. + Initialize Python from *config* configuration, as described in + :ref:`init-from-config`. See the :ref:`init-config` section for details on pre-initializing the interpreter, populating the runtime configuration structure, and querying From 54e53918a03a1e9a9c42a29aa59a002b204b7945 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 26 Sep 2024 21:30:43 +1000 Subject: [PATCH 17/23] Eliminate Py_RunMain docs duplication --- Doc/c-api/init.rst | 35 +++++++++++++++++++++-------------- Doc/c-api/init_config.rst | 20 -------------------- 2 files changed, 21 insertions(+), 34 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 547a91cfdcb7f7..067c24c2cbdffa 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -530,20 +530,27 @@ Initializing and finalizing the interpreter (:c:member:`PyConfig.run_filename`) or the module (:c:member:`PyConfig.run_module`) specified on the command line or in the configuration. If none of these values are set, runs the interactive Python - prompt. - - The return value will be ``0`` if the interpreter exits normally (i.e., - without an exception), or ``1`` if the interpreter exits due to an exception. - - Note that if an otherwise unhandled :exc:`SystemExit` is raised, this - function will not return ``1``, but exit the process, as long as - :c:member:`PyConfig.inspect` is not set. If :c:member:`PyConfig.inspect` is - set, execution will drop into the interactive Python prompt, at which point - a second otherwise unhandled :exc:`SystemExit` will still exit the process, - while any other means of exiting will set the return value as described above. - - Finally, finalizes Python and returns an exit status that can be passed to - the ``exit()`` function. + prompt (REPL) using the ``__main__`` module's global namespace. + + If :c:member:`PyConfig.inspect` is not set (the default), the return value + will be ``0`` if the interpreter exits normally (that is, without raising + an exception), or ``1`` if the interpreter exits due to an exception. If an + otherwise unhandled :exc:`SystemExit` is raised, the function will immediately + exit the process instead of returning ``1``. + + If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option + is used), rather than returning when the interpreter exits, execution will + instead resume in an interactive Python prompt (REPL) using the ``__main__`` + module's global namespace. If the interpreter exited with an exception, it + is immediately raised in the REPL session. The function return value is + then determined by the way the *REPL session* terminates: returning ``0`` + if the session terminates without raising an unhandled exception, exiting + immediately for an unhandled :exc:`SystemExit`, and returning ``1`` for + any other unhandled exception. + + This function always finalizes the Python interpreter regardless of whether + it returns a value or immediately exits the process due to an an unhandled + :exc:`SystemExit` exception. See :ref:`Python Configuration ` for an example of a customized Python that always runs in isolated mode using diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 590fdb3afe6bcd..f99f5723b4d77c 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -1829,26 +1829,6 @@ return ``-1`` on error: } -Py_RunMain() -============ - -.. c:function:: int Py_RunMain(void) - - Execute the command (:c:member:`PyConfig.run_command`), the script - (:c:member:`PyConfig.run_filename`) or the module - (:c:member:`PyConfig.run_module`) specified on the command line or in the - configuration. - - By default and when if :option:`-i` option is used, run the REPL. - - Finally, finalizes Python and returns an exit status that can be passed to - the ``exit()`` function. - -See :ref:`Python Configuration ` for an example of -customized Python always running in isolated mode using -:c:func:`Py_RunMain`. - - Runtime Python configuration API ================================ From 9a6fec583e3a37d73338fbdc111958d60326c495 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Thu, 26 Sep 2024 21:33:30 +1000 Subject: [PATCH 18/23] Fix anchor syntax --- Doc/c-api/init_config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index f99f5723b4d77c..7ef0dafc8bf9f8 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -1351,7 +1351,7 @@ the :option:`-X` command line option. The ``show_alloc_count`` field has been removed. -.._init-from-config: +.. _init-from-config: Initialization with PyConfig ---------------------------- From e8758170e4b5ecc96809d73ba068e35b84d9972f Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Fri, 27 Sep 2024 16:43:32 +1000 Subject: [PATCH 19/23] Replace stale reference to Py_Finalize --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 067c24c2cbdffa..e3848f56f57af4 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -471,7 +471,7 @@ Initializing and finalizing the interpreter .. c:function:: int Py_Main(int argc, wchar_t **argv) The main program for the standard interpreter, encapsulating a full - :c:func:`Py_Initialize`/:c:func:`Py_Finalize` cycle, as well as additional + initialization/finalization cycle, as well as additional behaviour to implement reading configurations settings from the environment and command line, and then executing ``__main__`` in accordance with :ref:`using-on-cmdline`. From e42ebb5f28e387b2bb26f77197664bf0d06ccc86 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Fri, 27 Sep 2024 16:45:15 +1000 Subject: [PATCH 20/23] Fix typo --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index e3848f56f57af4..89363492812413 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -549,7 +549,7 @@ Initializing and finalizing the interpreter any other unhandled exception. This function always finalizes the Python interpreter regardless of whether - it returns a value or immediately exits the process due to an an unhandled + it returns a value or immediately exits the process due to an unhandled :exc:`SystemExit` exception. See :ref:`Python Configuration ` for an example of a From 0a58fcd4d4b8bb410602501a667d96e1393a70f5 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Mon, 7 Oct 2024 22:53:07 +1000 Subject: [PATCH 21/23] Remove trailing whitespace --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 89363492812413..4f2e59b29b675d 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -362,7 +362,7 @@ Initializing and finalizing the interpreter :ref:`Before Python Initialization ` for the few exceptions. This initializes the table of loaded modules (``sys.modules``), and creates - the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. + the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes the module search path (``sys.path``). It does not set ``sys.argv``; use the :ref:`Python Initialization Configuration ` API for that. This is a no-op when called for a second time (without calling From c5bb626de6e0235a95b6beeebbbdf2ad8884603a Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Mon, 7 Oct 2024 23:01:59 +1000 Subject: [PATCH 22/23] Add back Py_Finalize docs (presumably lost in a merge error) --- Doc/c-api/init.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 449cdc2e6ebe37..8e0cf7bb0fc088 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -463,6 +463,13 @@ Initializing and finalizing the interpreter .. versionadded:: 3.6 + +.. c:function:: void Py_Finalize() + + This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that + disregards the return value. + + .. c:function:: int Py_BytesMain(int argc, char **argv) Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, From aad97ee24a76f70fc5d399aff612a2e9c1207bf3 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Tue, 8 Oct 2024 18:08:59 +1000 Subject: [PATCH 23/23] Apply suggestions from code review Co-authored-by: Carol Willing --- .../2018-07-04-20-35-25.bpo-34008.bqecIb.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst index a97597c359c398..a89086af35bfc1 100644 --- a/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst +++ b/Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst @@ -1,8 +1,8 @@ -The ``Py_Main`` documentation moved from the "Very High Level API" section to the +The :c:func:`Py_Main` documentation moved from the "Very High Level API" section to the "Initialization and Finalization" section. Also make it explicit that we expect ``Py_Main`` to typically be called instead of ``Py_Initialize`` rather than after it (since ``Py_Main`` makes its own -call to ``Py_Initialize``). However, also document that calling both is -supported, but it's version dependent as to exactly which settings -will be applied correctly in that case. +call to ``Py_Initialize``). Document that calling both is +supported but is version dependent on which settings +will be applied correctly.