CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 587 – Python Initialization Configuration | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0587/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 587 – Python Initialization Configuration | peps.python.org'> <meta property="og:description" content="Add a new C API to configure the Python Initialization providing finer control on the whole configuration and better error reporting."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0587/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Add a new C API to configure the Python Initialization providing finer control on the whole configuration and better error reporting."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 587</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 587 – Python Initialization Configuration</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Victor Stinner <vstinner at python.org>, Alyssa Coghlan <ncoghlan at gmail.com></dd> <dt class="field-even">BDFL-Delegate:</dt> <dd class="field-even">Thomas Wouters <thomas at python.org></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/">Python-Dev list</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">27-Mar-2019</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.8</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#python-initialization-c-api">Python Initialization C API</a><ul> <li><a class="reference internal" href="#pywidestringlist">PyWideStringList</a></li> <li><a class="reference internal" href="#pystatus">PyStatus</a></li> <li><a class="reference internal" href="#preinitialization-with-pypreconfig">Preinitialization with PyPreConfig</a></li> <li><a class="reference internal" href="#initialization-with-pyconfig">Initialization with PyConfig</a></li> <li><a class="reference internal" href="#isolated-configuration">Isolated Configuration</a></li> <li><a class="reference internal" href="#python-configuration">Python Configuration</a></li> <li><a class="reference internal" href="#path-configuration">Path Configuration</a></li> <li><a class="reference internal" href="#py-bytesmain">Py_BytesMain()</a></li> <li><a class="reference internal" href="#py-runmain">Py_RunMain()</a></li> <li><a class="reference internal" href="#multi-phase-initialization-private-provisional-api">Multi-Phase Initialization Private Provisional API</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#annexes">Annexes</a><ul> <li><a class="reference internal" href="#comparison-of-python-and-isolated-configurations">Comparison of Python and Isolated Configurations</a></li> <li><a class="reference internal" href="#priority-and-rules">Priority and Rules</a></li> <li><a class="reference internal" href="#configuration-files">Configuration Files</a></li> <li><a class="reference internal" href="#global-configuration-variables">Global Configuration Variables</a></li> <li><a class="reference internal" href="#command-line-arguments">Command Line Arguments</a></li> <li><a class="reference internal" href="#x-options">-X Options</a></li> <li><a class="reference internal" href="#environment-variables">Environment Variables</a></li> <li><a class="reference internal" href="#default-python-configuration">Default Python Configuration</a></li> <li><a class="reference internal" href="#default-isolated-configuration">Default Isolated Configuration</a></li> <li><a class="reference internal" href="#python-3-7-api">Python 3.7 API</a></li> </ul> </li> <li><a class="reference internal" href="#python-issues">Python Issues</a></li> <li><a class="reference internal" href="#discussions">Discussions</a></li> <li><a class="reference internal" href="#version-history">Version History</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Add a new C API to configure the Python Initialization providing finer control on the whole configuration and better error reporting. It becomes possible to read the configuration and then override some computed parameters before it is applied. It also becomes possible to completely override how Python computes the module search paths (<code class="docutils literal notranslate">sys.path</code>). The new <a class="reference internal" href="#isolated-configuration">Isolated Configuration</a> provides sane default values to isolate Python from the system. For example, to embed Python into an application. Using the environment are now opt-in options, rather than an opt-out options. For example, environment variables, command line arguments and global configuration variables are ignored by default. Building a customized Python which behaves as the regular Python becomes easier using the new <code class="docutils literal notranslate">Py_RunMain()</code> function. Moreover, using the <a class="reference internal" href="#python-configuration">Python Configuration</a>, <code class="docutils literal notranslate">PyConfig.argv</code> arguments are now parsed the same way the regular Python parses command line arguments, and <code class="docutils literal notranslate">PyConfig.xoptions</code> are handled as <code class="docutils literal notranslate">-X opt</code> command line options. This extracts a subset of the API design from the <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a> development and refactoring work that is now considered sufficiently stable to make public (allowing 3rd party embedding applications access to the same configuration APIs that the native CPython CLI is now using). </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Python is highly configurable but its configuration evolved organically. The initialization configuration is scattered all around the code using different ways to set them: global configuration variables (ex: <code class="docutils literal notranslate">Py_IsolatedFlag</code>), environment variables (ex: <code class="docutils literal notranslate">PYTHONPATH</code>), command line arguments (ex: <code class="docutils literal notranslate">-b</code>), configuration files (ex: <code class="docutils literal notranslate">pyvenv.cfg</code>), function calls (ex: <code class="docutils literal notranslate">Py_SetProgramName()</code>). A straightforward and reliable way to configure Python is needed. Some configuration parameters are not accessible from the C API, or not easily. For example, there is no API to override the default values of <code class="docutils literal notranslate">sys.executable</code>. Some options like <code class="docutils literal notranslate">PYTHONPATH</code> can only be set using an environment variable which has a side effect on Python child processes if not unset properly. Some options also depends on other options: see <a class="reference internal" href="#priority-and-rules">Priority and Rules</a>. Python 3.7 API does not provide a consistent view of the overall configuration. The C API of Python 3.7 Initialization takes <code class="docutils literal notranslate">wchar_t*</code> strings as input whereas the Python filesystem encoding is set during the initialization which can lead to mojibake. Python 3.7 APIs like <code class="docutils literal notranslate">Py_Initialize()</code> aborts the process on memory allocation failure which is not convenient when Python is embedded. Moreover, <code class="docutils literal notranslate">Py_Main()</code> could exit directly the process rather than returning an exit code. Proposed new API reports the error or exit code to the caller which can decide how to handle it. Implementing the <a class="pep reference internal" href="../pep-0540/" title="PEP 540 – Add a new UTF-8 Mode">PEP 540</a> (UTF-8 Mode) and the new <code class="docutils literal notranslate">-X dev</code> correctly was almost impossible in Python 3.6. The code base has been deeply reworked in Python 3.7 and then in Python 3.8 to read the configuration into a structure with no side effect. It becomes possible to clear the configuration (release memory) and read again the configuration if the encoding changed . It is required to implement properly the UTF-8 which changes the encoding using <code class="docutils literal notranslate">-X utf8</code> command line option. Internally, bytes <code class="docutils literal notranslate">argv</code> strings are decoded from the filesystem encoding. The <code class="docutils literal notranslate">-X dev</code> changes the memory allocator (behaves as <code class="docutils literal notranslate">PYTHONMALLOC=debug</code>), whereas it was not possible to change the memory allocation while parsing the command line arguments. The new design of the internal implementation not only allowed to implement properly <code class="docutils literal notranslate">-X utf8</code> and <code class="docutils literal notranslate">-X dev</code>, it also allows to change the Python behavior way more easily, especially for corner cases like that, and ensure that the configuration remains consistent: see <a class="reference internal" href="#priority-and-rules">Priority and Rules</a>. This PEP is a partial implementation of <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a> which is the overall design. New fields can be added later to <code class="docutils literal notranslate">PyConfig</code> structure to finish the implementation of the <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a> (e.g. by adding a new partial initialization API which allows to configure Python using Python objects to finish the full initialization). However, those features are omitted from this PEP as even the native CPython CLI doesn’t work that way - the public API proposal in this PEP is limited to features which have already been implemented and adopted as private APIs for us in the native CPython CLI. </section> <section id="python-initialization-c-api"> <h2><a class="toc-backref" href="#python-initialization-c-api" role="doc-backlink">Python Initialization C API</a></h2> This PEP proposes to add the following new structures and functions. New structures: <ul class="simple"> <li><code class="docutils literal notranslate">PyConfig</code></li> <li><code class="docutils literal notranslate">PyPreConfig</code></li> <li><code class="docutils literal notranslate">PyStatus</code></li> <li><code class="docutils literal notranslate">PyWideStringList</code></li> </ul> New functions: <ul class="simple"> <li><code class="docutils literal notranslate">PyConfig_Clear(config)</code></li> <li><code class="docutils literal notranslate">PyConfig_InitIsolatedConfig()</code></li> <li><code class="docutils literal notranslate">PyConfig_InitPythonConfig()</code></li> <li><code class="docutils literal notranslate">PyConfig_Read(config)</code></li> <li><code class="docutils literal notranslate">PyConfig_SetArgv(config, argc, argv)</code></li> <li><code class="docutils literal notranslate">PyConfig_SetBytesArgv(config, argc, argv)</code></li> <li><code class="docutils literal notranslate">PyConfig_SetBytesString(config, config_str, str)</code></li> <li><code class="docutils literal notranslate">PyConfig_SetString(config, config_str, str)</code></li> <li><code class="docutils literal notranslate">PyPreConfig_InitIsolatedConfig(preconfig)</code></li> <li><code class="docutils literal notranslate">PyPreConfig_InitPythonConfig(preconfig)</code></li> <li><code class="docutils literal notranslate">PyStatus_Error(err_msg)</code></li> <li><code class="docutils literal notranslate">PyStatus_Exception(status)</code></li> <li><code class="docutils literal notranslate">PyStatus_Exit(exitcode)</code></li> <li><code class="docutils literal notranslate">PyStatus_IsError(status)</code></li> <li><code class="docutils literal notranslate">PyStatus_IsExit(status)</code></li> <li><code class="docutils literal notranslate">PyStatus_NoMemory()</code></li> <li><code class="docutils literal notranslate">PyStatus_Ok()</code></li> <li><code class="docutils literal notranslate">PyWideStringList_Append(list, item)</code></li> <li><code class="docutils literal notranslate">PyWideStringList_Insert(list, index, item)</code></li> <li><code class="docutils literal notranslate">Py_BytesMain(argc, argv)</code></li> <li><code class="docutils literal notranslate">Py_ExitStatusException(status)</code></li> <li><code class="docutils literal notranslate">Py_InitializeFromConfig(config)</code></li> <li><code class="docutils literal notranslate">Py_PreInitialize(preconfig)</code></li> <li><code class="docutils literal notranslate">Py_PreInitializeFromArgs(preconfig, argc, argv)</code></li> <li><code class="docutils literal notranslate">Py_PreInitializeFromBytesArgs(preconfig, argc, argv)</code></li> <li><code class="docutils literal notranslate">Py_RunMain()</code></li> </ul> This PEP also adds <code class="docutils literal notranslate">_PyRuntimeState.preconfig</code> (<code class="docutils literal notranslate">PyPreConfig</code> type) and <code class="docutils literal notranslate">PyInterpreterState.config</code> (<code class="docutils literal notranslate">PyConfig</code> type) fields to these internal structures. <code class="docutils literal notranslate">PyInterpreterState.config</code> becomes the new reference configuration, replacing global configuration variables and other private variables. <section id="pywidestringlist"> <h3><a class="toc-backref" href="#pywidestringlist" role="doc-backlink">PyWideStringList</a></h3> <code class="docutils literal notranslate">PyWideStringList</code> is a list of <code class="docutils literal notranslate">wchar_t*</code> strings. <code class="docutils literal notranslate">PyWideStringList</code> structure fields: <ul class="simple"> <li><code class="docutils literal notranslate">length</code> (<code class="docutils literal notranslate">Py_ssize_t</code>)</li> <li><code class="docutils literal notranslate">items</code> (<code class="docutils literal notranslate">wchar_t**</code>)</li> </ul> Methods: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)</code>: Append item to list.</li> <li><code class="docutils literal notranslate">PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)</code>: Insert item into list at index. If index is greater than list length, just append item to list.</li> </ul> If length is non-zero, items must be non-NULL and all strings must be non-NULL. </section> <section id="pystatus"> <h3><a class="toc-backref" href="#pystatus" role="doc-backlink">PyStatus</a></h3> <code class="docutils literal notranslate">PyStatus</code> is a structure to store the status of an initialization function: success, error or exit. For an error, it can store the C function name which created the error. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>PyStatus alloc(void **ptr, size_t size) { *ptr = PyMem_RawMalloc(size); if (*ptr == NULL) { return PyStatus_NoMemory(); } return PyStatus_Ok(); } int main(int argc, char **argv) { void *ptr; PyStatus status = alloc(&ptr, 16); if (PyStatus_Exception(status)) { Py_ExitStatusException(status); } PyMem_Free(ptr); return 0; } </pre></div> </div> <code class="docutils literal notranslate">PyStatus</code> fields: <ul class="simple"> <li><code class="docutils literal notranslate">exitcode</code> (<code class="docutils literal notranslate">int</code>): Argument passed to <code class="docutils literal notranslate">exit()</code>.</li> <li><code class="docutils literal notranslate">err_msg</code> (<code class="docutils literal notranslate">const char*</code>): Error message.</li> <li><code class="docutils literal notranslate">func</code> (<code class="docutils literal notranslate">const char *</code>): Name of the function which created an error, can be <code class="docutils literal notranslate">NULL</code>.</li> <li>private <code class="docutils literal notranslate">_type</code> field: for internal usage only.</li> </ul> Functions to create a status: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus_Ok()</code>: Success.</li> <li><code class="docutils literal notranslate">PyStatus_Error(err_msg)</code>: Initialization error with a message.</li> <li><code class="docutils literal notranslate">PyStatus_NoMemory()</code>: Memory allocation failure (out of memory).</li> <li><code class="docutils literal notranslate">PyStatus_Exit(exitcode)</code>: Exit Python with the specified exit code.</li> </ul> Functions to handle a status: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus_Exception(status)</code>: Is the result an error or an exit? If true, the exception must be handled; by calling <code class="docutils literal notranslate">Py_ExitStatusException(status)</code> for example.</li> <li><code class="docutils literal notranslate">PyStatus_IsError(status)</code>: Is the result an error?</li> <li><code class="docutils literal notranslate">PyStatus_IsExit(status)</code>: Is the result an exit?</li> <li><code class="docutils literal notranslate">Py_ExitStatusException(status)</code>: Call <code class="docutils literal notranslate">exit(exitcode)</code> if status is an exit. Print the error messageand exit with a non-zero exit code if status is an error. Must only be called if <code class="docutils literal notranslate">PyStatus_Exception(status)</code> is true.</li> </ul> <div class="admonition note"> Note Internally, Python uses macros which set <code class="docutils literal notranslate">PyStatus.func</code>, whereas functions to create a status set <code class="docutils literal notranslate">func</code> to <code class="docutils literal notranslate">NULL</code>. </div> </section> <section id="preinitialization-with-pypreconfig"> <h3><a class="toc-backref" href="#preinitialization-with-pypreconfig" role="doc-backlink">Preinitialization with PyPreConfig</a></h3> The <code class="docutils literal notranslate">PyPreConfig</code> structure is used to preinitialize Python: <ul class="simple"> <li>Set the Python memory allocator</li> <li>Configure the LC_CTYPE locale</li> <li>Set the UTF-8 mode</li> </ul> Example using the preinitialization to enable the UTF-8 Mode: <div class="highlight-default notranslate"><div class="highlight"><pre>PyStatus status; PyPreConfig preconfig; PyPreConfig_InitPythonConfig(&preconfig); preconfig.utf8_mode = 1; status = Py_PreInitialize(&preconfig); if (PyStatus_Exception(status)) { Py_ExitStatusException(status); } /* at this point, Python will speak UTF-8 */ Py_Initialize(); /* ... use Python API here ... */ Py_Finalize(); </pre></div> </div> Function to initialize a preconfiguration: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)</code></li> <li><code class="docutils literal notranslate">PyStatus PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)</code></li> </ul> Functions to preinitialize Python: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus Py_PreInitialize(const PyPreConfig *preconfig)</code></li> <li><code class="docutils literal notranslate">PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)</code></li> <li><code class="docutils literal notranslate">PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)</code></li> </ul> The caller is responsible to handle exceptions (error or exit) using <code class="docutils literal notranslate">PyStatus_Exception()</code> and <code class="docutils literal notranslate">Py_ExitStatusException()</code>. For <a class="reference internal" href="#python-configuration">Python Configuration</a> (<code class="docutils literal notranslate">PyPreConfig_InitPythonConfig()</code>), 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 <code class="docutils literal notranslate">-X utf8</code> command line option enables the UTF-8 Mode. <code class="docutils literal notranslate">PyPreConfig</code> fields: <ul class="simple"> <li><code class="docutils literal notranslate">allocator</code> (<code class="docutils literal notranslate">int</code>): Name of the memory allocator (ex: <code class="docutils literal notranslate">PYMEM_ALLOCATOR_MALLOC</code>). Valid values:<ul> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_NOT_SET</code> (<code class="docutils literal notranslate">0</code>): don’t change memory allocators (use defaults)</li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_DEFAULT</code> (<code class="docutils literal notranslate">1</code>): default memory allocators</li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_DEBUG</code> (<code class="docutils literal notranslate">2</code>): default memory allocators with debug hooks</li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_MALLOC</code> (<code class="docutils literal notranslate">3</code>): force usage of <code class="docutils literal notranslate">malloc()</code></li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_MALLOC_DEBUG</code> (<code class="docutils literal notranslate">4</code>): force usage of <code class="docutils literal notranslate">malloc()</code> with debug hooks</li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_PYMALLOC</code> (<code class="docutils literal notranslate">5</code>): Python “pymalloc” allocator</li> <li><code class="docutils literal notranslate">PYMEM_ALLOCATOR_PYMALLOC_DEBUG</code> (<code class="docutils literal notranslate">6</code>): Python “pymalloc” allocator with debug hooks</li> <li>Note: <code class="docutils literal notranslate">PYMEM_ALLOCATOR_PYMALLOC</code> and <code class="docutils literal notranslate">PYMEM_ALLOCATOR_PYMALLOC_DEBUG</code> are not supported if Python is configured using <code class="docutils literal notranslate">--without-pymalloc</code></li> </ul> </li> <li><code class="docutils literal notranslate">configure_locale</code> (<code class="docutils literal notranslate">int</code>): Set the LC_CTYPE locale to the user preferred locale? If equals to 0, set <code class="docutils literal notranslate">coerce_c_locale</code> and <code class="docutils literal notranslate">coerce_c_locale_warn</code> to 0.</li> <li><code class="docutils literal notranslate">coerce_c_locale</code> (<code class="docutils literal notranslate">int</code>): If equals to 2, coerce the C locale; if equals to 1, read the LC_CTYPE locale to decide if it should be coerced.</li> <li><code class="docutils literal notranslate">coerce_c_locale_warn</code> (<code class="docutils literal notranslate">int</code>): If non-zero, emit a warning if the C locale is coerced.</li> <li><code class="docutils literal notranslate">dev_mode</code> (<code class="docutils literal notranslate">int</code>): See <code class="docutils literal notranslate">PyConfig.dev_mode</code>.</li> <li><code class="docutils literal notranslate">isolated</code> (<code class="docutils literal notranslate">int</code>): See <code class="docutils literal notranslate">PyConfig.isolated</code>.</li> <li><code class="docutils literal notranslate">legacy_windows_fs_encoding</code> (<code class="docutils literal notranslate">int</code>, Windows only): If non-zero, disable UTF-8 Mode, set the Python filesystem encoding to <code class="docutils literal notranslate">mbcs</code>, set the filesystem error handler to <code class="docutils literal notranslate">replace</code>.</li> <li><code class="docutils literal notranslate">parse_argv</code> (<code class="docutils literal notranslate">int</code>): If non-zero, <code class="docutils literal notranslate">Py_PreInitializeFromArgs()</code> and <code class="docutils literal notranslate">Py_PreInitializeFromBytesArgs()</code> parse their <code class="docutils literal notranslate">argv</code> argument the same way the regular Python parses command line arguments: see <a class="reference internal" href="#command-line-arguments">Command Line Arguments</a>.</li> <li><code class="docutils literal notranslate">use_environment</code> (<code class="docutils literal notranslate">int</code>): See <code class="docutils literal notranslate">PyConfig.use_environment</code>.</li> <li><code class="docutils literal notranslate">utf8_mode</code> (<code class="docutils literal notranslate">int</code>): If non-zero, enable the UTF-8 mode.</li> </ul> The <code class="docutils literal notranslate">legacy_windows_fs_encoding</code> field is only available on Windows. <code class="docutils literal notranslate">#ifdef MS_WINDOWS</code> macro can be used for Windows specific code. <code class="docutils literal notranslate">PyPreConfig</code> private fields, for internal use only: <ul class="simple"> <li><code class="docutils literal notranslate">_config_init</code> (<code class="docutils literal notranslate">int</code>): Function used to initialize <code class="docutils literal notranslate">PyConfig</code>, used for preinitialization.</li> </ul> <code class="docutils literal notranslate">PyMem_SetAllocator()</code> can be called after <code class="docutils literal notranslate">Py_PreInitialize()</code> and before <code class="docutils literal notranslate">Py_InitializeFromConfig()</code> to install a custom memory allocator. It can be called before <code class="docutils literal notranslate">Py_PreInitialize()</code> if <code class="docutils literal notranslate">allocator</code> is set to <code class="docutils literal notranslate">PYMEM_ALLOCATOR_NOT_SET</code> (default value). Python memory allocation functions like <code class="docutils literal notranslate">PyMem_RawMalloc()</code> must not be used before Python preinitialization, whereas calling directly <code class="docutils literal notranslate">malloc()</code> and <code class="docutils literal notranslate">free()</code> is always safe. <code class="docutils literal notranslate">Py_DecodeLocale()</code> must not be called before the preinitialization. </section> <section id="initialization-with-pyconfig"> <h3><a class="toc-backref" href="#initialization-with-pyconfig" role="doc-backlink">Initialization with PyConfig</a></h3> The <code class="docutils literal notranslate">PyConfig</code> structure contains most parameters to configure Python. Example setting the program name: <div class="highlight-default notranslate"><div class="highlight"><pre>void init_python(void) { PyStatus status; PyConfig config; PyConfig_InitPythonConfig(&config); /* Set the program name. Implicitly preinitialize Python. */ status = PyConfig_SetString(&config, &config.program_name, L"/path/to/my_program"); if (PyStatus_Exception(status)) { goto fail; } status = Py_InitializeFromConfig(&config); if (PyStatus_Exception(status)) { goto fail; } PyConfig_Clear(&config); return; fail: PyConfig_Clear(&config); Py_ExitStatusException(status); } </pre></div> </div> <code class="docutils literal notranslate">PyConfig</code> methods: <ul class="simple"> <li><code class="docutils literal notranslate">void PyConfig_InitPythonConfig(PyConfig *config)</code> Initialize configuration with <a class="reference internal" href="#python-configuration">Python Configuration</a>.</li> <li><code class="docutils literal notranslate">void PyConfig_InitIsolatedConfig(PyConfig *config)</code>: Initialize configuration with <a class="reference internal" href="#isolated-configuration">Isolated Configuration</a>.</li> <li><code class="docutils literal notranslate">PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)</code>: Copy the wide character string str into <code class="docutils literal notranslate">*config_str</code>. Preinitialize Python if needed.</li> <li><code class="docutils literal notranslate">PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t * const *config_str, const char *str)</code>: Decode str using <code class="docutils literal notranslate">Py_DecodeLocale()</code> and set the result into <code class="docutils literal notranslate">*config_str</code>. Preinitialize Python if needed.</li> <li><code class="docutils literal notranslate">PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)</code>: Set command line arguments from wide character strings. Preinitialize Python if needed.</li> <li><code class="docutils literal notranslate">PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)</code>: Set command line arguments: decode bytes using <code class="docutils literal notranslate">Py_DecodeLocale()</code>. Preinitialize Python if needed.</li> <li><code class="docutils literal notranslate">PyStatus PyConfig_Read(PyConfig *config)</code>: Read all Python configuration. Fields which are already initialized are left unchanged. Preinitialize Python if needed.</li> <li><code class="docutils literal notranslate">void PyConfig_Clear(PyConfig *config)</code>: Release configuration memory.</li> </ul> Most <code class="docutils literal notranslate">PyConfig</code> methods preinitialize Python if needed. In that case, the Python preinitialization configuration in based on the <code class="docutils literal notranslate">PyConfig</code>. If configuration fields which are in common with <code class="docutils literal notranslate">PyPreConfig</code> are tuned, they must be set before calling a <code class="docutils literal notranslate">PyConfig</code> method: <ul class="simple"> <li><code class="docutils literal notranslate">dev_mode</code></li> <li><code class="docutils literal notranslate">isolated</code></li> <li><code class="docutils literal notranslate">parse_argv</code></li> <li><code class="docutils literal notranslate">use_environment</code></li> </ul> Moreover, if <code class="docutils literal notranslate">PyConfig_SetArgv()</code> or <code class="docutils literal notranslate">PyConfig_SetBytesArgv()</code> is used, this method must be called first, before other methods, since the preinitialization configuration depends on command line arguments (if <code class="docutils literal notranslate">parse_argv</code> is non-zero). Functions to initialize Python: <ul class="simple"> <li><code class="docutils literal notranslate">PyStatus Py_InitializeFromConfig(const PyConfig *config)</code>: Initialize Python from config configuration.</li> </ul> The caller of these methods and functions is responsible to handle exceptions (error or exit) using <code class="docutils literal notranslate">PyStatus_Exception()</code> and <code class="docutils literal notranslate">Py_ExitStatusException()</code>. <code class="docutils literal notranslate">PyConfig</code> fields: <ul class="simple"> <li><code class="docutils literal notranslate">argv</code> (<code class="docutils literal notranslate">PyWideStringList</code>): Command line arguments, <code class="docutils literal notranslate">sys.argv</code>. See <code class="docutils literal notranslate">parse_argv</code> to parse <code class="docutils literal notranslate">argv</code> the same way the regular Python parses Python command line arguments. If <code class="docutils literal notranslate">argv</code> is empty, an empty string is added to ensure that <code class="docutils literal notranslate">sys.argv</code> always exists and is never empty.</li> <li><code class="docutils literal notranslate">base_exec_prefix</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">sys.base_exec_prefix</code>.</li> <li><code class="docutils literal notranslate">base_prefix</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">sys.base_prefix</code>.</li> <li><code class="docutils literal notranslate">buffered_stdio</code> (<code class="docutils literal notranslate">int</code>): If equals to 0, enable unbuffered mode, making the stdout and stderr streams unbuffered.</li> <li><code class="docutils literal notranslate">bytes_warning</code> (<code class="docutils literal notranslate">int</code>): If equals to 1, issue a warning when comparing <code class="docutils literal notranslate">bytes</code> or <code class="docutils literal notranslate">bytearray</code> with <code class="docutils literal notranslate">str</code>, or comparing <code class="docutils literal notranslate">bytes</code> with <code class="docutils literal notranslate">int</code>. If equal or greater to 2, raise a <code class="docutils literal notranslate">BytesWarning</code> exception.</li> <li><code class="docutils literal notranslate">check_hash_pycs_mode</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">--check-hash-based-pycs</code> command line option value (see <a class="pep reference internal" href="../pep-0552/" title="PEP 552 – Deterministic pycs">PEP 552</a>). Valid values: <code class="docutils literal notranslate">always</code>, <code class="docutils literal notranslate">never</code> and <code class="docutils literal notranslate">default</code>. The default value is <code class="docutils literal notranslate">default</code>.</li> <li><code class="docutils literal notranslate">configure_c_stdio</code> (<code class="docutils literal notranslate">int</code>): If non-zero, configure C standard streams (<code class="docutils literal notranslate">stdio</code>, <code class="docutils literal notranslate">stdout</code>, <code class="docutils literal notranslate">stdout</code>). For example, set their mode to <code class="docutils literal notranslate">O_BINARY</code> on Windows.</li> <li><code class="docutils literal notranslate">dev_mode</code> (<code class="docutils literal notranslate">int</code>): Development mode</li> <li><code class="docutils literal notranslate">dump_refs</code> (<code class="docutils literal notranslate">int</code>): If non-zero, dump all objects which are still alive at exit. Require a special Python build with <code class="docutils literal notranslate">Py_REF_DEBUG</code> macro defined.</li> <li><code class="docutils literal notranslate">exec_prefix</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">sys.exec_prefix</code>.</li> <li><code class="docutils literal notranslate">executable</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">sys.executable</code>.</li> <li><code class="docutils literal notranslate">faulthandler</code> (<code class="docutils literal notranslate">int</code>): If non-zero, call <code class="docutils literal notranslate">faulthandler.enable()</code>.</li> <li><code class="docutils literal notranslate">filesystem_encoding</code> (<code class="docutils literal notranslate">wchar_t*</code>): Filesystem encoding, <code class="docutils literal notranslate">sys.getfilesystemencoding()</code>.</li> <li><code class="docutils literal notranslate">filesystem_errors</code> (<code class="docutils literal notranslate">wchar_t*</code>): Filesystem encoding errors, <code class="docutils literal notranslate">sys.getfilesystemencodeerrors()</code>.</li> <li><code class="docutils literal notranslate">use_hash_seed</code> (<code class="docutils literal notranslate">int</code>), <code class="docutils literal notranslate">hash_seed</code> (<code class="docutils literal notranslate">unsigned long</code>): Randomized hash function seed.</li> <li><code class="docutils literal notranslate">home</code> (<code class="docutils literal notranslate">wchar_t*</code>): Python home directory.</li> <li><code class="docutils literal notranslate">import_time</code> (<code class="docutils literal notranslate">int</code>): If non-zero, profile import time.</li> <li><code class="docutils literal notranslate">inspect</code> (<code class="docutils literal notranslate">int</code>): Enter interactive mode after executing a script or a command.</li> <li><code class="docutils literal notranslate">install_signal_handlers</code> (<code class="docutils literal notranslate">int</code>): Install signal handlers?</li> <li><code class="docutils literal notranslate">interactive</code> (<code class="docutils literal notranslate">int</code>): Interactive mode.</li> <li><code class="docutils literal notranslate">isolated</code> (<code class="docutils literal notranslate">int</code>): If greater than 0, enable isolated mode:<ul> <li><code class="docutils literal notranslate">sys.path</code> contains neither the script’s directory (computed from <code class="docutils literal notranslate">argv[0]</code> or the current directory) nor the user’s site-packages directory.</li> <li>Python REPL doesn’t import <code class="docutils literal notranslate">readline</code> nor enable default readline configuration on interactive prompts.</li> <li>Set <code class="docutils literal notranslate">use_environment</code> and <code class="docutils literal notranslate">user_site_directory</code> to 0.</li> </ul> </li> <li><code class="docutils literal notranslate">legacy_windows_stdio</code> (<code class="docutils literal notranslate">int</code>, Windows only): If non-zero, use <code class="docutils literal notranslate">io.FileIO</code> instead of <code class="docutils literal notranslate">WindowsConsoleIO</code> for <code class="docutils literal notranslate">sys.stdin</code>, <code class="docutils literal notranslate">sys.stdout</code> and <code class="docutils literal notranslate">sys.stderr</code>.</li> <li><code class="docutils literal notranslate">malloc_stats</code> (<code class="docutils literal notranslate">int</code>): If non-zero, dump statistics on <code class="docutils literal notranslate">pymalloc</code> memory allocator at exit. The option is ignored if Python is built using <code class="docutils literal notranslate">--without-pymalloc</code>.</li> <li><code class="docutils literal notranslate">pythonpath_env</code> (<code class="docutils literal notranslate">wchar_t*</code>): Module search paths as a string separated by DELIM (usually <code class="docutils literal notranslate">:</code> character). Initialized from <code class="docutils literal notranslate">PYTHONPATH</code> environment variable value by default.</li> <li><code class="docutils literal notranslate">module_search_paths_set</code> (<code class="docutils literal notranslate">int</code>), <code class="docutils literal notranslate">module_search_paths</code> (<code class="docutils literal notranslate">PyWideStringList</code>): <code class="docutils literal notranslate">sys.path</code>. If <code class="docutils literal notranslate">module_search_paths_set</code> is equal to 0, the <code class="docutils literal notranslate">module_search_paths</code> is overridden by the function computing the <a class="reference internal" href="#path-configuration">Path Configuration</a>.</li> <li><code class="docutils literal notranslate">optimization_level</code> (<code class="docutils literal notranslate">int</code>): Compilation optimization level:<ul> <li>0: Peephole optimizer (and <code class="docutils literal notranslate">__debug__</code> is set to <code class="docutils literal notranslate">True</code>)</li> <li>1: Remove assertions, set <code class="docutils literal notranslate">__debug__</code> to <code class="docutils literal notranslate">False</code></li> <li>2: Strip docstrings</li> </ul> </li> <li><code class="docutils literal notranslate">parse_argv</code> (<code class="docutils literal notranslate">int</code>): If non-zero, parse <code class="docutils literal notranslate">argv</code> the same way the regular Python command line arguments, and strip Python arguments from <code class="docutils literal notranslate">argv</code>: see <a class="reference internal" href="#command-line-arguments">Command Line Arguments</a>.</li> <li><code class="docutils literal notranslate">parser_debug</code> (<code class="docutils literal notranslate">int</code>): If non-zero, turn on parser debugging output (for expert only, depending on compilation options).</li> <li><code class="docutils literal notranslate">pathconfig_warnings</code> (<code class="docutils literal notranslate">int</code>): If equal to 0, suppress warnings when computing the path configuration (Unix only, Windows does not log any warning). Otherwise, warnings are written into stderr.</li> <li><code class="docutils literal notranslate">prefix</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">sys.prefix</code>.</li> <li><code class="docutils literal notranslate">program_name</code> (<code class="docutils literal notranslate">wchar_t*</code>): Program name.</li> <li><code class="docutils literal notranslate">pycache_prefix</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">.pyc</code> cache prefix.</li> <li><code class="docutils literal notranslate">quiet</code> (<code class="docutils literal notranslate">int</code>): Quiet mode. For example, don’t display the copyright and version messages even in interactive mode.</li> <li><code class="docutils literal notranslate">run_command</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">python3 -c COMMAND</code> argument.</li> <li><code class="docutils literal notranslate">run_filename</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">python3 FILENAME</code> argument.</li> <li><code class="docutils literal notranslate">run_module</code> (<code class="docutils literal notranslate">wchar_t*</code>): <code class="docutils literal notranslate">python3 -m MODULE</code> argument.</li> <li><code class="docutils literal notranslate">show_alloc_count</code> (<code class="docutils literal notranslate">int</code>): Show allocation counts at exit? Need a special Python build with <code class="docutils literal notranslate">COUNT_ALLOCS</code> macro defined.</li> <li><code class="docutils literal notranslate">show_ref_count</code> (<code class="docutils literal notranslate">int</code>): Show total reference count at exit? Need a debug build of Python (<code class="docutils literal notranslate">Py_REF_DEBUG</code> macro should be defined).</li> <li><code class="docutils literal notranslate">site_import</code> (<code class="docutils literal notranslate">int</code>): Import the <code class="docutils literal notranslate">site</code> module at startup?</li> <li><code class="docutils literal notranslate">skip_source_first_line</code> (<code class="docutils literal notranslate">int</code>): Skip the first line of the source?</li> <li><code class="docutils literal notranslate">stdio_encoding</code> (<code class="docutils literal notranslate">wchar_t*</code>), <code class="docutils literal notranslate">stdio_errors</code> (<code class="docutils literal notranslate">wchar_t*</code>): Encoding and encoding errors of <code class="docutils literal notranslate">sys.stdin</code>, <code class="docutils literal notranslate">sys.stdout</code> and <code class="docutils literal notranslate">sys.stderr</code>.</li> <li><code class="docutils literal notranslate">tracemalloc</code> (<code class="docutils literal notranslate">int</code>): If non-zero, call <code class="docutils literal notranslate">tracemalloc.start(value)</code>.</li> <li><code class="docutils literal notranslate">user_site_directory</code> (<code class="docutils literal notranslate">int</code>): If non-zero, add user site directory to <code class="docutils literal notranslate">sys.path</code>.</li> <li><code class="docutils literal notranslate">verbose</code> (<code class="docutils literal notranslate">int</code>): If non-zero, enable verbose mode.</li> <li><code class="docutils literal notranslate">warnoptions</code> (<code class="docutils literal notranslate">PyWideStringList</code>): Options of the <code class="docutils literal notranslate">warnings</code> module to build warnings filters.</li> <li><code class="docutils literal notranslate">write_bytecode</code> (<code class="docutils literal notranslate">int</code>): If non-zero, write <code class="docutils literal notranslate">.pyc</code> files.</li> <li><code class="docutils literal notranslate">xoptions</code> (<code class="docutils literal notranslate">PyWideStringList</code>): <code class="docutils literal notranslate">sys._xoptions</code>.</li> </ul> The <code class="docutils literal notranslate">legacy_windows_stdio</code> field is only available on Windows. <code class="docutils literal notranslate">#ifdef MS_WINDOWS</code> macro can be used for Windows specific code. If <code class="docutils literal notranslate">parse_argv</code> is non-zero, <code class="docutils literal notranslate">argv</code> arguments are parsed the same way the regular Python parses command line arguments, and Python arguments are stripped from <code class="docutils literal notranslate">argv</code>: see <a class="reference internal" href="#command-line-arguments">Command Line Arguments</a>. The <code class="docutils literal notranslate">xoptions</code> options are parsed to set other options: see <a class="reference internal" href="#x-options">-X Options</a>. <code class="docutils literal notranslate">PyConfig</code> private fields, for internal use only: <ul class="simple"> <li><code class="docutils literal notranslate">_config_init</code> (<code class="docutils literal notranslate">int</code>): Function used to initialize <code class="docutils literal notranslate">PyConfig</code>, used for preinitialization.</li> <li><code class="docutils literal notranslate">_install_importlib</code> (<code class="docutils literal notranslate">int</code>): Install importlib?</li> <li><code class="docutils literal notranslate">_init_main</code> (<code class="docutils literal notranslate">int</code>): If equal to 0, stop Python initialization before the “main” phase (see <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a>).</li> </ul> More complete example modifying the default configuration, read the configuration, and then override some parameters: <div class="highlight-default notranslate"><div class="highlight"><pre>PyStatus init_python(const char *program_name) { PyStatus status; PyConfig config; PyConfig_InitPythonConfig(&config); /* Set the program name before reading the configuration (decode byte string from the locale encoding). Implicitly preinitialize Python. */ status = PyConfig_SetBytesString(&config, &config.program_name, program_name); if (PyStatus_Exception(status)) { goto done; } /* Read all configuration at once */ status = PyConfig_Read(&config); if (PyStatus_Exception(status)) { goto done; } /* Append our custom search path to sys.path */ status = PyWideStringList_Append(&config.module_search_paths, L"/path/to/more/modules"); if (PyStatus_Exception(status)) { goto done; } /* Override executable computed by PyConfig_Read() */ status = PyConfig_SetString(&config, &config.executable, L"/path/to/my_executable"); if (PyStatus_Exception(status)) { goto done; } status = Py_InitializeFromConfig(&config); done: PyConfig_Clear(&config); return status; } </pre></div> </div> <div class="admonition note"> Note <code class="docutils literal notranslate">PyImport_FrozenModules</code>, <code class="docutils literal notranslate">PyImport_AppendInittab()</code> and <code class="docutils literal notranslate">PyImport_ExtendInittab()</code> functions are still relevant and continue to work as previously. They should be set or called after Python preinitialization and before the Python initialization. </div> </section> <section id="isolated-configuration"> <h3><a class="toc-backref" href="#isolated-configuration" role="doc-backlink">Isolated Configuration</a></h3> <code class="docutils literal notranslate">PyPreConfig_InitIsolatedConfig()</code> and <code class="docutils literal notranslate">PyConfig_InitIsolatedConfig()</code> functions create a configuration to isolate Python from the system. For example, to embed Python into an application. This configuration ignores global configuration variables, environments variables and command line arguments (<code class="docutils literal notranslate">argv</code> is not parsed). The C standard streams (ex: <code class="docutils literal notranslate">stdout</code>) and the LC_CTYPE locale are left unchanged by default. Configuration files are still used with this configuration. Set the <a class="reference internal" href="#path-configuration">Path Configuration</a> (“output fields”) to ignore these configuration files and avoid the function computing the default path configuration. </section> <section id="python-configuration"> <h3><a class="toc-backref" href="#python-configuration" role="doc-backlink">Python Configuration</a></h3> <code class="docutils literal notranslate">PyPreConfig_InitPythonConfig()</code> and <code class="docutils literal notranslate">PyConfig_InitPythonConfig()</code> functions create a configuration to build a customized Python which behaves as the regular Python. Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored. This function enables C locale coercion (<a class="pep reference internal" href="../pep-0538/" title="PEP 538 – Coercing the legacy C locale to a UTF-8 based locale">PEP 538</a>) and UTF-8 Mode (PEP 540) depending on the LC_CTYPE locale, <code class="docutils literal notranslate">PYTHONUTF8</code> and <code class="docutils literal notranslate">PYTHONCOERCECLOCALE</code> environment variables. Example of customized Python always running in isolated mode: <div class="highlight-default notranslate"><div class="highlight"><pre>int main(int argc, char **argv) { PyStatus status; PyConfig config; PyConfig_InitPythonConfig(&config); config.isolated = 1; /* Decode command line arguments. Implicitly preinitialize Python (in isolated mode). */ status = PyConfig_SetBytesArgv(&config, argc, argv); if (PyStatus_Exception(status)) { goto fail; } status = Py_InitializeFromConfig(&config); if (PyStatus_Exception(status)) { goto fail; } PyConfig_Clear(&config); return Py_RunMain(); fail: PyConfig_Clear(&config); if (PyStatus_IsExit(status)) { return status.exitcode; } /* Display the error message and exit the process with non-zero exit code */ Py_ExitStatusException(status); } </pre></div> </div> This example is a basic implementation of the “System Python Executable” discussed in <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a>. </section> <section id="path-configuration"> <h3><a class="toc-backref" href="#path-configuration" role="doc-backlink">Path Configuration</a></h3> <code class="docutils literal notranslate">PyConfig</code> contains multiple fields for the path configuration: <ul class="simple"> <li>Path configuration input fields:<ul> <li><code class="docutils literal notranslate">home</code></li> <li><code class="docutils literal notranslate">pythonpath_env</code></li> <li><code class="docutils literal notranslate">pathconfig_warnings</code></li> </ul> </li> <li>Path configuration output fields:<ul> <li><code class="docutils literal notranslate">exec_prefix</code></li> <li><code class="docutils literal notranslate">executable</code></li> <li><code class="docutils literal notranslate">prefix</code></li> <li><code class="docutils literal notranslate">module_search_paths_set</code>, <code class="docutils literal notranslate">module_search_paths</code></li> </ul> </li> </ul> If at least one “output field” is not set, Python computes the path configuration to fill unset fields. If <code class="docutils literal notranslate">module_search_paths_set</code> is equal to 0, <code class="docutils literal notranslate">module_search_paths</code> is overridden and <code class="docutils literal notranslate">module_search_paths_set</code> is set to 1. 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 is non-empty. <code class="docutils literal notranslate">module_search_paths</code> is considered as set if <code class="docutils literal notranslate">module_search_paths_set</code> is set to 1. In this case, path configuration input fields are ignored as well. Set <code class="docutils literal notranslate">pathconfig_warnings</code> to 0 to suppress warnings when computing the path configuration (Unix only, Windows does not log any warning). If <code class="docutils literal notranslate">base_prefix</code> or <code class="docutils literal notranslate">base_exec_prefix</code> fields are not set, they inherit their value from <code class="docutils literal notranslate">prefix</code> and <code class="docutils literal notranslate">exec_prefix</code> respectively. <code class="docutils literal notranslate">Py_RunMain()</code> and <code class="docutils literal notranslate">Py_Main()</code> modify <code class="docutils literal notranslate">sys.path</code>: <ul class="simple"> <li>If <code class="docutils literal notranslate">run_filename</code> is set and is a directory which contains a <code class="docutils literal notranslate">__main__.py</code> script, prepend <code class="docutils literal notranslate">run_filename</code> to <code class="docutils literal notranslate">sys.path</code>.</li> <li>If <code class="docutils literal notranslate">isolated</code> is zero:<ul> <li>If <code class="docutils literal notranslate">run_module</code> is set, prepend the current directory to <code class="docutils literal notranslate">sys.path</code>. Do nothing if the current directory cannot be read.</li> <li>If <code class="docutils literal notranslate">run_filename</code> is set, prepends the directory of the filename to <code class="docutils literal notranslate">sys.path</code>.</li> <li>Otherwise, prepends an empty string to <code class="docutils literal notranslate">sys.path</code>.</li> </ul> </li> </ul> If <code class="docutils literal notranslate">site_import</code> is non-zero, <code class="docutils literal notranslate">sys.path</code> can be modified by the <code class="docutils literal notranslate">site</code> module. If <code class="docutils literal notranslate">user_site_directory</code> is non-zero and the user’s site-package directory exists, the <code class="docutils literal notranslate">site</code> module appends the user’s site-package directory to <code class="docutils literal notranslate">sys.path</code>. See also <a class="reference internal" href="#configuration-files">Configuration Files</a> used by the path configuration. </section> <section id="py-bytesmain"> <h3><a class="toc-backref" href="#py-bytesmain" role="doc-backlink">Py_BytesMain()</a></h3> Python 3.7 provides a high-level <code class="docutils literal notranslate">Py_Main()</code> function which requires to pass command line arguments as <code class="docutils literal notranslate">wchar_t*</code> strings. It is non-trivial to use the correct encoding to decode bytes. Python has its own set of issues with C locale coercion and UTF-8 Mode. This PEP adds a new <code class="docutils literal notranslate">Py_BytesMain()</code> function which takes command line arguments as bytes: <div class="highlight-default notranslate"><div class="highlight"><pre>int Py_BytesMain(int argc, char **argv) </pre></div> </div> </section> <section id="py-runmain"> <h3><a class="toc-backref" href="#py-runmain" role="doc-backlink">Py_RunMain()</a></h3> The new <code class="docutils literal notranslate">Py_RunMain()</code> function executes the command (<code class="docutils literal notranslate">PyConfig.run_command</code>), the script (<code class="docutils literal notranslate">PyConfig.run_filename</code>) or the module (<code class="docutils literal notranslate">PyConfig.run_module</code>) specified on the command line or in the configuration, and then finalizes Python. It returns an exit status that can be passed to the <code class="docutils literal notranslate">exit()</code> function. <div class="highlight-default notranslate"><div class="highlight"><pre>int Py_RunMain(void); </pre></div> </div> See <a class="reference internal" href="#python-configuration">Python Configuration</a> for an example of customized Python always running in isolated mode using <code class="docutils literal notranslate">Py_RunMain()</code>. </section> <section id="multi-phase-initialization-private-provisional-api"> <h3><a class="toc-backref" href="#multi-phase-initialization-private-provisional-api" role="doc-backlink">Multi-Phase Initialization Private Provisional API</a></h3> This section is a private provisional API introducing multi-phase initialization, the core feature of the <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a>: <ul class="simple"> <li>“Core” initialization phase, “bare minimum Python”:<ul> <li>Builtin types;</li> <li>Builtin exceptions;</li> <li>Builtin and frozen modules;</li> <li>The <code class="docutils literal notranslate">sys</code> module is only partially initialized (ex: <code class="docutils literal notranslate">sys.path</code> doesn’t exist yet);</li> </ul> </li> <li>“Main” initialization phase, Python is fully initialized:<ul> <li>Install and configure <code class="docutils literal notranslate">importlib</code>;</li> <li>Apply the <a class="reference internal" href="#path-configuration">Path Configuration</a>;</li> <li>Install signal handlers;</li> <li>Finish <code class="docutils literal notranslate">sys</code> module initialization (ex: create <code class="docutils literal notranslate">sys.stdout</code> and <code class="docutils literal notranslate">sys.path</code>);</li> <li>Enable optional features like <code class="docutils literal notranslate">faulthandler</code> and <code class="docutils literal notranslate">tracemalloc</code>;</li> <li>Import the <code class="docutils literal notranslate">site</code> module;</li> <li>etc.</li> </ul> </li> </ul> Private provisional API: <ul class="simple"> <li><code class="docutils literal notranslate">PyConfig._init_main</code>: if set to 0, <code class="docutils literal notranslate">Py_InitializeFromConfig()</code> stops at the “Core” initialization phase.</li> <li><code class="docutils literal notranslate">PyStatus _Py_InitializeMain(void)</code>: move to the “Main” initialization phase, finish the Python initialization.</li> </ul> No module is imported during the “Core” phase and the <code class="docutils literal notranslate">importlib</code> module is not configured: the <a class="reference internal" href="#path-configuration">Path Configuration</a> is only applied during the “Main” phase. It may allow to customize Python in Python to override or tune the <a class="reference internal" href="#path-configuration">Path Configuration</a>, maybe install a custom sys.meta_path importer or an import hook, etc. It may become possible to compute the <a class="reference internal" href="#path-configuration">Path Configuration</a> in Python, after the Core phase and before the Main phase, which is one of the PEP 432 motivation. 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 designed. Example running Python code between “Core” and “Main” initialization phases: <div class="highlight-default notranslate"><div class="highlight"><pre>void init_python(void) { PyStatus status; PyConfig config; PyConfig_InitPythonConfig(&config); config._init_main = 0; /* ... customize 'config' configuration ... */ status = Py_InitializeFromConfig(&config); PyConfig_Clear(&config); if (PyStatus_Exception(status)) { Py_ExitStatusException(status); } /* Use sys.stderr because sys.stdout is only created by _Py_InitializeMain() */ int res = PyRun_SimpleString( "import sys; " "print('Run Python code before _Py_InitializeMain', " "file=sys.stderr)"); if (res < 0) { exit(1); } /* ... put more configuration code here ... */ status = _Py_InitializeMain(); if (PyStatus_Exception(status)) { Py_ExitStatusException(status); } } </pre></div> </div> </section> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> This PEP only adds a new API: it leaves the existing API unchanged and has no impact on the backwards compatibility. The Python 3.7 <code class="docutils literal notranslate">Py_Initialize()</code> function now disable the C locale coercion (<a class="pep reference internal" href="../pep-0538/" title="PEP 538 – Coercing the legacy C locale to a UTF-8 based locale">PEP 538</a>) and the UTF-8 Mode (<a class="pep reference internal" href="../pep-0540/" title="PEP 540 – Add a new UTF-8 Mode">PEP 540</a>) by default to prevent mojibake. The new API using the <a class="reference internal" href="#python-configuration">Python Configuration</a> is needed to enable them automatically. </section> <section id="annexes"> <h2><a class="toc-backref" href="#annexes" role="doc-backlink">Annexes</a></h2> <section id="comparison-of-python-and-isolated-configurations"> <h3><a class="toc-backref" href="#comparison-of-python-and-isolated-configurations" role="doc-backlink">Comparison of Python and Isolated Configurations</a></h3> Differences between <code class="docutils literal notranslate">PyPreConfig_InitPythonConfig()</code> and <code class="docutils literal notranslate">PyPreConfig_InitIsolatedConfig()</code>: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">PyPreConfig</th> <th class="head">Python</th> <th class="head">Isolated</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">coerce_c_locale_warn</code></td> <td>-1</td> <td>0</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">coerce_c_locale</code></td> <td>-1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">configure_locale</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">dev_mode</code></td> <td>-1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">isolated</code></td> <td>0</td> <td>1</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">legacy_windows_fs_encoding</code></td> <td>-1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">use_environment</code></td> <td>0</td> <td>0</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">parse_argv</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">utf8_mode</code></td> <td>-1</td> <td>0</td> </tr> </tbody> </table> Differences between <code class="docutils literal notranslate">PyConfig_InitPythonConfig()</code> and <code class="docutils literal notranslate">PyConfig_InitIsolatedConfig()</code>: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">PyConfig</th> <th class="head">Python</th> <th class="head">Isolated</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">configure_c_stdio</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">install_signal_handlers</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">isolated</code></td> <td>0</td> <td>1</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">parse_argv</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">pathconfig_warnings</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">use_environment</code></td> <td>1</td> <td>0</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">user_site_directory</code></td> <td>1</td> <td>0</td> </tr> </tbody> </table> </section> <section id="priority-and-rules"> <h3><a class="toc-backref" href="#priority-and-rules" role="doc-backlink">Priority and Rules</a></h3> Priority of configuration parameters, highest to lowest: <ul class="simple"> <li><code class="docutils literal notranslate">PyConfig</code></li> <li><code class="docutils literal notranslate">PyPreConfig</code></li> <li>Configuration files</li> <li>Command line options</li> <li>Environment variables</li> <li>Global configuration variables</li> </ul> Priority of warning options, highest to lowest: <ul class="simple"> <li><code class="docutils literal notranslate">PyConfig.warnoptions</code></li> <li><code class="docutils literal notranslate">PySys_AddWarnOption()</code></li> <li><code class="docutils literal notranslate">PyConfig.bytes_warning</code> (add <code class="docutils literal notranslate">"error::BytesWarning"</code> filter if greater than 1, add <code class="docutils literal notranslate">"default::BytesWarning</code> filter if equals to 1)</li> <li><code class="docutils literal notranslate">-W opt</code> command line argument</li> <li><code class="docutils literal notranslate">PYTHONWARNINGS</code> environment variable</li> <li><code class="docutils literal notranslate">PyConfig.dev_mode</code> (add <code class="docutils literal notranslate">"default"</code> filter)</li> </ul> Rules on <code class="docutils literal notranslate">PyConfig</code> parameters: <ul class="simple"> <li>If <code class="docutils literal notranslate">isolated</code> is non-zero, <code class="docutils literal notranslate">use_environment</code> and <code class="docutils literal notranslate">user_site_directory</code> are set to 0.</li> <li>If <code class="docutils literal notranslate">dev_mode</code> is non-zero, <code class="docutils literal notranslate">allocator</code> is set to <code class="docutils literal notranslate">"debug"</code>, <code class="docutils literal notranslate">faulthandler</code> is set to 1, and <code class="docutils literal notranslate">"default"</code> filter is added to <code class="docutils literal notranslate">warnoptions</code>. But the <code class="docutils literal notranslate">PYTHONMALLOC</code> environment variable has the priority over <code class="docutils literal notranslate">dev_mode</code> to set the memory allocator.</li> <li>If <code class="docutils literal notranslate">base_prefix</code> is not set, it inherits <code class="docutils literal notranslate">prefix</code> value.</li> <li>If <code class="docutils literal notranslate">base_exec_prefix</code> is not set, it inherits <code class="docutils literal notranslate">exec_prefix</code> value.</li> <li>If the <code class="docutils literal notranslate">python._pth</code> configuration file is present, <code class="docutils literal notranslate">isolated</code> is set to 1 and <code class="docutils literal notranslate">site_import</code> is set to 0; but <code class="docutils literal notranslate">site_import</code> is set to 1 if <code class="docutils literal notranslate">python._pth</code> contains <code class="docutils literal notranslate">import site</code>.</li> </ul> Rules on <code class="docutils literal notranslate">PyConfig</code> and <code class="docutils literal notranslate">PyPreConfig</code> parameters: <ul class="simple"> <li>If <code class="docutils literal notranslate">PyPreConfig.legacy_windows_fs_encoding</code> is non-zero, set <code class="docutils literal notranslate">PyPreConfig.utf8_mode</code> to 0, set <code class="docutils literal notranslate">PyConfig.filesystem_encoding</code> to <code class="docutils literal notranslate">mbcs</code>, and set <code class="docutils literal notranslate">PyConfig.filesystem_errors</code> to <code class="docutils literal notranslate">replace</code>.</li> </ul> </section> <section id="configuration-files"> <h3><a class="toc-backref" href="#configuration-files" role="doc-backlink">Configuration Files</a></h3> Python configuration files used by the <a class="reference internal" href="#path-configuration">Path Configuration</a>: <ul class="simple"> <li><code class="docutils literal notranslate">pyvenv.cfg</code></li> <li><code class="docutils literal notranslate">python._pth</code> (Windows only)</li> <li><code class="docutils literal notranslate">pybuilddir.txt</code> (Unix only)</li> </ul> </section> <section id="global-configuration-variables"> <h3><a class="toc-backref" href="#global-configuration-variables" role="doc-backlink">Global Configuration Variables</a></h3> Global configuration variables mapped to <code class="docutils literal notranslate">PyPreConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Variable</th> <th class="head">Field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">Py_IgnoreEnvironmentFlag</code></td> <td><code class="docutils literal notranslate">use_environment</code> (NOT)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_IsolatedFlag</code></td> <td><code class="docutils literal notranslate">isolated</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_LegacyWindowsFSEncodingFlag</code></td> <td><code class="docutils literal notranslate">legacy_windows_fs_encoding</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_UTF8Mode</code></td> <td><code class="docutils literal notranslate">utf8_mode</code></td> </tr> </tbody> </table> (NOT) means that the <code class="docutils literal notranslate">PyPreConfig</code> value is the opposite of the global configuration variable value. <code class="docutils literal notranslate">Py_LegacyWindowsFSEncodingFlag</code> is only available on Windows. Global configuration variables mapped to <code class="docutils literal notranslate">PyConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Variable</th> <th class="head">Field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">Py_BytesWarningFlag</code></td> <td><code class="docutils literal notranslate">bytes_warning</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_DebugFlag</code></td> <td><code class="docutils literal notranslate">parser_debug</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_DontWriteBytecodeFlag</code></td> <td><code class="docutils literal notranslate">write_bytecode</code> (NOT)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_FileSystemDefaultEncodeErrors</code></td> <td><code class="docutils literal notranslate">filesystem_errors</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_FileSystemDefaultEncoding</code></td> <td><code class="docutils literal notranslate">filesystem_encoding</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_FrozenFlag</code></td> <td><code class="docutils literal notranslate">pathconfig_warnings</code> (NOT)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_HasFileSystemDefaultEncoding</code></td> <td><code class="docutils literal notranslate">filesystem_encoding</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_HashRandomizationFlag</code></td> <td><code class="docutils literal notranslate">use_hash_seed</code>, <code class="docutils literal notranslate">hash_seed</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_IgnoreEnvironmentFlag</code></td> <td><code class="docutils literal notranslate">use_environment</code> (NOT)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_InspectFlag</code></td> <td><code class="docutils literal notranslate">inspect</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_InteractiveFlag</code></td> <td><code class="docutils literal notranslate">interactive</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_IsolatedFlag</code></td> <td><code class="docutils literal notranslate">isolated</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_LegacyWindowsStdioFlag</code></td> <td><code class="docutils literal notranslate">legacy_windows_stdio</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_NoSiteFlag</code></td> <td><code class="docutils literal notranslate">site_import</code> (NOT)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_NoUserSiteDirectory</code></td> <td><code class="docutils literal notranslate">user_site_directory</code> (NOT)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_OptimizeFlag</code></td> <td><code class="docutils literal notranslate">optimization_level</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_QuietFlag</code></td> <td><code class="docutils literal notranslate">quiet</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">Py_UnbufferedStdioFlag</code></td> <td><code class="docutils literal notranslate">buffered_stdio</code> (NOT)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">Py_VerboseFlag</code></td> <td><code class="docutils literal notranslate">verbose</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">_Py_HasFileSystemDefaultEncodeErrors</code></td> <td><code class="docutils literal notranslate">filesystem_errors</code></td> </tr> </tbody> </table> (NOT) means that the <code class="docutils literal notranslate">PyConfig</code> value is the opposite of the global configuration variable value. <code class="docutils literal notranslate">Py_LegacyWindowsStdioFlag</code> is only available on Windows. </section> <section id="command-line-arguments"> <h3><a class="toc-backref" href="#command-line-arguments" role="doc-backlink">Command Line Arguments</a></h3> Usage: <div class="highlight-default notranslate"><div class="highlight"><pre>python3 [options] python3 [options] -c COMMAND python3 [options] -m MODULE python3 [options] SCRIPT </pre></div> </div> Command line options mapped to pseudo-action on <code class="docutils literal notranslate">PyPreConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Option</th> <th class="head"><code class="docutils literal notranslate">PyConfig</code> field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">-E</code></td> <td><code class="docutils literal notranslate">use_environment = 0</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-I</code></td> <td><code class="docutils literal notranslate">isolated = 1</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-X dev</code></td> <td><code class="docutils literal notranslate">dev_mode = 1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-X utf8</code></td> <td><code class="docutils literal notranslate">utf8_mode = 1</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-X utf8=VALUE</code></td> <td><code class="docutils literal notranslate">utf8_mode = VALUE</code></td> </tr> </tbody> </table> Command line options mapped to pseudo-action on <code class="docutils literal notranslate">PyConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Option</th> <th class="head"><code class="docutils literal notranslate">PyConfig</code> field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">-b</code></td> <td><code class="docutils literal notranslate">bytes_warning++</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-B</code></td> <td><code class="docutils literal notranslate">write_bytecode = 0</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-c COMMAND</code></td> <td><code class="docutils literal notranslate">run_command = COMMAND</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">--check-hash-based-pycs=MODE</code></td> <td><code class="docutils literal notranslate">check_hash_pycs_mode = MODE</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-d</code></td> <td><code class="docutils literal notranslate">parser_debug++</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-E</code></td> <td><code class="docutils literal notranslate">use_environment = 0</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-i</code></td> <td><code class="docutils literal notranslate">inspect++</code> and <code class="docutils literal notranslate">interactive++</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-I</code></td> <td><code class="docutils literal notranslate">isolated = 1</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-m MODULE</code></td> <td><code class="docutils literal notranslate">run_module = MODULE</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-O</code></td> <td><code class="docutils literal notranslate">optimization_level++</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-q</code></td> <td><code class="docutils literal notranslate">quiet++</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-R</code></td> <td><code class="docutils literal notranslate">use_hash_seed = 0</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-s</code></td> <td><code class="docutils literal notranslate">user_site_directory = 0</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-S</code></td> <td><code class="docutils literal notranslate">site_import</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-t</code></td> <td>ignored (kept for backwards compatibility)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-u</code></td> <td><code class="docutils literal notranslate">buffered_stdio = 0</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-v</code></td> <td><code class="docutils literal notranslate">verbose++</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-W WARNING</code></td> <td>add <code class="docutils literal notranslate">WARNING</code> to <code class="docutils literal notranslate">warnoptions</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-x</code></td> <td><code class="docutils literal notranslate">skip_source_first_line = 1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-X OPTION</code></td> <td>add <code class="docutils literal notranslate">OPTION</code> to <code class="docutils literal notranslate">xoptions</code></td> </tr> </tbody> </table> <code class="docutils literal notranslate">-h</code>, <code class="docutils literal notranslate">-?</code> and <code class="docutils literal notranslate">-V</code> options are handled without <code class="docutils literal notranslate">PyConfig</code>. </section> <section id="x-options"> <h3><a class="toc-backref" href="#x-options" role="doc-backlink">-X Options</a></h3> -X options mapped to pseudo-action on <code class="docutils literal notranslate">PyConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Option</th> <th class="head"><code class="docutils literal notranslate">PyConfig</code> field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">-X dev</code></td> <td><code class="docutils literal notranslate">dev_mode = 1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-X faulthandler</code></td> <td><code class="docutils literal notranslate">faulthandler = 1</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-X importtime</code></td> <td><code class="docutils literal notranslate">import_time = 1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-X pycache_prefix=PREFIX</code></td> <td><code class="docutils literal notranslate">pycache_prefix = PREFIX</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-X showalloccount</code></td> <td><code class="docutils literal notranslate">show_alloc_count = 1</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-X showrefcount</code></td> <td><code class="docutils literal notranslate">show_ref_count = 1</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">-X tracemalloc=N</code></td> <td><code class="docutils literal notranslate">tracemalloc = N</code></td> </tr> </tbody> </table> </section> <section id="environment-variables"> <h3><a class="toc-backref" href="#environment-variables" role="doc-backlink">Environment Variables</a></h3> Environment variables mapped to <code class="docutils literal notranslate">PyPreConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Variable</th> <th class="head"><code class="docutils literal notranslate">PyPreConfig</code> field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONCOERCECLOCALE</code></td> <td><code class="docutils literal notranslate">coerce_c_locale</code>, <code class="docutils literal notranslate">coerce_c_locale_warn</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONDEVMODE</code></td> <td><code class="docutils literal notranslate">dev_mode</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONLEGACYWINDOWSFSENCODING</code></td> <td><code class="docutils literal notranslate">legacy_windows_fs_encoding</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONMALLOC</code></td> <td><code class="docutils literal notranslate">allocator</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONUTF8</code></td> <td><code class="docutils literal notranslate">utf8_mode</code></td> </tr> </tbody> </table> Environment variables mapped to <code class="docutils literal notranslate">PyConfig</code> fields: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Variable</th> <th class="head"><code class="docutils literal notranslate">PyConfig</code> field</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONDEBUG</code></td> <td><code class="docutils literal notranslate">parser_debug</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONDEVMODE</code></td> <td><code class="docutils literal notranslate">dev_mode</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONDONTWRITEBYTECODE</code></td> <td><code class="docutils literal notranslate">write_bytecode</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONDUMPREFS</code></td> <td><code class="docutils literal notranslate">dump_refs</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONEXECUTABLE</code></td> <td><code class="docutils literal notranslate">program_name</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONFAULTHANDLER</code></td> <td><code class="docutils literal notranslate">faulthandler</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONHASHSEED</code></td> <td><code class="docutils literal notranslate">use_hash_seed</code>, <code class="docutils literal notranslate">hash_seed</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONHOME</code></td> <td><code class="docutils literal notranslate">home</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONINSPECT</code></td> <td><code class="docutils literal notranslate">inspect</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONIOENCODING</code></td> <td><code class="docutils literal notranslate">stdio_encoding</code>, <code class="docutils literal notranslate">stdio_errors</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONLEGACYWINDOWSSTDIO</code></td> <td><code class="docutils literal notranslate">legacy_windows_stdio</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONMALLOCSTATS</code></td> <td><code class="docutils literal notranslate">malloc_stats</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONNOUSERSITE</code></td> <td><code class="docutils literal notranslate">user_site_directory</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONOPTIMIZE</code></td> <td><code class="docutils literal notranslate">optimization_level</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONPATH</code></td> <td><code class="docutils literal notranslate">pythonpath_env</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONPROFILEIMPORTTIME</code></td> <td><code class="docutils literal notranslate">import_time</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONPYCACHEPREFIX,</code></td> <td><code class="docutils literal notranslate">pycache_prefix</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONTRACEMALLOC</code></td> <td><code class="docutils literal notranslate">tracemalloc</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONUNBUFFERED</code></td> <td><code class="docutils literal notranslate">buffered_stdio</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PYTHONVERBOSE</code></td> <td><code class="docutils literal notranslate">verbose</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PYTHONWARNINGS</code></td> <td><code class="docutils literal notranslate">warnoptions</code></td> </tr> </tbody> </table> <code class="docutils literal notranslate">PYTHONLEGACYWINDOWSFSENCODING</code> and <code class="docutils literal notranslate">PYTHONLEGACYWINDOWSSTDIO</code> are specific to Windows. </section> <section id="default-python-configuration"> <h3><a class="toc-backref" href="#default-python-configuration" role="doc-backlink">Default Python Configuration</a></h3> <code class="docutils literal notranslate">PyPreConfig_InitPythonConfig()</code>: <ul class="simple"> <li><code class="docutils literal notranslate">allocator</code> = <code class="docutils literal notranslate">PYMEM_ALLOCATOR_NOT_SET</code></li> <li><code class="docutils literal notranslate">coerce_c_locale_warn</code> = -1</li> <li><code class="docutils literal notranslate">coerce_c_locale</code> = -1</li> <li><code class="docutils literal notranslate">configure_locale</code> = 1</li> <li><code class="docutils literal notranslate">dev_mode</code> = -1</li> <li><code class="docutils literal notranslate">isolated</code> = 0</li> <li><code class="docutils literal notranslate">legacy_windows_fs_encoding</code> = -1</li> <li><code class="docutils literal notranslate">use_environment</code> = 1</li> <li><code class="docutils literal notranslate">utf8_mode</code> = -1</li> </ul> <code class="docutils literal notranslate">PyConfig_InitPythonConfig()</code>: <ul class="simple"> <li><code class="docutils literal notranslate">argv</code> = []</li> <li><code class="docutils literal notranslate">base_exec_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">base_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">buffered_stdio</code> = 1</li> <li><code class="docutils literal notranslate">bytes_warning</code> = 0</li> <li><code class="docutils literal notranslate">check_hash_pycs_mode</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">configure_c_stdio</code> = 1</li> <li><code class="docutils literal notranslate">dev_mode</code> = 0</li> <li><code class="docutils literal notranslate">dump_refs</code> = 0</li> <li><code class="docutils literal notranslate">exec_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">executable</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">faulthandler</code> = 0</li> <li><code class="docutils literal notranslate">filesystem_encoding</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">filesystem_errors</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">hash_seed</code> = 0</li> <li><code class="docutils literal notranslate">home</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">import_time</code> = 0</li> <li><code class="docutils literal notranslate">inspect</code> = 0</li> <li><code class="docutils literal notranslate">install_signal_handlers</code> = 1</li> <li><code class="docutils literal notranslate">interactive</code> = 0</li> <li><code class="docutils literal notranslate">isolated</code> = 0</li> <li><code class="docutils literal notranslate">malloc_stats</code> = 0</li> <li><code class="docutils literal notranslate">module_search_path_env</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">module_search_paths</code> = []</li> <li><code class="docutils literal notranslate">optimization_level</code> = 0</li> <li><code class="docutils literal notranslate">parse_argv</code> = 1</li> <li><code class="docutils literal notranslate">parser_debug</code> = 0</li> <li><code class="docutils literal notranslate">pathconfig_warnings</code> = 1</li> <li><code class="docutils literal notranslate">prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">program_name</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">pycache_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">quiet</code> = 0</li> <li><code class="docutils literal notranslate">run_command</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">run_filename</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">run_module</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">show_alloc_count</code> = 0</li> <li><code class="docutils literal notranslate">show_ref_count</code> = 0</li> <li><code class="docutils literal notranslate">site_import</code> = 1</li> <li><code class="docutils literal notranslate">skip_source_first_line</code> = 0</li> <li><code class="docutils literal notranslate">stdio_encoding</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">stdio_errors</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">tracemalloc</code> = 0</li> <li><code class="docutils literal notranslate">use_environment</code> = 1</li> <li><code class="docutils literal notranslate">use_hash_seed</code> = 0</li> <li><code class="docutils literal notranslate">user_site_directory</code> = 1</li> <li><code class="docutils literal notranslate">verbose</code> = 0</li> <li><code class="docutils literal notranslate">warnoptions</code> = []</li> <li><code class="docutils literal notranslate">write_bytecode</code> = 1</li> <li><code class="docutils literal notranslate">xoptions</code> = []</li> <li><code class="docutils literal notranslate">_init_main</code> = 1</li> <li><code class="docutils literal notranslate">_install_importlib</code> = 1</li> </ul> </section> <section id="default-isolated-configuration"> <h3><a class="toc-backref" href="#default-isolated-configuration" role="doc-backlink">Default Isolated Configuration</a></h3> <code class="docutils literal notranslate">PyPreConfig_InitIsolatedConfig()</code>: <ul class="simple"> <li><code class="docutils literal notranslate">allocator</code> = <code class="docutils literal notranslate">PYMEM_ALLOCATOR_NOT_SET</code></li> <li><code class="docutils literal notranslate">coerce_c_locale_warn</code> = 0</li> <li><code class="docutils literal notranslate">coerce_c_locale</code> = 0</li> <li><code class="docutils literal notranslate">configure_locale</code> = 0</li> <li><code class="docutils literal notranslate">dev_mode</code> = 0</li> <li><code class="docutils literal notranslate">isolated</code> = 1</li> <li><code class="docutils literal notranslate">legacy_windows_fs_encoding</code> = 0</li> <li><code class="docutils literal notranslate">use_environment</code> = 0</li> <li><code class="docutils literal notranslate">utf8_mode</code> = 0</li> </ul> <code class="docutils literal notranslate">PyConfig_InitIsolatedConfig()</code>: <ul class="simple"> <li><code class="docutils literal notranslate">argv</code> = []</li> <li><code class="docutils literal notranslate">base_exec_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">base_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">buffered_stdio</code> = 1</li> <li><code class="docutils literal notranslate">bytes_warning</code> = 0</li> <li><code class="docutils literal notranslate">check_hash_pycs_mode</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">configure_c_stdio</code> = 0</li> <li><code class="docutils literal notranslate">dev_mode</code> = 0</li> <li><code class="docutils literal notranslate">dump_refs</code> = 0</li> <li><code class="docutils literal notranslate">exec_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">executable</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">faulthandler</code> = 0</li> <li><code class="docutils literal notranslate">filesystem_encoding</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">filesystem_errors</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">hash_seed</code> = 0</li> <li><code class="docutils literal notranslate">home</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">import_time</code> = 0</li> <li><code class="docutils literal notranslate">inspect</code> = 0</li> <li><code class="docutils literal notranslate">install_signal_handlers</code> = 0</li> <li><code class="docutils literal notranslate">interactive</code> = 0</li> <li><code class="docutils literal notranslate">isolated</code> = 1</li> <li><code class="docutils literal notranslate">malloc_stats</code> = 0</li> <li><code class="docutils literal notranslate">module_search_path_env</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">module_search_paths</code> = []</li> <li><code class="docutils literal notranslate">optimization_level</code> = 0</li> <li><code class="docutils literal notranslate">parse_argv</code> = 0</li> <li><code class="docutils literal notranslate">parser_debug</code> = 0</li> <li><code class="docutils literal notranslate">pathconfig_warnings</code> = 0</li> <li><code class="docutils literal notranslate">prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">program_name</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">pycache_prefix</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">quiet</code> = 0</li> <li><code class="docutils literal notranslate">run_command</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">run_filename</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">run_module</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">show_alloc_count</code> = 0</li> <li><code class="docutils literal notranslate">show_ref_count</code> = 0</li> <li><code class="docutils literal notranslate">site_import</code> = 1</li> <li><code class="docutils literal notranslate">skip_source_first_line</code> = 0</li> <li><code class="docutils literal notranslate">stdio_encoding</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">stdio_errors</code> = <code class="docutils literal notranslate">NULL</code></li> <li><code class="docutils literal notranslate">tracemalloc</code> = 0</li> <li><code class="docutils literal notranslate">use_environment</code> = 0</li> <li><code class="docutils literal notranslate">use_hash_seed</code> = 0</li> <li><code class="docutils literal notranslate">user_site_directory</code> = 0</li> <li><code class="docutils literal notranslate">verbose</code> = 0</li> <li><code class="docutils literal notranslate">warnoptions</code> = []</li> <li><code class="docutils literal notranslate">write_bytecode</code> = 1</li> <li><code class="docutils literal notranslate">xoptions</code> = []</li> <li><code class="docutils literal notranslate">_init_main</code> = 1</li> <li><code class="docutils literal notranslate">_install_importlib</code> = 1</li> </ul> </section> <section id="python-3-7-api"> <h3><a class="toc-backref" href="#python-3-7-api" role="doc-backlink">Python 3.7 API</a></h3> Python 3.7 has 4 functions in its C API to initialize and finalize Python: <ul class="simple"> <li><code class="docutils literal notranslate">Py_Initialize()</code>, <code class="docutils literal notranslate">Py_InitializeEx()</code>: initialize Python</li> <li><code class="docutils literal notranslate">Py_Finalize()</code>, <code class="docutils literal notranslate">Py_FinalizeEx()</code>: finalize Python</li> </ul> Python 3.7 can be configured using <a class="reference internal" href="#global-configuration-variables">Global Configuration Variables</a>, <a class="reference internal" href="#environment-variables">Environment Variables</a>, and the following functions: <ul class="simple"> <li><code class="docutils literal notranslate">PyImport_AppendInittab()</code></li> <li><code class="docutils literal notranslate">PyImport_ExtendInittab()</code></li> <li><code class="docutils literal notranslate">PyMem_SetAllocator()</code></li> <li><code class="docutils literal notranslate">PyMem_SetupDebugHooks()</code></li> <li><code class="docutils literal notranslate">PyObject_SetArenaAllocator()</code></li> <li><code class="docutils literal notranslate">Py_SetPath()</code></li> <li><code class="docutils literal notranslate">Py_SetProgramName()</code></li> <li><code class="docutils literal notranslate">Py_SetPythonHome()</code></li> <li><code class="docutils literal notranslate">Py_SetStandardStreamEncoding()</code></li> <li><code class="docutils literal notranslate">PySys_AddWarnOption()</code></li> <li><code class="docutils literal notranslate">PySys_AddXOption()</code></li> <li><code class="docutils literal notranslate">PySys_ResetWarnOptions()</code></li> </ul> There is also a high-level <code class="docutils literal notranslate">Py_Main()</code> function and <code class="docutils literal notranslate">PyImport_FrozenModules</code> variable which can be overridden. See <a class="reference external" href="https://docs.python.org/dev/c-api/init.html">Initialization, Finalization, and Threads</a> documentation. </section> </section> <section id="python-issues"> <h2><a class="toc-backref" href="#python-issues" role="doc-backlink">Python Issues</a></h2> Issues that will be fixed by this PEP, directly or indirectly: <ul class="simple"> <li><a class="reference external" href="https://bugs.python.org/issue1195571">bpo-1195571</a>: “simple callback system for Py_FatalError”</li> <li><a class="reference external" href="https://bugs.python.org/issue11320">bpo-11320</a>: “Usage of API method Py_SetPath causes errors in Py_Initialize() (Posix only)”</li> <li><a class="reference external" href="https://bugs.python.org/issue13533">bpo-13533</a>: “Would like Py_Initialize to play friendly with host app”</li> <li><a class="reference external" href="https://bugs.python.org/issue14956">bpo-14956</a>: “custom PYTHONPATH may break apps embedding Python”</li> <li><a class="reference external" href="https://bugs.python.org/issue19983">bpo-19983</a>: “When interrupted during startup, Python should not call abort() but exit()”</li> <li><a class="reference external" href="https://bugs.python.org/issue22213">bpo-22213</a>: “Make pyvenv style virtual environments easier to configure when embedding Python”.</li> <li><a class="reference external" href="https://bugs.python.org/issue29778">bpo-29778</a>: “_Py_CheckPython3 uses uninitialized dllpath when embedder sets module path with Py_SetPath”</li> <li><a class="reference external" href="https://bugs.python.org/issue30560">bpo-30560</a>: “Add Py_SetFatalErrorAbortFunc: Allow embedding program to handle fatal errors”.</li> <li><a class="reference external" href="https://bugs.python.org/issue31745">bpo-31745</a>: “Overloading “Py_GetPath” does not work”</li> <li><a class="reference external" href="https://bugs.python.org/issue32573">bpo-32573</a>: “All sys attributes (.argv, …) should exist in embedded environments”.</li> <li><a class="reference external" href="https://bugs.python.org/issue33135">bpo-33135</a>: “Define field prefixes for the various config structs”. The PEP now defines well how warnings options are handled.</li> <li><a class="reference external" href="https://bugs.python.org/issue34725">bpo-34725</a>: “Py_GetProgramFullPath() odd behaviour in Windows”</li> <li><a class="reference external" href="https://bugs.python.org/issue36204">bpo-36204</a>: “Deprecate calling Py_Main() after Py_Initialize()? Add Py_InitializeFromArgv()?”</li> </ul> Issues of the PEP implementation: <ul class="simple"> <li><a class="reference external" href="https://bugs.python.org/issue16961">bpo-16961</a>: “No regression tests for -E and individual environment vars”</li> <li><a class="reference external" href="https://bugs.python.org/issue20361">bpo-20361</a>: “-W command line options and PYTHONWARNINGS environmental variable should not override -b / -bb command line options”</li> <li><a class="reference external" href="https://bugs.python.org/issue26122">bpo-26122</a>: “Isolated mode doesn’t ignore PYTHONHASHSEED”</li> <li><a class="reference external" href="https://bugs.python.org/issue29818">bpo-29818</a>: “Py_SetStandardStreamEncoding leads to a memory error in debug mode”</li> <li><a class="reference external" href="https://bugs.python.org/issue31845">bpo-31845</a>: “PYTHONDONTWRITEBYTECODE and PYTHONOPTIMIZE have no effect”</li> <li><a class="reference external" href="https://bugs.python.org/issue32030">bpo-32030</a>: “PEP 432: Rewrite Py_Main()”</li> <li><a class="reference external" href="https://bugs.python.org/issue32124">bpo-32124</a>: “Document functions safe to be called before Py_Initialize()”</li> <li><a class="reference external" href="https://bugs.python.org/issue33042">bpo-33042</a>: “New 3.7 startup sequence crashes PyInstaller”</li> <li><a class="reference external" href="https://bugs.python.org/issue33932">bpo-33932</a>: “Calling Py_Initialize() twice now triggers a fatal error (Python 3.7)”</li> <li><a class="reference external" href="https://bugs.python.org/issue34008">bpo-34008</a>: “Do we support calling Py_Main() after Py_Initialize()?”</li> <li><a class="reference external" href="https://bugs.python.org/issue34170">bpo-34170</a>: “Py_Initialize(): computing path configuration must not have side effect (PEP 432)”</li> <li><a class="reference external" href="https://bugs.python.org/issue34589">bpo-34589</a>: “Py_Initialize() and Py_Main() should not enable C locale coercion”</li> <li><a class="reference external" href="https://bugs.python.org/issue34639">bpo-34639</a>: “PYTHONCOERCECLOCALE is ignored when using -E or -I option”</li> <li><a class="reference external" href="https://bugs.python.org/issue36142">bpo-36142</a>: “Add a new _PyPreConfig step to Python initialization to setup memory allocator and encodings”</li> <li><a class="reference external" href="https://bugs.python.org/issue36202">bpo-36202</a>: “Calling Py_DecodeLocale() before _PyPreConfig_Write() can produce mojibake”</li> <li><a class="reference external" href="https://bugs.python.org/issue36301">bpo-36301</a>: “Add _Py_PreInitialize() function”</li> <li><a class="reference external" href="https://bugs.python.org/issue36443">bpo-36443</a>: “Disable coerce_c_locale and utf8_mode by default in _PyPreConfig?”</li> <li><a class="reference external" href="https://bugs.python.org/issue36444">bpo-36444</a>: “Python initialization: remove _PyMainInterpreterConfig”</li> <li><a class="reference external" href="https://bugs.python.org/issue36471">bpo-36471</a>: “PEP 432, PEP 587: Add _Py_RunMain()”</li> <li><a class="reference external" href="https://bugs.python.org/issue36763">bpo-36763</a>: “PEP 587: Rework initialization API to prepare second version of the PEP”</li> <li><a class="reference external" href="https://bugs.python.org/issue36775">bpo-36775</a>: “Rework filesystem codec implementation”</li> <li><a class="reference external" href="https://bugs.python.org/issue36900">bpo-36900</a>: “Use _PyCoreConfig rather than global configuration variables”</li> </ul> Issues related to this PEP: <ul class="simple"> <li><a class="reference external" href="https://bugs.python.org/issue12598">bpo-12598</a>: “Move sys variable initialization from import.c to sysmodule.c”</li> <li><a class="reference external" href="https://bugs.python.org/issue15577">bpo-15577</a>: “Real argc and argv in embedded interpreter”</li> <li><a class="reference external" href="https://bugs.python.org/issue16202">bpo-16202</a>: “sys.path[0] security issues”</li> <li><a class="reference external" href="https://bugs.python.org/issue18309">bpo-18309</a>: “Make python slightly more relocatable”</li> <li><a class="reference external" href="https://bugs.python.org/issue22257">bpo-22257</a>: “PEP 432: Redesign the interpreter startup sequence”</li> <li><a class="reference external" href="https://bugs.python.org/issue25631">bpo-25631</a>: “Segmentation fault with invalid Unicode command-line arguments in embedded Python”</li> <li><a class="reference external" href="https://bugs.python.org/issue26007">bpo-26007</a>: “Support embedding the standard library in an executable”</li> <li><a class="reference external" href="https://bugs.python.org/issue31210">bpo-31210</a>: “Can not import modules if sys.prefix contains DELIM”.</li> <li><a class="reference external" href="https://bugs.python.org/issue31349">bpo-31349</a>: “Embedded initialization ignores Py_SetProgramName()”</li> <li><a class="reference external" href="https://bugs.python.org/issue33919">bpo-33919</a>: “Expose _PyCoreConfig structure to Python”</li> <li><a class="reference external" href="https://bugs.python.org/issue35173">bpo-35173</a>: “Re-use already existing functionality to allow Python 2.7.x (both embedded and standalone) to locate the module path according to the shared library”</li> </ul> </section> <section id="discussions"> <h2><a class="toc-backref" href="#discussions" role="doc-backlink">Discussions</a></h2> <ul class="simple"> <li>May 2019:<ul> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-May/157492.html">[Python-Dev] PEP 587 “Python Initialization Configuration” version 4</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-May/157435.html">[Python-Dev] RFC: PEP 587 “Python Initialization Configuration”: 3rd version</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-May/157385.html">Study on applications embedding Python</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-May/157290.html">[Python-Dev] RFC: PEP 587 “Python Initialization Configuration”: 2nd version</a></li> </ul> </li> <li>March 2019:<ul> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-March/156892.html">[Python-Dev] PEP 587: Python Initialization Configuration</a></li> <li><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-March/156884.html">[Python-Dev] New Python Initialization API</a></li> </ul> </li> <li>February 2019:<ul> <li><a class="reference external" href="https://discuss.python.org/t/adding-char-based-apis-for-unix/916">Adding char* based APIs for Unix</a></li> </ul> </li> <li>July-August 2018:<ul> <li>July: <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2018-July/154882.html">[Python-Dev] New _Py_InitializeFromConfig() function (PEP 432)</a></li> <li>August: <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2018-August/154896.html">[Python-Dev] New _Py_InitializeFromConfig() function (PEP 432)</a></li> </ul> </li> </ul> </section> <section id="version-history"> <h2><a class="toc-backref" href="#version-history" role="doc-backlink">Version History</a></h2> <ul class="simple"> <li>Version 5:<ul> <li>Rename <code class="docutils literal notranslate">PyInitError</code> to <code class="docutils literal notranslate">PyStatus</code></li> <li>Rename <code class="docutils literal notranslate">PyInitError_Failed()</code> to <code class="docutils literal notranslate">PyStatus_Exception()</code></li> <li>Rename <code class="docutils literal notranslate">Py_ExitInitError()</code> to <code class="docutils literal notranslate">Py_ExitStatusException()</code></li> <li>Add <code class="docutils literal notranslate">PyPreConfig._config_init</code> private field.</li> <li>Fix Python Configuration default values: isolated=0 and use_environment=1, instead of -1.</li> <li>Add “Multi-Phase Initialization Private Provisional API” and “Discussions” sections</li> </ul> </li> <li>Version 4:<ul> <li>Introduce “Python Configuration” and “Isolated Configuration” which are well better defined. Replace all macros with functions.</li> <li>Replace <code class="docutils literal notranslate">PyPreConfig_INIT</code> and <code class="docutils literal notranslate">PyConfig_INIT</code> macros with functions:<ul> <li><code class="docutils literal notranslate">PyPreConfig_InitIsolatedConfig()</code>, <code class="docutils literal notranslate">PyConfig_InitIsolatedConfig()</code></li> <li><code class="docutils literal notranslate">PyPreConfig_InitPythonConfig()</code>, <code class="docutils literal notranslate">PyConfig_InitPythonConfig()</code></li> </ul> </li> <li><code class="docutils literal notranslate">PyPreConfig</code> no longer uses dynamic memory, the <code class="docutils literal notranslate">allocator</code> field type becomes an int, add <code class="docutils literal notranslate">configure_locale</code> and <code class="docutils literal notranslate">parse_argv</code> field.</li> <li><code class="docutils literal notranslate">PyConfig</code>: rename <code class="docutils literal notranslate">module_search_path_env</code> to <code class="docutils literal notranslate">pythonpath_env</code>, rename <code class="docutils literal notranslate">use_module_search_paths</code> to <code class="docutils literal notranslate">module_search_paths_set</code>, remove <code class="docutils literal notranslate">program</code> and <code class="docutils literal notranslate">dll_path</code>.</li> <li>Replace <code class="docutils literal notranslate">Py_INIT_xxx()</code> macros with <code class="docutils literal notranslate">PyInitError_xxx()</code> functions.</li> <li>Remove the “Constant PyConfig” section. Remove <code class="docutils literal notranslate">Py_InitializeFromArgs()</code> and <code class="docutils literal notranslate">Py_InitializeFromBytesArgs()</code> functions.</li> </ul> </li> <li>Version 3:<ul> <li><code class="docutils literal notranslate">PyConfig</code>: Add <code class="docutils literal notranslate">configure_c_stdio</code> and <code class="docutils literal notranslate">parse_argv</code>; rename <code class="docutils literal notranslate">_frozen</code> to <code class="docutils literal notranslate">pathconfig_warnings</code>.</li> <li>Rename functions using bytes strings and wide character strings. For example, <code class="docutils literal notranslate">Py_PreInitializeFromWideArgs()</code> becomes <code class="docutils literal notranslate">Py_PreInitializeFromArgs()</code>, and <code class="docutils literal notranslate">PyConfig_SetArgv()</code> becomes <code class="docutils literal notranslate">PyConfig_SetBytesArgv()</code>.</li> <li>Add <code class="docutils literal notranslate">PyWideStringList_Insert()</code> function.</li> <li>New “Path configuration”, “Isolate Python”, “Python Issues” and “Version History” sections.</li> <li><code class="docutils literal notranslate">PyConfig_SetString()</code> and <code class="docutils literal notranslate">PyConfig_SetBytesString()</code> now requires the configuration as the first argument.</li> <li>Rename <code class="docutils literal notranslate">Py_UnixMain()</code> to <code class="docutils literal notranslate">Py_BytesMain()</code></li> </ul> </li> <li>Version 2: Add <code class="docutils literal notranslate">PyConfig</code> methods (ex: <code class="docutils literal notranslate">PyConfig_Read()</code>), add <code class="docutils literal notranslate">PyWideStringList_Append()</code>, rename <code class="docutils literal notranslate">PyWideCharList</code> to <code class="docutils literal notranslate">PyWideStringList</code>.</li> <li>Version 1: Initial version.</li> </ul> </section> <section id="acceptance"> <h2><a class="toc-backref" href="#acceptance" role="doc-backlink">Acceptance</a></h2> <a class="pep reference internal" href="../pep-0587/" title="PEP 587 – Python Initialization Configuration">PEP 587</a> was <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2019-May/157721.html">accepted by Thomas Wouters on May 26, 2019</a>. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0587.rst">https://github.com/python/peps/blob/main/peps/pep-0587.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0587.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#python-initialization-c-api">Python Initialization C API</a><ul> <li><a class="reference internal" href="#pywidestringlist">PyWideStringList</a></li> <li><a class="reference internal" href="#pystatus">PyStatus</a></li> <li><a class="reference internal" href="#preinitialization-with-pypreconfig">Preinitialization with PyPreConfig</a></li> <li><a class="reference internal" href="#initialization-with-pyconfig">Initialization with PyConfig</a></li> <li><a class="reference internal" href="#isolated-configuration">Isolated Configuration</a></li> <li><a class="reference internal" href="#python-configuration">Python Configuration</a></li> <li><a class="reference internal" href="#path-configuration">Path Configuration</a></li> <li><a class="reference internal" href="#py-bytesmain">Py_BytesMain()</a></li> <li><a class="reference internal" href="#py-runmain">Py_RunMain()</a></li> <li><a class="reference internal" href="#multi-phase-initialization-private-provisional-api">Multi-Phase Initialization Private Provisional API</a></li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#annexes">Annexes</a><ul> <li><a class="reference internal" href="#comparison-of-python-and-isolated-configurations">Comparison of Python and Isolated Configurations</a></li> <li><a class="reference internal" href="#priority-and-rules">Priority and Rules</a></li> <li><a class="reference internal" href="#configuration-files">Configuration Files</a></li> <li><a class="reference internal" href="#global-configuration-variables">Global Configuration Variables</a></li> <li><a class="reference internal" href="#command-line-arguments">Command Line Arguments</a></li> <li><a class="reference internal" href="#x-options">-X Options</a></li> <li><a class="reference internal" href="#environment-variables">Environment Variables</a></li> <li><a class="reference internal" href="#default-python-configuration">Default Python Configuration</a></li> <li><a class="reference internal" href="#default-isolated-configuration">Default Isolated Configuration</a></li> <li><a class="reference internal" href="#python-3-7-api">Python 3.7 API</a></li> </ul> </li> <li><a class="reference internal" href="#python-issues">Python Issues</a></li> <li><a class="reference internal" href="#discussions">Discussions</a></li> <li><a class="reference internal" href="#version-history">Version History</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0587.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>