PEP 587: Fix a few minor issues (#1087)

* Fix _init_main=0 example: set config._init_main to 0!
* Document special builds needed by some speficic options like
  show_alloc_count.
* Specify that preconfiguration only requires command line arguments
  for the "Python Configuration" (not for "Isolated Configuration").

Author: vstinner

pep-0587.rst

@@ -101,14 +101,13 @@ and adopted as private APIs for us in the native CPython CLI.
 Python Initialization C API
 ===========================
 
-This PEP proposes to add the following new structures, functions and
-macros.
+This PEP proposes to add the following new structures and functions.
 
 New structures:
 
 * ``PyConfig``
-* ``PyStatus``
 * ``PyPreConfig``
+* ``PyStatus``
 * ``PyWideStringList``
 
 New functions:
@@ -258,12 +257,12 @@ Example using the preinitialization to enable the UTF-8 Mode::
     /* ... use Python API here ... */
     Py_Finalize();
 
-Function to initialize a pre-configuration:
+Function to initialize a preconfiguration:
 
 * ``void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)``
 * ``void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)``
 
-Functions to preinitialization Python:
+Functions to preinitialize Python:
 
 * ``PyStatus Py_PreInitialize(const PyPreConfig *preconfig)``
 * ``PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)``
@@ -272,7 +271,8 @@ Functions to preinitialization Python:
 The caller is responsible to handle exceptions (error or exit) using
 ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
 
-If Python is initialized with command line arguments, the command line
+For `Python Configuration`_ (``PyPreConfig_InitPythonConfig()``),
+if Python is initialized with command line arguments, the command line
 arguments must also be passed to preinitialize Python, since they have
 an effect on the pre-configuration like encodings. For example, the
 ``-X utf8`` command line option enables the UTF-8 Mode.
@@ -363,7 +363,7 @@ Example setting the program name::
 
         /* Set the program name. Implicitly preinitialize Python. */
         status = PyConfig_SetString(&config, &config.program_name,
-                                 L"/path/to/my_program");
+                                    L"/path/to/my_program");
         if (PyStatus_Exception(status)) {
             goto fail;
         }
@@ -451,13 +451,16 @@ exceptions (error or exit) using ``PyStatus_Exception()`` and
   equal or greater to 2, raise a ``BytesWarning`` exception.
 * ``check_hash_pycs_mode`` (``wchar_t*``):
   ``--check-hash-based-pycs`` command line option value (see PEP 552).
+  Valid values: ``always``, ``never`` and ``default``. The default value
+  is ``default``.
 * ``configure_c_stdio`` (``int``):
   If non-zero, configure C standard streams (``stdio``, ``stdout``,
   ``stdout``).  For example, set their mode to ``O_BINARY`` on Windows.
 * ``dev_mode`` (``int``):
   Development mode
 * ``dump_refs`` (``int``):
-  If non-zero, dump all objects which are still alive at exit
+  If non-zero, dump all objects which are still alive at exit.
+  Require a special Python build with ``Py_REF_DEBUG`` macro defined.
 * ``exec_prefix`` (``wchar_t*``):
   ``sys.exec_prefix``.
 * ``executable`` (``wchar_t*``):
@@ -495,17 +498,24 @@ exceptions (error or exit) using ``PyStatus_Exception()`` and
   If non-zero, use ``io.FileIO`` instead of ``WindowsConsoleIO`` for
   ``sys.stdin``, ``sys.stdout`` and ``sys.stderr``.
 * ``malloc_stats`` (``int``):
-  If non-zero, dump memory allocation statistics at exit.
+  If non-zero, dump statistics on ``pymalloc`` memory allocator at exit.
+  The option is ignored if Python is built using ``--without-pymalloc``.
 * ``pythonpath_env`` (``wchar_t*``):
-  Module search paths as a string separated by DELIM (usually ``:``).
+  Module search paths as a string separated by DELIM (usually ``:``
+  character).
   Initialized from ``PYTHONPATH`` environment variable value by default.
 * ``module_search_paths_set`` (``int``),
   ``module_search_paths`` (``PyWideStringList``):
   ``sys.path``. If ``module_search_paths_set`` is equal to 0, the
