diff --git a/pep-0587.rst b/pep-0587.rst index b37d35ffa..cb22d8319 100644 --- a/pep-0587.rst +++ b/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++``