bpo-34206: Improve docs and test coverage for pre-init functions

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,44 @@ 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
+   :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, 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
+   (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
 =======================
 

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)

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"

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.

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");