-  ``module_search_paths`` is replaced by the function computing the
-  `Path Configuration`.
+  ``module_search_paths`` is overridden by the function computing the
+  `Path Configuration`_.
 * ``optimization_level`` (``int``):
-  Compilation optimization level.
+  Compilation optimization level:
+
+  * 0: Peephole optimizer (and ``__debug__`` is set to ``True``)
+  * 1: Remove assertions, set ``__debug__`` to ``False``
+  * 2: Strip docstrings
+
 * ``parse_argv`` (``int``):
   If non-zero, parse ``argv`` the same way the regular Python command
   line arguments, and strip Python arguments from ``argv``: see `Command
@@ -527,15 +537,18 @@ exceptions (error or exit) using ``PyStatus_Exception()`` and
   Quiet mode. For example, don't display the copyright and version
   messages even in interactive mode.
 * ``run_command`` (``wchar_t*``):
-  ``-c COMMAND`` argument.
+  ``python3 -c COMMAND`` argument.
 * ``run_filename`` (``wchar_t*``):
-  ``python3 SCRIPT`` argument.
+  ``python3 FILENAME`` argument.
 * ``run_module`` (``wchar_t*``):
   ``python3 -m MODULE`` argument.
 * ``show_alloc_count`` (``int``):
   Show allocation counts at exit?
+  Need a special Python build with ``COUNT_ALLOCS`` macro defined.
 * ``show_ref_count`` (``int``):
   Show total reference count at exit?
+  Need a debug build of Python (``Py_REF_DEBUG`` macro should be
+  defined).
 * ``site_import`` (``int``):
   Import the ``site`` module at startup?
 * ``skip_source_first_line`` (``int``):
@@ -617,7 +630,7 @@ configuration, and then override some parameters::
 
         /* Override executable computed by PyConfig_Read() */
         status = PyConfig_SetString(&config, &config.executable,
-                                 L"/path/to/my_executable");
+                                    L"/path/to/my_executable");
         if (PyStatus_Exception(status)) {
             goto done;
         }
@@ -736,8 +749,8 @@ equal to 0, ``module_search_paths`` is overriden and
 
 It is possible to completely ignore the function computing the default
 path configuration by setting explicitly all path configuration output
-fields listed above. A string is considered as set even if it's an empty
-string. ``module_search_paths`` is considered as set if
+fields listed above. A string is considered as set even if it is non-empty.
+``module_search_paths`` is considered as set if
 ``module_search_paths_set`` is set to 1. In this case, path
 configuration input fields are ignored as well.
 
@@ -829,7 +842,7 @@ Private provisional API:
 
 No module is imported during the "Core" phase and the ``importlib``
 module is not configured: the `Path Configuration`_ is only applied
-during the "Main" phase. It allows to customize Python in Python to
+during the "Main" phase. It may allow to customize Python in Python to
 override or tune the `Path Configuration`_, maybe install a custom
 sys.meta_path importer or an import hook, etc.
 
@@ -840,7 +853,7 @@ after the Core phase and before the Main phase, which is one of the PEP
 The "Core" phase is not properly defined: what should be and what should
 not be available at this phase is not specified yet. The API is marked
 as private and provisional: the API can be modified or even be removed
-anytime until a proper public API is design.
+anytime until a proper public API is designed.
 
 Example running Python code between "Core" and "Main" initialization
 phases::
@@ -856,7 +869,9 @@ phases::
             Py_ExitStatusException(status);
         }
 
-        /* ... set 'config' configuration ... */
+        config._init_main = 0;
+
+        /* ... customize 'config' configuration ... */
 
         status = Py_InitializeFromConfig(&config);
         PyConfig_Clear(&config);
@@ -1065,7 +1080,7 @@ Option                            ``PyConfig`` field
 ``-b``                            ``bytes_warning++``
 ``-B``                            ``write_bytecode = 0``
 ``-c COMMAND``                    ``run_command = COMMAND``
-``--check-hash-based-pycs=MODE``  ``_check_hash_pycs_mode = MODE``
+``--check-hash-based-pycs=MODE``  ``check_hash_pycs_mode = MODE``
 ``-d``                            ``parser_debug++``
 ``-E``                            ``use_environment = 0``
 ``-i``                            ``inspect++`` and ``interactive++``