Python Initialization Configuration
***********************************
-.. _pyconfig_api:
-
-PyConfig C API
-==============
-.. versionadded:: 3.8
-
-Python can be initialized with :c:func:`Py_InitializeFromConfig` and the
-:c:type:`PyConfig` structure. It can be preinitialized with
-:c:func:`Py_PreInitialize` and the :c:type:`PyPreConfig` structure.
+.. _pyinitconfig_api:
-There are two kinds of configuration:
+PyInitConfig C API
+==================
-* The :ref:`Python Configuration <init-python-config>` can be used to build a
- customized Python which behaves as the regular Python. For example,
- environment variables and command line arguments are used to configure
- Python.
+.. versionadded:: 3.14
-* The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
- Python into an application. It isolates Python from the system. For example,
- environment variables are ignored, the LC_CTYPE locale is left unchanged and
- no signal handler is registered.
+Python can be initialized with :c:func:`Py_InitializeFromInitConfig`.
The :c:func:`Py_RunMain` function can be used to write a customized Python
program.
See also :ref:`Initialization, Finalization, and Threads <initialization>`.
.. seealso::
- :pep:`587` "Python Initialization Configuration".
+ :pep:`741` "Python Configuration C API".
Example
-------
-Example of customized Python always running in isolated mode::
-
- int main(int argc, char **argv)
- {
- PyStatus status;
+Example of customized Python always running with the :ref:`Python Development
+Mode <devmode>` enabled; return ``-1`` on error:
- PyConfig config;
- PyConfig_InitPythonConfig(&config);
- config.isolated = 1;
+.. code-block:: c
- /* Decode command line arguments.
- Implicitly preinitialize Python (in isolated mode). */
- status = PyConfig_SetBytesArgv(&config, argc, argv);
- if (PyStatus_Exception(status)) {
- goto exception;
+ int init_python(void)
+ {
+ PyInitConfig *config = PyInitConfig_Create();
+ if (config == NULL) {
+ printf("PYTHON INIT ERROR: memory allocation failed\n");
+ return -1;
}
- status = Py_InitializeFromConfig(&config);
- if (PyStatus_Exception(status)) {
- goto exception;
+ // Enable the Python Development Mode
+ if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
+ goto error;
}
- PyConfig_Clear(&config);
- return Py_RunMain();
+ // Initialize Python with the configuration
+ if (Py_InitializeFromInitConfig(config) < 0) {
+ goto error;
+ }
+ PyInitConfig_Free(config);
+ return 0;
- exception:
- PyConfig_Clear(&config);
- if (PyStatus_IsExit(status)) {
- return status.exitcode;
+ error:
+ {
+ // Display the error message.
+ //
+ // This uncommon braces style is used, because you cannot make
+ // goto targets point to variable declarations.
+ const char *err_msg;
+ (void)PyInitConfig_GetError(config, &err_msg);
+ printf("PYTHON INIT ERROR: %s\n", err_msg);
+ PyInitConfig_Free(config);
+ return -1;
}
- /* Display the error message and exit the process with
- non-zero exit code */
- Py_ExitStatusException(status);
}
+Create Config
+-------------
-PyWideStringList
-----------------
+.. c:struct:: PyInitConfig
-.. c:type:: PyWideStringList
+ Opaque structure to configure the Python initialization.
- List of ``wchar_t*`` strings.
- If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
- non-``NULL``.
+.. c:function:: PyInitConfig* PyInitConfig_Create(void)
- .. c:namespace:: NULL
+ Create a new initialization configuration using :ref:`Isolated Configuration
+ <init-isolated-conf>` default values.
- Methods:
+ It must be freed by :c:func:`PyInitConfig_Free`.
- .. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
+ Return ``NULL`` on memory allocation failure.
- Append *item* to *list*.
- Python must be preinitialized to call this function.
+.. c:function:: void PyInitConfig_Free(PyInitConfig *config)
- .. c:function:: PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)
+ Free memory of the initialization configuration *config*.
- Insert *item* into *list* at *index*.
+ If *config* is ``NULL``, no operation is performed.
- If *index* is greater than or equal to *list* length, append *item* to
- *list*.
- *index* must be greater than or equal to ``0``.
+Error Handling
+--------------
- Python must be preinitialized to call this function.
+.. c:function:: int PyInitConfig_GetError(PyInitConfig* config, const char **err_msg)
- .. c:namespace:: PyWideStringList
+ Get the *config* error message.
- Structure fields:
+ * Set *\*err_msg* and return ``1`` if an error is set.
+ * Set *\*err_msg* to ``NULL`` and return ``0`` otherwise.
- .. c:member:: Py_ssize_t length
+ An error message is an UTF-8 encoded string.
- List length.
+ If *config* has an exit code, format the exit code as an error
+ message.
- .. c:member:: wchar_t** items
+ The error message remains valid until another ``PyInitConfig``
+ function is called with *config*. The caller doesn't have to free the
+ error message.
- List items.
-PyStatus
---------
+.. c:function:: int PyInitConfig_GetExitCode(PyInitConfig* config, int *exitcode)
-.. c:type:: PyStatus
+ Get the *config* exit code.
- Structure to store an initialization function status: success, error
- or exit.
+ * Set *\*exitcode* and return ``1`` if *config* has an exit code set.
+ * Return ``0`` if *config* has no exit code set.
- For an error, it can store the C function name which created the error.
+ Only the ``Py_InitializeFromInitConfig()`` function can set an exit
+ code if the ``parse_argv`` option is non-zero.
- Structure fields:
+ An exit code can be set when parsing the command line failed (exit
+ code ``2``) or when a command line option asks to display the command
+ line help (exit code ``0``).
- .. c:member:: int exitcode
- Exit code. Argument passed to ``exit()``.
+Get Options
+-----------
- .. c:member:: const char *err_msg
+The configuration option *name* parameter must be a non-NULL
+null-terminated UTF-8 encoded string.
- Error message.
+.. c:function:: int PyInitConfig_HasOption(PyInitConfig *config, const char *name)
- .. c:member:: const char *func
+ Test if the configuration has an option called *name*.
- Name of the function which created an error, can be ``NULL``.
+ Return ``1`` if the option exists, or return ``0`` otherwise.
- .. c:namespace:: NULL
- Functions to create a status:
+.. c:function:: int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)
- .. c:function:: PyStatus PyStatus_Ok(void)
+ Get an integer configuration option.
- Success.
+ * Set *\*value*, and return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- .. c:function:: PyStatus PyStatus_Error(const char *err_msg)
- Initialization error with a message.
+.. c:function:: int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)
- *err_msg* must not be ``NULL``.
+ Get a string configuration option as a null-terminated UTF-8
+ encoded string.
- .. c:function:: PyStatus PyStatus_NoMemory(void)
+ * Set *\*value*, and return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- Memory allocation failure (out of memory).
+ *\*value* can be set to ``NULL`` if the option is an optional string and the
+ option is unset.
- .. c:function:: PyStatus PyStatus_Exit(int exitcode)
+ On success, the string must be released with ``free(value)`` if it's not
+ ``NULL``.
- Exit Python with the specified exit code.
- Functions to handle a status:
+.. c:function:: int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)
- .. c:function:: int PyStatus_Exception(PyStatus status)
+ Get a string list configuration option as an array of
+ null-terminated UTF-8 encoded strings.
- Is the status an error or an exit? If true, the exception must be
- handled; by calling :c:func:`Py_ExitStatusException` for example.
+ * Set *\*length* and *\*value*, and return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- .. c:function:: int PyStatus_IsError(PyStatus status)
+ On success, the string list must be released with
+ ``PyInitConfig_FreeStrList(length, items)``.
- Is the result an error?
- .. c:function:: int PyStatus_IsExit(PyStatus status)
+.. c:function:: void PyInitConfig_FreeStrList(size_t length, char **items)
- Is the result an exit?
+ Free memory of a string list created by
+ ``PyInitConfig_GetStrList()``.
- .. c:function:: void Py_ExitStatusException(PyStatus status)
- Call ``exit(exitcode)`` if *status* is an exit. Print the error
- message and exit with a non-zero exit code if *status* is an error. Must
- only be called if ``PyStatus_Exception(status)`` is non-zero.
+Set Options
+-----------
-.. note::
- Internally, Python uses macros which set ``PyStatus.func``,
- whereas functions to create a status set ``func`` to ``NULL``.
+The configuration option *name* parameter must be a non-NULL null-terminated
+UTF-8 encoded string.
-Example::
+Some configuration options have side effects on other options. This logic is
+only implemented when ``Py_InitializeFromInitConfig()`` is called, not by the
+"Set" functions below. For example, setting ``dev_mode`` to ``1`` does not set
+``faulthandler`` to ``1``.
- PyStatus alloc(void **ptr, size_t size)
- {
- *ptr = PyMem_RawMalloc(size);
- if (*ptr == NULL) {
- return PyStatus_NoMemory();
- }
- return PyStatus_Ok();
- }
+.. c:function:: int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)
- 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;
- }
+ Set an integer configuration option.
+ * Return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
-PyPreConfig
------------
-.. c:type:: PyPreConfig
+.. c:function:: int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)
- Structure used to preinitialize Python.
+ Set a string configuration option from a null-terminated UTF-8
+ encoded string. The string is copied.
- .. c:namespace:: NULL
+ * Return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- Function to initialize a preconfiguration:
- .. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
+.. c:function:: int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char * const *items)
- Initialize the preconfiguration with :ref:`Python Configuration
- <init-python-config>`.
+ Set a string list configuration option from an array of
+ null-terminated UTF-8 encoded strings. The string list is copied.
- .. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
+ * Return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- Initialize the preconfiguration with :ref:`Isolated Configuration
- <init-isolated-conf>`.
- .. c:namespace:: PyPreConfig
+Module
+------
- Structure fields:
+.. c:function:: int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject* (*initfunc)(void))
- .. c:member:: int allocator
-
- Name of the Python memory allocators:
+ Add a built-in extension module to the table of built-in modules.
- * ``PYMEM_ALLOCATOR_NOT_SET`` (``0``): don't change memory allocators
- (use defaults).
- * ``PYMEM_ALLOCATOR_DEFAULT`` (``1``): :ref:`default memory allocators
- <default-memory-allocators>`.
- * ``PYMEM_ALLOCATOR_DEBUG`` (``2``): :ref:`default memory allocators
- <default-memory-allocators>` with :ref:`debug hooks
- <pymem-debug-hooks>`.
- * ``PYMEM_ALLOCATOR_MALLOC`` (``3``): use ``malloc()`` of the C library.
- * ``PYMEM_ALLOCATOR_MALLOC_DEBUG`` (``4``): force usage of
- ``malloc()`` with :ref:`debug hooks <pymem-debug-hooks>`.
- * ``PYMEM_ALLOCATOR_PYMALLOC`` (``5``): :ref:`Python pymalloc memory
- allocator <pymalloc>`.
- * ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc
- memory allocator <pymalloc>` with :ref:`debug hooks
- <pymem-debug-hooks>`.
- * ``PYMEM_ALLOCATOR_MIMALLOC`` (``6``): use ``mimalloc``, a fast
- malloc replacement.
- * ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` (``7``): use ``mimalloc``, a fast
- malloc replacement with :ref:`debug hooks <pymem-debug-hooks>`.
+ The new module can be imported by the name *name*, and uses the function
+ *initfunc* as the initialization function called on the first attempted
+ import.
+ * Return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
- ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
- not supported if Python is :option:`configured using --without-pymalloc
- <--without-pymalloc>`.
+ If Python is initialized multiple times, ``PyInitConfig_AddModule()`` must
+ be called at each Python initialization.
- ``PYMEM_ALLOCATOR_MIMALLOC`` and ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` are
- not supported if Python is :option:`configured using --without-mimalloc
- <--without-mimalloc>` or if the underlying atomic support isn't
- available.
+ Similar to the :c:func:`PyImport_AppendInittab` function.
- See :ref:`Memory Management <memory>`.
- Default: ``PYMEM_ALLOCATOR_NOT_SET``.
+Initialize Python
+-----------------
- .. c:member:: int configure_locale
+.. c:function:: int Py_InitializeFromInitConfig(PyInitConfig *config)
- Set the LC_CTYPE locale to the user preferred locale.
+ Initialize Python from the initialization configuration.
- If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
- :c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.
+ * Return ``0`` on success.
+ * Set an error in *config* and return ``-1`` on error.
+ * Set an exit code in *config* and return ``-1`` if Python wants to
+ exit.
- See the :term:`locale encoding`.
+ See ``PyInitConfig_GetExitcode()`` for the exit code case.
- Default: ``1`` in Python config, ``0`` in isolated config.
- .. c:member:: int coerce_c_locale
+Runtime Python configuration API
+================================
- If equals to ``2``, coerce the C locale.
+At runtime, it's possible to get and set configuration options using
+:c:func:`PyConfig_Get` and :c:func:`PyConfig_Set` functions.
- If equals to ``1``, read the LC_CTYPE locale to decide if it should be
- coerced.
+The configuration option *name* parameter must be a non-NULL null-terminated
+UTF-8 encoded string.
- See the :term:`locale encoding`.
+Some options are read from the :mod:`sys` attributes. For example, the option
+``"argv"`` is read from :data:`sys.argv`.
- Default: ``-1`` in Python config, ``0`` in isolated config.
- .. c:member:: int coerce_c_locale_warn
+.. c:function:: PyObject* PyConfig_Get(const char *name)
- If non-zero, emit a warning if the C locale is coerced.
+ Get the current runtime value of a configuration option as a Python object.
- Default: ``-1`` in Python config, ``0`` in isolated config.
+ * Return a new reference on success.
+ * Set an exception and return ``NULL`` on error.
- .. c:member:: int dev_mode
+ The object type depends on the configuration option. It can be:
- :ref:`Python Development Mode <devmode>`: see
- :c:member:`PyConfig.dev_mode`.
+ * ``bool``
+ * ``int``
+ * ``str``
+ * ``list[str]``
+ * ``dict[str, str]``
- Default: ``-1`` in Python mode, ``0`` in isolated mode.
+ The caller must hold the GIL. The function cannot be called before
+ Python initialization nor after Python finalization.
- .. c:member:: int isolated
+ .. versionadded:: 3.14
- Isolated mode: see :c:member:`PyConfig.isolated`.
- Default: ``0`` in Python mode, ``1`` in isolated mode.
+.. c:function:: int PyConfig_GetInt(const char *name, int *value)
- .. c:member:: int legacy_windows_fs_encoding
+ Similar to :c:func:`PyConfig_Get`, but get the value as a C int.
- If non-zero:
+ * Return ``0`` on success.
+ * Set an exception and return ``-1`` on error.
- * Set :c:member:`PyPreConfig.utf8_mode` to ``0``,
- * Set :c:member:`PyConfig.filesystem_encoding` to ``"mbcs"``,
- * Set :c:member:`PyConfig.filesystem_errors` to ``"replace"``.
+ .. versionadded:: 3.14
- Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
- variable value.
- Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
- Windows specific code.
+.. c:function:: PyObject* PyConfig_Names(void)
- Default: ``0``.
+ Get all configuration option names as a ``frozenset``.
- .. c:member:: int parse_argv
+ * Return a new reference on success.
+ * Set an exception and return ``NULL`` on error.
- If non-zero, :c:func:`Py_PreInitializeFromArgs` and
- :c:func:`Py_PreInitializeFromBytesArgs` parse their ``argv`` argument the
- same way the regular Python parses command line arguments: see
- :ref:`Command Line Arguments <using-on-cmdline>`.
+ The caller must hold the GIL. The function cannot be called before
+ Python initialization nor after Python finalization.
- Default: ``1`` in Python config, ``0`` in isolated config.
+ .. versionadded:: 3.14
- .. c:member:: int use_environment
- Use :ref:`environment variables <using-on-envvars>`? See
- :c:member:`PyConfig.use_environment`.
+.. c:function:: int PyConfig_Set(const char *name, PyObject *value)
- Default: ``1`` in Python config and ``0`` in isolated config.
+ Set the current runtime value of a configuration option.
- .. c:member:: int utf8_mode
+ * Raise a :exc:`ValueError` if there is no option *name*.
+ * Raise a :exc:`ValueError` if *value* is an invalid value.
+ * Raise a :exc:`ValueError` if the option is read-only (cannot be set).
+ * Raise a :exc:`TypeError` if *value* has not the proper type.
- If non-zero, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
+ The caller must hold the GIL. The function cannot be called before
+ Python initialization nor after Python finalization.
- Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option
- and the :envvar:`PYTHONUTF8` environment variable.
+ .. versionadded:: 3.14
- Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``.
- Default: ``-1`` in Python config and ``0`` in isolated config.
+.. _pyconfig_api:
+PyConfig C API
+==============
-.. _c-preinit:
+.. versionadded:: 3.8
-Preinitialize Python with PyPreConfig
--------------------------------------
+Python can be initialized with :c:func:`Py_InitializeFromConfig` and the
+:c:type:`PyConfig` structure. It can be preinitialized with
+:c:func:`Py_PreInitialize` and the :c:type:`PyPreConfig` structure.
-The preinitialization of Python:
+There are two kinds of configuration:
-* Set the Python memory allocators (:c:member:`PyPreConfig.allocator`)
-* Configure the LC_CTYPE locale (:term:`locale encoding`)
-* Set the :ref:`Python UTF-8 Mode <utf8-mode>`
- (:c:member:`PyPreConfig.utf8_mode`)
+* The :ref:`Python Configuration <init-python-config>` can be used to build a
+ customized Python which behaves as the regular Python. For example,
+ environment variables and command line arguments are used to configure
+ Python.
-The current preconfiguration (``PyPreConfig`` type) is stored in
-``_PyRuntime.preconfig``.
+* The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
+ Python into an application. It isolates Python from the system. For example,
+ environment variables are ignored, the LC_CTYPE locale is left unchanged and
+ no signal handler is registered.
-Functions to preinitialize Python:
+The :c:func:`Py_RunMain` function can be used to write a customized Python
+program.
-.. c:function:: PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
+See also :ref:`Initialization, Finalization, and Threads <initialization>`.
- Preinitialize Python from *preconfig* preconfiguration.
+.. seealso::
+ :pep:`587` "Python Initialization Configuration".
- *preconfig* must not be ``NULL``.
-.. c:function:: PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)
+Example
+-------
- Preinitialize Python from *preconfig* preconfiguration.
+Example of customized Python always running in isolated mode::
- Parse *argv* command line arguments (bytes strings) if
- :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
+ int main(int argc, char **argv)
+ {
+ PyStatus status;
- *preconfig* must not be ``NULL``.
+ PyConfig config;
+ PyConfig_InitPythonConfig(&config);
+ config.isolated = 1;
-.. c:function:: PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)
+ /* Decode command line arguments.
+ Implicitly preinitialize Python (in isolated mode). */
+ status = PyConfig_SetBytesArgv(&config, argc, argv);
+ if (PyStatus_Exception(status)) {
+ goto exception;
+ }
- Preinitialize Python from *preconfig* preconfiguration.
+ status = Py_InitializeFromConfig(&config);
+ if (PyStatus_Exception(status)) {
+ goto exception;
+ }
+ PyConfig_Clear(&config);
- Parse *argv* command line arguments (wide strings) if
- :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
+ return Py_RunMain();
- *preconfig* must not be ``NULL``.
+ exception:
+ 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);
+ }
-The caller is responsible to handle exceptions (error or exit) using
-:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
-For :ref:`Python Configuration <init-python-config>`
-(:c:func:`PyPreConfig_InitPythonConfig`), if Python is initialized with
-command line arguments, the command line arguments must also be passed to
-preinitialize Python, since they have an effect on the pre-configuration
-like encodings. For example, the :option:`-X utf8 <-X>` command line option
-enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
+PyWideStringList
+----------------
-``PyMem_SetAllocator()`` can be called after :c:func:`Py_PreInitialize` and
-before :c:func:`Py_InitializeFromConfig` to install a custom memory allocator.
-It can be called before :c:func:`Py_PreInitialize` if
-:c:member:`PyPreConfig.allocator` is set to ``PYMEM_ALLOCATOR_NOT_SET``.
+.. c:type:: PyWideStringList
-Python memory allocation functions like :c:func:`PyMem_RawMalloc` must not be
-used before the Python preinitialization, whereas calling directly ``malloc()``
-and ``free()`` is always safe. :c:func:`Py_DecodeLocale` must not be called
-before the Python preinitialization.
+ List of ``wchar_t*`` strings.
-Example using the preinitialization to enable
-the :ref:`Python UTF-8 Mode <utf8-mode>`::
+ If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
+ non-``NULL``.
- PyStatus status;
- PyPreConfig preconfig;
- PyPreConfig_InitPythonConfig(&preconfig);
+ .. c:namespace:: NULL
- preconfig.utf8_mode = 1;
+ Methods:
- status = Py_PreInitialize(&preconfig);
- if (PyStatus_Exception(status)) {
- Py_ExitStatusException(status);
- }
+ .. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
- /* at this point, Python speaks UTF-8 */
+ Append *item* to *list*.
- Py_Initialize();
- /* ... use Python API here ... */
- Py_Finalize();
+ Python must be preinitialized to call this function.
+ .. c:function:: PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)
-PyConfig
---------
+ Insert *item* into *list* at *index*.
-.. c:type:: PyConfig
+ If *index* is greater than or equal to *list* length, append *item* to
+ *list*.
- Structure containing most parameters to configure Python.
+ *index* must be greater than or equal to ``0``.
- When done, the :c:func:`PyConfig_Clear` function must be used to release the
- configuration memory.
+ Python must be preinitialized to call this function.
- .. c:namespace:: NULL
+ .. c:namespace:: PyWideStringList
- Structure methods:
+ Structure fields:
- .. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
+ .. c:member:: Py_ssize_t length
- Initialize configuration with the :ref:`Python Configuration
- <init-python-config>`.
+ List length.
- .. c:function:: void PyConfig_InitIsolatedConfig(PyConfig *config)
+ .. c:member:: wchar_t** items
- Initialize configuration with the :ref:`Isolated Configuration
- <init-isolated-conf>`.
+ List items.
- .. c:function:: PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)
+PyStatus
+--------
- Copy the wide character string *str* into ``*config_str``.
+.. c:type:: PyStatus
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ Structure to store an initialization function status: success, error
+ or exit.
- .. c:function:: PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t * const *config_str, const char *str)
+ For an error, it can store the C function name which created the error.
- Decode *str* using :c:func:`Py_DecodeLocale` and set the result into
- ``*config_str``.
+ Structure fields:
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ .. c:member:: int exitcode
- .. c:function:: PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)
+ Exit code. Argument passed to ``exit()``.
- Set command line arguments (:c:member:`~PyConfig.argv` member of
- *config*) from the *argv* list of wide character strings.
+ .. c:member:: const char *err_msg
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ Error message.
- .. c:function:: PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)
+ .. c:member:: const char *func
- Set command line arguments (:c:member:`~PyConfig.argv` member of
- *config*) from the *argv* list of bytes strings. Decode bytes using
- :c:func:`Py_DecodeLocale`.
+ Name of the function which created an error, can be ``NULL``.
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ .. c:namespace:: NULL
- .. c:function:: PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)
+ Functions to create a status:
- Set the list of wide strings *list* to *length* and *items*.
+ .. c:function:: PyStatus PyStatus_Ok(void)
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ Success.
- .. c:function:: PyStatus PyConfig_Read(PyConfig *config)
+ .. c:function:: PyStatus PyStatus_Error(const char *err_msg)
- Read all Python configuration.
+ Initialization error with a message.
- Fields which are already initialized are left unchanged.
+ *err_msg* must not be ``NULL``.
- Fields for :ref:`path configuration <init-path-config>` are no longer
- calculated or modified when calling this function, as of Python 3.11.
+ .. c:function:: PyStatus PyStatus_NoMemory(void)
- The :c:func:`PyConfig_Read` function only parses
- :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
- is set to ``2`` after arguments are parsed. Since Python arguments are
- stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
- parse the application options as Python options.
+ Memory allocation failure (out of memory).
- :ref:`Preinitialize Python <c-preinit>` if needed.
+ .. c:function:: PyStatus PyStatus_Exit(int exitcode)
- .. versionchanged:: 3.10
- The :c:member:`PyConfig.argv` arguments are now only parsed once,
- :c:member:`PyConfig.parse_argv` is set to ``2`` after arguments are
- parsed, and arguments are only parsed if
- :c:member:`PyConfig.parse_argv` equals ``1``.
+ Exit Python with the specified exit code.
- .. versionchanged:: 3.11
- :c:func:`PyConfig_Read` no longer calculates all paths, and so fields
- listed under :ref:`Python Path Configuration <init-path-config>` may
- no longer be updated until :c:func:`Py_InitializeFromConfig` is
- called.
+ Functions to handle a status:
- .. c:function:: void PyConfig_Clear(PyConfig *config)
+ .. c:function:: int PyStatus_Exception(PyStatus status)
- Release configuration memory.
+ Is the status an error or an exit? If true, the exception must be
+ handled; by calling :c:func:`Py_ExitStatusException` for example.
- Most ``PyConfig`` methods :ref:`preinitialize Python <c-preinit>` if needed.
- In that case, the Python preinitialization configuration
- (:c:type:`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration
- fields which are in common with :c:type:`PyPreConfig` are tuned, they must
- be set before calling a :c:type:`PyConfig` method:
+ .. c:function:: int PyStatus_IsError(PyStatus status)
- * :c:member:`PyConfig.dev_mode`
- * :c:member:`PyConfig.isolated`
- * :c:member:`PyConfig.parse_argv`
- * :c:member:`PyConfig.use_environment`
+ Is the result an error?
- Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv`
- is used, this method must be called before other methods, since the
- preinitialization configuration depends on command line arguments (if
- :c:member:`~PyConfig.parse_argv` is non-zero).
+ .. c:function:: int PyStatus_IsExit(PyStatus status)
- The caller of these methods is responsible to handle exceptions (error or
- exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
+ Is the result an exit?
- .. c:namespace:: PyConfig
+ .. c:function:: void Py_ExitStatusException(PyStatus status)
- Structure fields:
+ Call ``exit(exitcode)`` if *status* is an exit. Print the error
+ message and exit with a non-zero exit code if *status* is an error. Must
+ only be called if ``PyStatus_Exception(status)`` is non-zero.
- .. c:member:: PyWideStringList argv
+.. note::
+ Internally, Python uses macros which set ``PyStatus.func``,
+ whereas functions to create a status set ``func`` to ``NULL``.
- .. index::
- single: main()
- single: argv (in module sys)
+Example::
- Set :data:`sys.argv` command line arguments based on
- :c:member:`~PyConfig.argv`. These parameters are similar to those passed
- to the program's :c:func:`main` function with the difference that the
- first entry should refer to the script file to be executed rather than
- the executable hosting the Python interpreter. If there isn't a script
- that will be run, the first entry in :c:member:`~PyConfig.argv` can be an
- empty string.
+ PyStatus alloc(void **ptr, size_t size)
+ {
+ *ptr = PyMem_RawMalloc(size);
+ if (*ptr == NULL) {
+ return PyStatus_NoMemory();
+ }
+ return PyStatus_Ok();
+ }
- Set :c:member:`~PyConfig.parse_argv` to ``1`` to parse
- :c:member:`~PyConfig.argv` the same way the regular Python parses Python
- command line arguments and then to strip Python arguments from
- :c:member:`~PyConfig.argv`.
+ 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;
+ }
- If :c:member:`~PyConfig.argv` is empty, an empty string is added to
- ensure that :data:`sys.argv` always exists and is never empty.
- Default: ``NULL``.
+PyPreConfig
+-----------
- See also the :c:member:`~PyConfig.orig_argv` member.
+.. c:type:: PyPreConfig
- .. c:member:: int safe_path
+ Structure used to preinitialize Python.
- If equals to zero, ``Py_RunMain()`` prepends a potentially unsafe path to
- :data:`sys.path` at startup:
+ .. c:namespace:: NULL
- * If :c:member:`argv[0] <PyConfig.argv>` is equal to ``L"-m"``
- (``python -m module``), prepend the current working directory.
- * If running a script (``python script.py``), prepend the script's
- directory. If it's a symbolic link, resolve symbolic links.
- * Otherwise (``python -c code`` and ``python``), prepend an empty string,
- which means the current working directory.
+ Function to initialize a preconfiguration:
- Set to ``1`` by the :option:`-P` command line option and the
- :envvar:`PYTHONSAFEPATH` environment variable.
+ .. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
- Default: ``0`` in Python config, ``1`` in isolated config.
+ Initialize the preconfiguration with :ref:`Python Configuration
+ <init-python-config>`.
- .. versionadded:: 3.11
+ .. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
- .. c:member:: wchar_t* base_exec_prefix
+ Initialize the preconfiguration with :ref:`Isolated Configuration
+ <init-isolated-conf>`.
- :data:`sys.base_exec_prefix`.
+ .. c:namespace:: PyPreConfig
- Default: ``NULL``.
+ Structure fields:
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ .. c:member:: int allocator
- See also :c:member:`PyConfig.exec_prefix`.
+ Name of the Python memory allocators:
- .. c:member:: wchar_t* base_executable
+ * ``PYMEM_ALLOCATOR_NOT_SET`` (``0``): don't change memory allocators
+ (use defaults).
+ * ``PYMEM_ALLOCATOR_DEFAULT`` (``1``): :ref:`default memory allocators
+ <default-memory-allocators>`.
+ * ``PYMEM_ALLOCATOR_DEBUG`` (``2``): :ref:`default memory allocators
+ <default-memory-allocators>` with :ref:`debug hooks
+ <pymem-debug-hooks>`.
+ * ``PYMEM_ALLOCATOR_MALLOC`` (``3``): use ``malloc()`` of the C library.
+ * ``PYMEM_ALLOCATOR_MALLOC_DEBUG`` (``4``): force usage of
+ ``malloc()`` with :ref:`debug hooks <pymem-debug-hooks>`.
+ * ``PYMEM_ALLOCATOR_PYMALLOC`` (``5``): :ref:`Python pymalloc memory
+ allocator <pymalloc>`.
+ * ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc
+ memory allocator <pymalloc>` with :ref:`debug hooks
+ <pymem-debug-hooks>`.
+ * ``PYMEM_ALLOCATOR_MIMALLOC`` (``6``): use ``mimalloc``, a fast
+ malloc replacement.
+ * ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` (``7``): use ``mimalloc``, a fast
+ malloc replacement with :ref:`debug hooks <pymem-debug-hooks>`.
- Python base executable: :data:`sys._base_executable`.
- Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable.
+ ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
+ not supported if Python is :option:`configured using --without-pymalloc
+ <--without-pymalloc>`.
- Set from :c:member:`PyConfig.executable` if ``NULL``.
+ ``PYMEM_ALLOCATOR_MIMALLOC`` and ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` are
+ not supported if Python is :option:`configured using --without-mimalloc
+ <--without-mimalloc>` or if the underlying atomic support isn't
+ available.
- Default: ``NULL``.
+ See :ref:`Memory Management <memory>`.
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ Default: ``PYMEM_ALLOCATOR_NOT_SET``.
- See also :c:member:`PyConfig.executable`.
+ .. c:member:: int configure_locale
- .. c:member:: wchar_t* base_prefix
+ Set the LC_CTYPE locale to the user preferred locale.
- :data:`sys.base_prefix`.
+ If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
+ :c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.
- Default: ``NULL``.
+ See the :term:`locale encoding`.
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ Default: ``1`` in Python config, ``0`` in isolated config.
- See also :c:member:`PyConfig.prefix`.
+ .. c:member:: int coerce_c_locale
- .. c:member:: int buffered_stdio
+ If equals to ``2``, coerce the C locale.
- If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero,
- disable buffering on the C streams stdout and stderr.
+ If equals to ``1``, read the LC_CTYPE locale to decide if it should be
+ coerced.
- Set to ``0`` by the :option:`-u` command line option and the
- :envvar:`PYTHONUNBUFFERED` environment variable.
+ See the :term:`locale encoding`.
- stdin is always opened in buffered mode.
+ Default: ``-1`` in Python config, ``0`` in isolated config.
- Default: ``1``.
+ .. c:member:: int coerce_c_locale_warn
- .. c:member:: int bytes_warning
+ If non-zero, emit a warning if the C locale is coerced.
- If equals to ``1``, issue a warning when comparing :class:`bytes` or
- :class:`bytearray` with :class:`str`, or comparing :class:`bytes` with
- :class:`int`.
-
- If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these
- cases.
-
- Incremented by the :option:`-b` command line option.
+ Default: ``-1`` in Python config, ``0`` in isolated config.
- Default: ``0``.
+ .. c:member:: int dev_mode
- .. c:member:: int warn_default_encoding
+ :ref:`Python Development Mode <devmode>`: see
+ :c:member:`PyConfig.dev_mode`.
- If non-zero, emit a :exc:`EncodingWarning` warning when :class:`io.TextIOWrapper`
- uses its default encoding. See :ref:`io-encoding-warning` for details.
+ Default: ``-1`` in Python mode, ``0`` in isolated mode.
- Default: ``0``.
+ .. c:member:: int isolated
- .. versionadded:: 3.10
+ Isolated mode: see :c:member:`PyConfig.isolated`.
- .. c:member:: int code_debug_ranges
+ Default: ``0`` in Python mode, ``1`` in isolated mode.
- If equals to ``0``, disables the inclusion of the end line and column
- mappings in code objects. Also disables traceback printing carets to
- specific error locations.
+ .. c:member:: int legacy_windows_fs_encoding
- Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable
- and by the :option:`-X no_debug_ranges <-X>` command line option.
+ If non-zero:
- Default: ``1``.
+ * Set :c:member:`PyPreConfig.utf8_mode` to ``0``,
+ * Set :c:member:`PyConfig.filesystem_encoding` to ``"mbcs"``,
+ * Set :c:member:`PyConfig.filesystem_errors` to ``"replace"``.
- .. versionadded:: 3.11
+ Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
+ variable value.
- .. c:member:: wchar_t* check_hash_pycs_mode
+ Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
+ Windows specific code.
- Control the validation behavior of hash-based ``.pyc`` files:
- value of the :option:`--check-hash-based-pycs` command line option.
+ Default: ``0``.
- Valid values:
+ .. c:member:: int parse_argv
- - ``L"always"``: Hash the source file for invalidation regardless of
- value of the 'check_source' flag.
- - ``L"never"``: Assume that hash-based pycs always are valid.
- - ``L"default"``: The 'check_source' flag in hash-based pycs
- determines invalidation.
+ If non-zero, :c:func:`Py_PreInitializeFromArgs` and
+ :c:func:`Py_PreInitializeFromBytesArgs` parse their ``argv`` argument the
+ same way the regular Python parses command line arguments: see
+ :ref:`Command Line Arguments <using-on-cmdline>`.
- Default: ``L"default"``.
+ Default: ``1`` in Python config, ``0`` in isolated config.
- See also :pep:`552` "Deterministic pycs".
+ .. c:member:: int use_environment
- .. c:member:: int configure_c_stdio
+ Use :ref:`environment variables <using-on-envvars>`? See
+ :c:member:`PyConfig.use_environment`.
- If non-zero, configure C standard streams:
+ Default: ``1`` in Python config and ``0`` in isolated config.
- * On Windows, set the binary mode (``O_BINARY``) on stdin, stdout and
- stderr.
- * If :c:member:`~PyConfig.buffered_stdio` equals zero, disable buffering
- of stdin, stdout and stderr streams.
- * If :c:member:`~PyConfig.interactive` is non-zero, enable stream
- buffering on stdin and stdout (only stdout on Windows).
+ .. c:member:: int utf8_mode
- Default: ``1`` in Python config, ``0`` in isolated config.
+ If non-zero, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
- .. c:member:: int dev_mode
+ Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option
+ and the :envvar:`PYTHONUTF8` environment variable.
- If non-zero, enable the :ref:`Python Development Mode <devmode>`.
+ Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``.
- Set to ``1`` by the :option:`-X dev <-X>` option and the
- :envvar:`PYTHONDEVMODE` environment variable.
+ Default: ``-1`` in Python config and ``0`` in isolated config.
- Default: ``-1`` in Python mode, ``0`` in isolated mode.
- .. c:member:: int dump_refs
+.. _c-preinit:
- Dump Python references?
+Preinitialize Python with PyPreConfig
+-------------------------------------
- If non-zero, dump all objects which are still alive at exit.
+The preinitialization of Python:
- Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable.
+* Set the Python memory allocators (:c:member:`PyPreConfig.allocator`)
+* Configure the LC_CTYPE locale (:term:`locale encoding`)
+* Set the :ref:`Python UTF-8 Mode <utf8-mode>`
+ (:c:member:`PyPreConfig.utf8_mode`)
- Needs a special build of Python with the ``Py_TRACE_REFS`` macro defined:
- see the :option:`configure --with-trace-refs option <--with-trace-refs>`.
+The current preconfiguration (``PyPreConfig`` type) is stored in
+``_PyRuntime.preconfig``.
- Default: ``0``.
+Functions to preinitialize Python:
- .. c:member:: wchar_t* exec_prefix
+.. c:function:: PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
- The site-specific directory prefix where the platform-dependent Python
- files are installed: :data:`sys.exec_prefix`.
+ Preinitialize Python from *preconfig* preconfiguration.
- Default: ``NULL``.
+ *preconfig* must not be ``NULL``.
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+.. c:function:: PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)
- See also :c:member:`PyConfig.base_exec_prefix`.
+ Preinitialize Python from *preconfig* preconfiguration.
- .. c:member:: wchar_t* executable
+ Parse *argv* command line arguments (bytes strings) if
+ :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
- The absolute path of the executable binary for the Python interpreter:
- :data:`sys.executable`.
+ *preconfig* must not be ``NULL``.
- Default: ``NULL``.
+.. c:function:: PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ Preinitialize Python from *preconfig* preconfiguration.
- See also :c:member:`PyConfig.base_executable`.
+ Parse *argv* command line arguments (wide strings) if
+ :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
- .. c:member:: int faulthandler
+ *preconfig* must not be ``NULL``.
- Enable faulthandler?
+The caller is responsible to handle exceptions (error or exit) using
+:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
- If non-zero, call :func:`faulthandler.enable` at startup.
+For :ref:`Python Configuration <init-python-config>`
+(:c:func:`PyPreConfig_InitPythonConfig`), if Python is initialized with
+command line arguments, the command line arguments must also be passed to
+preinitialize Python, since they have an effect on the pre-configuration
+like encodings. For example, the :option:`-X utf8 <-X>` command line option
+enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
- Set to ``1`` by :option:`-X faulthandler <-X>` and the
- :envvar:`PYTHONFAULTHANDLER` environment variable.
+``PyMem_SetAllocator()`` can be called after :c:func:`Py_PreInitialize` and
+before :c:func:`Py_InitializeFromConfig` to install a custom memory allocator.
+It can be called before :c:func:`Py_PreInitialize` if
+:c:member:`PyPreConfig.allocator` is set to ``PYMEM_ALLOCATOR_NOT_SET``.
- Default: ``-1`` in Python mode, ``0`` in isolated mode.
+Python memory allocation functions like :c:func:`PyMem_RawMalloc` must not be
+used before the Python preinitialization, whereas calling directly ``malloc()``
+and ``free()`` is always safe. :c:func:`Py_DecodeLocale` must not be called
+before the Python preinitialization.
- .. c:member:: wchar_t* filesystem_encoding
+Example using the preinitialization to enable
+the :ref:`Python UTF-8 Mode <utf8-mode>`::
- :term:`Filesystem encoding <filesystem encoding and error handler>`:
- :func:`sys.getfilesystemencoding`.
+ PyStatus status;
+ PyPreConfig preconfig;
+ PyPreConfig_InitPythonConfig(&preconfig);
- On macOS, Android and VxWorks: use ``"utf-8"`` by default.
+ preconfig.utf8_mode = 1;
- On Windows: use ``"utf-8"`` by default, or ``"mbcs"`` if
- :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
- :c:type:`PyPreConfig` is non-zero.
+ status = Py_PreInitialize(&preconfig);
+ if (PyStatus_Exception(status)) {
+ Py_ExitStatusException(status);
+ }
- Default encoding on other platforms:
+ /* at this point, Python speaks UTF-8 */
- * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
- * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
- the ASCII encoding, whereas the ``mbstowcs()`` function
- decodes from a different encoding (usually Latin1).
- * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
- * Otherwise, use the :term:`locale encoding`:
- ``nl_langinfo(CODESET)`` result.
+ Py_Initialize();
+ /* ... use Python API here ... */
+ Py_Finalize();
- At Python startup, the encoding name is normalized to the Python codec
- name. For example, ``"ANSI_X3.4-1968"`` is replaced with ``"ascii"``.
- See also the :c:member:`~PyConfig.filesystem_errors` member.
+PyConfig
+--------
- .. c:member:: wchar_t* filesystem_errors
+.. c:type:: PyConfig
- :term:`Filesystem error handler <filesystem encoding and error handler>`:
- :func:`sys.getfilesystemencodeerrors`.
+ Structure containing most parameters to configure Python.
- On Windows: use ``"surrogatepass"`` by default, or ``"replace"`` if
- :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
- :c:type:`PyPreConfig` is non-zero.
+ When done, the :c:func:`PyConfig_Clear` function must be used to release the
+ configuration memory.
- On other platforms: use ``"surrogateescape"`` by default.
+ .. c:namespace:: NULL
- Supported error handlers:
+ Structure methods:
- * ``"strict"``
- * ``"surrogateescape"``
- * ``"surrogatepass"`` (only supported with the UTF-8 encoding)
+ .. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
- See also the :c:member:`~PyConfig.filesystem_encoding` member.
+ Initialize configuration with the :ref:`Python Configuration
+ <init-python-config>`.
- .. c:member:: unsigned long hash_seed
- .. c:member:: int use_hash_seed
+ .. c:function:: void PyConfig_InitIsolatedConfig(PyConfig *config)
- Randomized hash function seed.
+ Initialize configuration with the :ref:`Isolated Configuration
+ <init-isolated-conf>`.
- If :c:member:`~PyConfig.use_hash_seed` is zero, a seed is chosen randomly
- at Python startup, and :c:member:`~PyConfig.hash_seed` is ignored.
+ .. c:function:: PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)
- Set by the :envvar:`PYTHONHASHSEED` environment variable.
+ Copy the wide character string *str* into ``*config_str``.
- Default *use_hash_seed* value: ``-1`` in Python mode, ``0`` in isolated
- mode.
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- .. c:member:: wchar_t* home
+ .. c:function:: PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t * const *config_str, const char *str)
- Set the default Python "home" directory, that is, the location of the
- standard Python libraries (see :envvar:`PYTHONHOME`).
+ Decode *str* using :c:func:`Py_DecodeLocale` and set the result into
+ ``*config_str``.
- Set by the :envvar:`PYTHONHOME` environment variable.
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- Default: ``NULL``.
+ .. c:function:: PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)
- Part of the :ref:`Python Path Configuration <init-path-config>` input.
+ Set command line arguments (:c:member:`~PyConfig.argv` member of
+ *config*) from the *argv* list of wide character strings.
- .. c:member:: int import_time
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- If non-zero, profile import time.
+ .. c:function:: PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)
- Set the ``1`` by the :option:`-X importtime <-X>` option and the
- :envvar:`PYTHONPROFILEIMPORTTIME` environment variable.
+ Set command line arguments (:c:member:`~PyConfig.argv` member of
+ *config*) from the *argv* list of bytes strings. Decode bytes using
+ :c:func:`Py_DecodeLocale`.
- Default: ``0``.
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- .. c:member:: int inspect
+ .. c:function:: PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)
- Enter interactive mode after executing a script or a command.
+ Set the list of wide strings *list* to *length* and *items*.
- If greater than ``0``, enable inspect: when a script is passed as first
- argument or the -c option is used, enter interactive mode after executing
- the script or the command, even when :data:`sys.stdin` does not appear to
- be a terminal.
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- Incremented by the :option:`-i` command line option. Set to ``1`` if the
- :envvar:`PYTHONINSPECT` environment variable is non-empty.
+ .. c:function:: PyStatus PyConfig_Read(PyConfig *config)
- Default: ``0``.
+ Read all Python configuration.
- .. c:member:: int install_signal_handlers
+ Fields which are already initialized are left unchanged.
- Install Python signal handlers?
+ Fields for :ref:`path configuration <init-path-config>` are no longer
+ calculated or modified when calling this function, as of Python 3.11.
- Default: ``1`` in Python mode, ``0`` in isolated mode.
-
- .. c:member:: int interactive
-
- If greater than ``0``, enable the interactive mode (REPL).
-
- Incremented by the :option:`-i` command line option.
+ The :c:func:`PyConfig_Read` function only parses
+ :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
+ is set to ``2`` after arguments are parsed. Since Python arguments are
+ stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
+ parse the application options as Python options.
- Default: ``0``.
+ :ref:`Preinitialize Python <c-preinit>` if needed.
- .. c:member:: int int_max_str_digits
+ .. versionchanged:: 3.10
+ The :c:member:`PyConfig.argv` arguments are now only parsed once,
+ :c:member:`PyConfig.parse_argv` is set to ``2`` after arguments are
+ parsed, and arguments are only parsed if
+ :c:member:`PyConfig.parse_argv` equals ``1``.
- Configures the :ref:`integer string conversion length limitation
- <int_max_str_digits>`. An initial value of ``-1`` means the value will
- be taken from the command line or environment or otherwise default to
- 4300 (:data:`sys.int_info.default_max_str_digits`). A value of ``0``
- disables the limitation. Values greater than zero but less than 640
- (:data:`sys.int_info.str_digits_check_threshold`) are unsupported and
- will produce an error.
+ .. versionchanged:: 3.11
+ :c:func:`PyConfig_Read` no longer calculates all paths, and so fields
+ listed under :ref:`Python Path Configuration <init-path-config>` may
+ no longer be updated until :c:func:`Py_InitializeFromConfig` is
+ called.
- Configured by the :option:`-X int_max_str_digits <-X>` command line
- flag or the :envvar:`PYTHONINTMAXSTRDIGITS` environment variable.
+ .. c:function:: void PyConfig_Clear(PyConfig *config)
- Default: ``-1`` in Python mode. 4300
- (:data:`sys.int_info.default_max_str_digits`) in isolated mode.
+ Release configuration memory.
- .. versionadded:: 3.12
+ Most ``PyConfig`` methods :ref:`preinitialize Python <c-preinit>` if needed.
+ In that case, the Python preinitialization configuration
+ (:c:type:`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration
+ fields which are in common with :c:type:`PyPreConfig` are tuned, they must
+ be set before calling a :c:type:`PyConfig` method:
- .. c:member:: int cpu_count
+ * :c:member:`PyConfig.dev_mode`
+ * :c:member:`PyConfig.isolated`
+ * :c:member:`PyConfig.parse_argv`
+ * :c:member:`PyConfig.use_environment`
- If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will
- override the return values of :func:`os.cpu_count`,
- :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
+ Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv`
+ is used, this method must be called before other methods, since the
+ preinitialization configuration depends on command line arguments (if
+ :c:member:`~PyConfig.parse_argv` is non-zero).
- Configured by the :samp:`-X cpu_count={n|default}` command line
- flag or the :envvar:`PYTHON_CPU_COUNT` environment variable.
+ The caller of these methods is responsible to handle exceptions (error or
+ exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
- Default: ``-1``.
+ .. c:namespace:: PyConfig
- .. versionadded:: 3.13
+ Structure fields:
- .. c:member:: int isolated
+ .. c:member:: PyWideStringList argv
- If greater than ``0``, enable isolated mode:
+ .. index::
+ single: main()
+ single: argv (in module sys)
- * Set :c:member:`~PyConfig.safe_path` to ``1``:
- don't prepend a potentially unsafe path to :data:`sys.path` at Python
- startup, such as the current directory, the script's directory or an
- empty string.
- * Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON``
- environment variables.
- * Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
- site directory to :data:`sys.path`.
- * Python REPL doesn't import :mod:`readline` nor enable default readline
- configuration on interactive prompts.
+ Set :data:`sys.argv` command line arguments based on
+ :c:member:`~PyConfig.argv`. These parameters are similar to those passed
+ to the program's :c:func:`main` function with the difference that the
+ first entry should refer to the script file to be executed rather than
+ the executable hosting the Python interpreter. If there isn't a script
+ that will be run, the first entry in :c:member:`~PyConfig.argv` can be an
+ empty string.
- Set to ``1`` by the :option:`-I` command line option.
+ Set :c:member:`~PyConfig.parse_argv` to ``1`` to parse
+ :c:member:`~PyConfig.argv` the same way the regular Python parses Python
+ command line arguments and then to strip Python arguments from
+ :c:member:`~PyConfig.argv`.
- Default: ``0`` in Python mode, ``1`` in isolated mode.
+ If :c:member:`~PyConfig.argv` is empty, an empty string is added to
+ ensure that :data:`sys.argv` always exists and is never empty.
- See also the :ref:`Isolated Configuration <init-isolated-conf>` and
- :c:member:`PyPreConfig.isolated`.
+ Default: ``NULL``.
- .. c:member:: int legacy_windows_stdio
+ See also the :c:member:`~PyConfig.orig_argv` member.
- If non-zero, use :class:`io.FileIO` instead of
- :class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
- and :data:`sys.stderr`.
+ .. c:member:: int safe_path
- Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
- variable is set to a non-empty string.
+ If equals to zero, ``Py_RunMain()`` prepends a potentially unsafe path to
+ :data:`sys.path` at startup:
- Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
- Windows specific code.
+ * If :c:member:`argv[0] <PyConfig.argv>` is equal to ``L"-m"``
+ (``python -m module``), prepend the current working directory.
+ * If running a script (``python script.py``), prepend the script's
+ directory. If it's a symbolic link, resolve symbolic links.
+ * Otherwise (``python -c code`` and ``python``), prepend an empty string,
+ which means the current working directory.
- Default: ``0``.
+ Set to ``1`` by the :option:`-P` command line option and the
+ :envvar:`PYTHONSAFEPATH` environment variable.
- See also the :pep:`528` (Change Windows console encoding to UTF-8).
+ Default: ``0`` in Python config, ``1`` in isolated config.
- .. c:member:: int malloc_stats
+ .. versionadded:: 3.11
- If non-zero, dump statistics on :ref:`Python pymalloc memory allocator
- <pymalloc>` at exit.
+ .. c:member:: wchar_t* base_exec_prefix
- Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable.
+ :data:`sys.base_exec_prefix`.
- The option is ignored if Python is :option:`configured using
- the --without-pymalloc option <--without-pymalloc>`.
+ Default: ``NULL``.
- Default: ``0``.
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- .. c:member:: wchar_t* platlibdir
+ See also :c:member:`PyConfig.exec_prefix`.
- Platform library directory name: :data:`sys.platlibdir`.
+ .. c:member:: wchar_t* base_executable
- Set by the :envvar:`PYTHONPLATLIBDIR` environment variable.
+ Python base executable: :data:`sys._base_executable`.
- Default: value of the ``PLATLIBDIR`` macro which is set by the
- :option:`configure --with-platlibdir option <--with-platlibdir>`
- (default: ``"lib"``, or ``"DLLs"`` on Windows).
+ Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable.
- Part of the :ref:`Python Path Configuration <init-path-config>` input.
+ Set from :c:member:`PyConfig.executable` if ``NULL``.
- .. versionadded:: 3.9
+ Default: ``NULL``.
- .. versionchanged:: 3.11
- This macro is now used on Windows to locate the standard
- library extension modules, typically under ``DLLs``. However,
- for compatibility, note that this value is ignored for any
- non-standard layouts, including in-tree builds and virtual
- environments.
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- .. c:member:: wchar_t* pythonpath_env
+ See also :c:member:`PyConfig.executable`.
- Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
- (:data:`os.pathsep`).
+ .. c:member:: wchar_t* base_prefix
- Set by the :envvar:`PYTHONPATH` environment variable.
+ :data:`sys.base_prefix`.
Default: ``NULL``.
- Part of the :ref:`Python Path Configuration <init-path-config>` input.
-
- .. c:member:: PyWideStringList module_search_paths
- .. c:member:: int module_search_paths_set
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- Module search paths: :data:`sys.path`.
+ See also :c:member:`PyConfig.prefix`.
- If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
- :c:func:`Py_InitializeFromConfig` will replace
- :c:member:`~PyConfig.module_search_paths` and sets
- :c:member:`~PyConfig.module_search_paths_set` to ``1``.
+ .. c:member:: int buffered_stdio
- Default: empty list (``module_search_paths``) and ``0``
- (``module_search_paths_set``).
+ If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero,
+ disable buffering on the C streams stdout and stderr.
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ Set to ``0`` by the :option:`-u` command line option and the
+ :envvar:`PYTHONUNBUFFERED` environment variable.
- .. c:member:: int optimization_level
+ stdin is always opened in buffered mode.
- Compilation optimization level:
+ Default: ``1``.
- * ``0``: Peephole optimizer, set ``__debug__`` to ``True``.
- * ``1``: Level 0, remove assertions, set ``__debug__`` to ``False``.
- * ``2``: Level 1, strip docstrings.
+ .. c:member:: int bytes_warning
- Incremented by the :option:`-O` command line option. Set to the
- :envvar:`PYTHONOPTIMIZE` environment variable value.
+ If equals to ``1``, issue a warning when comparing :class:`bytes` or
+ :class:`bytearray` with :class:`str`, or comparing :class:`bytes` with
+ :class:`int`.
- Default: ``0``.
+ If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these
+ cases.
- .. c:member:: PyWideStringList orig_argv
+ Incremented by the :option:`-b` command line option.
- The list of the original command line arguments passed to the Python
- executable: :data:`sys.orig_argv`.
+ Default: ``0``.
- If :c:member:`~PyConfig.orig_argv` list is empty and
- :c:member:`~PyConfig.argv` is not a list only containing an empty
- string, :c:func:`PyConfig_Read` copies :c:member:`~PyConfig.argv` into
- :c:member:`~PyConfig.orig_argv` before modifying
- :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
- non-zero).
+ .. c:member:: int warn_default_encoding
- See also the :c:member:`~PyConfig.argv` member and the
- :c:func:`Py_GetArgcArgv` function.
+ If non-zero, emit a :exc:`EncodingWarning` warning when :class:`io.TextIOWrapper`
+ uses its default encoding. See :ref:`io-encoding-warning` for details.
- Default: empty list.
+ Default: ``0``.
.. versionadded:: 3.10
- .. c:member:: int parse_argv
+ .. c:member:: int code_debug_ranges
- Parse command line arguments?
+ If equals to ``0``, disables the inclusion of the end line and column
+ mappings in code objects. Also disables traceback printing carets to
+ specific error locations.
- If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the regular
- Python parses :ref:`command line arguments <using-on-cmdline>`, and strip
- Python arguments from :c:member:`~PyConfig.argv`.
+ Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable
+ and by the :option:`-X no_debug_ranges <-X>` command line option.
- The :c:func:`PyConfig_Read` function only parses
- :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
- is set to ``2`` after arguments are parsed. Since Python arguments are
- stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
- parse the application options as Python options.
+ Default: ``1``.
- Default: ``1`` in Python mode, ``0`` in isolated mode.
+ .. versionadded:: 3.11
- .. versionchanged:: 3.10
- The :c:member:`PyConfig.argv` arguments are now only parsed if
- :c:member:`PyConfig.parse_argv` equals to ``1``.
+ .. c:member:: wchar_t* check_hash_pycs_mode
- .. c:member:: int parser_debug
+ Control the validation behavior of hash-based ``.pyc`` files:
+ value of the :option:`--check-hash-based-pycs` command line option.
- Parser debug mode. If greater than ``0``, turn on parser debugging output (for expert only, depending
- on compilation options).
+ Valid values:
- Incremented by the :option:`-d` command line option. Set to the
- :envvar:`PYTHONDEBUG` environment variable value.
+ - ``L"always"``: Hash the source file for invalidation regardless of
+ value of the 'check_source' flag.
+ - ``L"never"``: Assume that hash-based pycs always are valid.
+ - ``L"default"``: The 'check_source' flag in hash-based pycs
+ determines invalidation.
- Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
- must be defined).
+ Default: ``L"default"``.
- Default: ``0``.
+ See also :pep:`552` "Deterministic pycs".
- .. c:member:: int pathconfig_warnings
-
- If non-zero, calculation of path configuration is allowed to log
- warnings into ``stderr``. If equals to ``0``, suppress these warnings.
-
- Default: ``1`` in Python mode, ``0`` in isolated mode.
-
- Part of the :ref:`Python Path Configuration <init-path-config>` input.
+ .. c:member:: int configure_c_stdio
- .. versionchanged:: 3.11
- Now also applies on Windows.
+ If non-zero, configure C standard streams:
- .. c:member:: wchar_t* prefix
+ * On Windows, set the binary mode (``O_BINARY``) on stdin, stdout and
+ stderr.
+ * If :c:member:`~PyConfig.buffered_stdio` equals zero, disable buffering
+ of stdin, stdout and stderr streams.
+ * If :c:member:`~PyConfig.interactive` is non-zero, enable stream
+ buffering on stdin and stdout (only stdout on Windows).
- The site-specific directory prefix where the platform independent Python
- files are installed: :data:`sys.prefix`.
+ Default: ``1`` in Python config, ``0`` in isolated config.
- Default: ``NULL``.
+ .. c:member:: int dev_mode
- Part of the :ref:`Python Path Configuration <init-path-config>` output.
+ If non-zero, enable the :ref:`Python Development Mode <devmode>`.
- See also :c:member:`PyConfig.base_prefix`.
+ Set to ``1`` by the :option:`-X dev <-X>` option and the
+ :envvar:`PYTHONDEVMODE` environment variable.
- .. c:member:: wchar_t* program_name
+ Default: ``-1`` in Python mode, ``0`` in isolated mode.
- Program name used to initialize :c:member:`~PyConfig.executable` and in
- early error messages during Python initialization.
+ .. c:member:: int dump_refs
- * On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set.
- * If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use
- :envvar:`__PYVENV_LAUNCHER__` environment variable if set.
- * Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and
- non-empty.
- * Otherwise, use ``L"python"`` on Windows, or ``L"python3"`` on other
- platforms.
+ Dump Python references?
- Default: ``NULL``.
+ If non-zero, dump all objects which are still alive at exit.
- Part of the :ref:`Python Path Configuration <init-path-config>` input.
+ Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable.
- .. c:member:: wchar_t* pycache_prefix
+ Needs a special build of Python with the ``Py_TRACE_REFS`` macro defined:
+ see the :option:`configure --with-trace-refs option <--with-trace-refs>`.
- Directory where cached ``.pyc`` files are written:
- :data:`sys.pycache_prefix`.
+ Default: ``0``.
- Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and
- the :envvar:`PYTHONPYCACHEPREFIX` environment variable.
- The command-line option takes precedence.
+ .. c:member:: wchar_t* exec_prefix
- If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``.
+ The site-specific directory prefix where the platform-dependent Python
+ files are installed: :data:`sys.exec_prefix`.
Default: ``NULL``.
- .. c:member:: int quiet
-
- Quiet mode. If greater than ``0``, don't display the copyright and version at
- Python startup in interactive mode.
-
- Incremented by the :option:`-q` command line option.
-
- Default: ``0``.
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- .. c:member:: wchar_t* run_command
+ See also :c:member:`PyConfig.base_exec_prefix`.
- Value of the :option:`-c` command line option.
+ .. c:member:: wchar_t* executable
- Used by :c:func:`Py_RunMain`.
+ The absolute path of the executable binary for the Python interpreter:
+ :data:`sys.executable`.
Default: ``NULL``.
- .. c:member:: wchar_t* run_filename
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- Filename passed on the command line: trailing command line argument
- without :option:`-c` or :option:`-m`. It is used by the
- :c:func:`Py_RunMain` function.
+ See also :c:member:`PyConfig.base_executable`.
- For example, it is set to ``script.py`` by the ``python3 script.py arg``
- command line.
+ .. c:member:: int faulthandler
- See also the :c:member:`PyConfig.skip_source_first_line` option.
+ Enable faulthandler?
- Default: ``NULL``.
+ If non-zero, call :func:`faulthandler.enable` at startup.
- .. c:member:: wchar_t* run_module
+ Set to ``1`` by :option:`-X faulthandler <-X>` and the
+ :envvar:`PYTHONFAULTHANDLER` environment variable.
- Value of the :option:`-m` command line option.
+ Default: ``-1`` in Python mode, ``0`` in isolated mode.
- Used by :c:func:`Py_RunMain`.
+ .. c:member:: wchar_t* filesystem_encoding
- Default: ``NULL``.
+ :term:`Filesystem encoding <filesystem encoding and error handler>`:
+ :func:`sys.getfilesystemencoding`.
- .. c:member:: wchar_t* run_presite
+ On macOS, Android and VxWorks: use ``"utf-8"`` by default.
- ``package.module`` path to module that should be imported before
- ``site.py`` is run.
+ On Windows: use ``"utf-8"`` by default, or ``"mbcs"`` if
+ :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
+ :c:type:`PyPreConfig` is non-zero.
- Set by the :option:`-X presite=package.module <-X>` command-line
- option and the :envvar:`PYTHON_PRESITE` environment variable.
- The command-line option takes precedence.
+ Default encoding on other platforms:
- Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
- must be defined).
+ * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
+ * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
+ the ASCII encoding, whereas the ``mbstowcs()`` function
+ decodes from a different encoding (usually Latin1).
+ * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
+ * Otherwise, use the :term:`locale encoding`:
+ ``nl_langinfo(CODESET)`` result.
- Default: ``NULL``.
+ At Python startup, the encoding name is normalized to the Python codec
+ name. For example, ``"ANSI_X3.4-1968"`` is replaced with ``"ascii"``.
- .. c:member:: int show_ref_count
+ See also the :c:member:`~PyConfig.filesystem_errors` member.
- Show total reference count at exit (excluding :term:`immortal` objects)?
+ .. c:member:: wchar_t* filesystem_errors
- Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
+ :term:`Filesystem error handler <filesystem encoding and error handler>`:
+ :func:`sys.getfilesystemencodeerrors`.
- Needs a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
- macro must be defined).
+ On Windows: use ``"surrogatepass"`` by default, or ``"replace"`` if
+ :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
+ :c:type:`PyPreConfig` is non-zero.
- Default: ``0``.
+ On other platforms: use ``"surrogateescape"`` by default.
- .. c:member:: int site_import
+ Supported error handlers:
- Import the :mod:`site` module at startup?
+ * ``"strict"``
+ * ``"surrogateescape"``
+ * ``"surrogatepass"`` (only supported with the UTF-8 encoding)
- If equal to zero, disable the import of the module site and the
- site-dependent manipulations of :data:`sys.path` that it entails.
+ See also the :c:member:`~PyConfig.filesystem_encoding` member.
- Also disable these manipulations if the :mod:`site` module is explicitly
- imported later (call :func:`site.main` if you want them to be triggered).
+ .. c:member:: unsigned long hash_seed
+ .. c:member:: int use_hash_seed
- Set to ``0`` by the :option:`-S` command line option.
+ Randomized hash function seed.
- :data:`sys.flags.no_site <sys.flags>` is set to the inverted value of
- :c:member:`~PyConfig.site_import`.
+ If :c:member:`~PyConfig.use_hash_seed` is zero, a seed is chosen randomly
+ at Python startup, and :c:member:`~PyConfig.hash_seed` is ignored.
- Default: ``1``.
+ Set by the :envvar:`PYTHONHASHSEED` environment variable.
- .. c:member:: int skip_source_first_line
+ Default *use_hash_seed* value: ``-1`` in Python mode, ``0`` in isolated
+ mode.
- If non-zero, skip the first line of the :c:member:`PyConfig.run_filename`
- source.
+ .. c:member:: wchar_t* home
- It allows the usage of non-Unix forms of ``#!cmd``. This is intended for
- a DOS specific hack only.
+ Set the default Python "home" directory, that is, the location of the
+ standard Python libraries (see :envvar:`PYTHONHOME`).
- Set to ``1`` by the :option:`-x` command line option.
+ Set by the :envvar:`PYTHONHOME` environment variable.
- Default: ``0``.
+ Default: ``NULL``.
- .. c:member:: wchar_t* stdio_encoding
- .. c:member:: wchar_t* stdio_errors
+ Part of the :ref:`Python Path Configuration <init-path-config>` input.
- Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and
- :data:`sys.stderr` (but :data:`sys.stderr` always uses
- ``"backslashreplace"`` error handler).
+ .. c:member:: int import_time
- Use the :envvar:`PYTHONIOENCODING` environment variable if it is
- non-empty.
+ If non-zero, profile import time.
- Default encoding:
+ Set the ``1`` by the :option:`-X importtime <-X>` option and the
+ :envvar:`PYTHONPROFILEIMPORTTIME` environment variable.
- * ``"UTF-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
- * Otherwise, use the :term:`locale encoding`.
+ Default: ``0``.
- Default error handler:
+ .. c:member:: int inspect
- * On Windows: use ``"surrogateescape"``.
- * ``"surrogateescape"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero,
- or if the LC_CTYPE locale is "C" or "POSIX".
- * ``"strict"`` otherwise.
+ Enter interactive mode after executing a script or a command.
- See also :c:member:`PyConfig.legacy_windows_stdio`.
+ If greater than ``0``, enable inspect: when a script is passed as first
+ argument or the -c option is used, enter interactive mode after executing
+ the script or the command, even when :data:`sys.stdin` does not appear to
+ be a terminal.
- .. c:member:: int tracemalloc
+ Incremented by the :option:`-i` command line option. Set to ``1`` if the
+ :envvar:`PYTHONINSPECT` environment variable is non-empty.
- Enable tracemalloc?
+ Default: ``0``.
- If non-zero, call :func:`tracemalloc.start` at startup.
+ .. c:member:: int install_signal_handlers
- Set by :option:`-X tracemalloc=N <-X>` command line option and by the
- :envvar:`PYTHONTRACEMALLOC` environment variable.
+ Install Python signal handlers?
- Default: ``-1`` in Python mode, ``0`` in isolated mode.
+ Default: ``1`` in Python mode, ``0`` in isolated mode.
- .. c:member:: int perf_profiling
+ .. c:member:: int interactive
- Enable the Linux ``perf`` profiler support?
+ If greater than ``0``, enable the interactive mode (REPL).
- If equals to ``1``, enable support for the Linux ``perf`` profiler.
+ Incremented by the :option:`-i` command line option.
- If equals to ``2``, enable support for the Linux ``perf`` profiler with
- DWARF JIT support.
+ Default: ``0``.
- Set to ``1`` by :option:`-X perf <-X>` command-line option and the
- :envvar:`PYTHONPERFSUPPORT` environment variable.
+ .. c:member:: int int_max_str_digits
- Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and
- the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable.
+ Configures the :ref:`integer string conversion length limitation
+ <int_max_str_digits>`. An initial value of ``-1`` means the value will
+ be taken from the command line or environment or otherwise default to
+ 4300 (:data:`sys.int_info.default_max_str_digits`). A value of ``0``
+ disables the limitation. Values greater than zero but less than 640
+ (:data:`sys.int_info.str_digits_check_threshold`) are unsupported and
+ will produce an error.
- Default: ``-1``.
+ Configured by the :option:`-X int_max_str_digits <-X>` command line
+ flag or the :envvar:`PYTHONINTMAXSTRDIGITS` environment variable.
- .. seealso::
- See :ref:`perf_profiling` for more information.
+ Default: ``-1`` in Python mode. 4300
+ (:data:`sys.int_info.default_max_str_digits`) in isolated mode.
.. versionadded:: 3.12
- .. c:member:: int use_environment
+ .. c:member:: int cpu_count
- Use :ref:`environment variables <using-on-envvars>`?
+ If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will
+ override the return values of :func:`os.cpu_count`,
+ :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
- If equals to zero, ignore the :ref:`environment variables
- <using-on-envvars>`.
+ Configured by the :samp:`-X cpu_count={n|default}` command line
+ flag or the :envvar:`PYTHON_CPU_COUNT` environment variable.
- Set to ``0`` by the :option:`-E` environment variable.
+ Default: ``-1``.
- Default: ``1`` in Python config and ``0`` in isolated config.
+ .. versionadded:: 3.13
- .. c:member:: int use_system_logger
+ .. c:member:: int isolated
- If non-zero, ``stdout`` and ``stderr`` will be redirected to the system
- log.
+ If greater than ``0``, enable isolated mode:
- Only available on macOS 10.12 and later, and on iOS.
+ * Set :c:member:`~PyConfig.safe_path` to ``1``:
+ don't prepend a potentially unsafe path to :data:`sys.path` at Python
+ startup, such as the current directory, the script's directory or an
+ empty string.
+ * Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON``
+ environment variables.
+ * Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
+ site directory to :data:`sys.path`.
+ * Python REPL doesn't import :mod:`readline` nor enable default readline
+ configuration on interactive prompts.
- Default: ``0`` (don't use system log).
+ Set to ``1`` by the :option:`-I` command line option.
- .. versionadded:: 3.13.2
+ Default: ``0`` in Python mode, ``1`` in isolated mode.
- .. c:member:: int user_site_directory
+ See also the :ref:`Isolated Configuration <init-isolated-conf>` and
+ :c:member:`PyPreConfig.isolated`.
- If non-zero, add the user site directory to :data:`sys.path`.
+ .. c:member:: int legacy_windows_stdio
- Set to ``0`` by the :option:`-s` and :option:`-I` command line options.
+ If non-zero, use :class:`io.FileIO` instead of
+ :class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
+ and :data:`sys.stderr`.
- Set to ``0`` by the :envvar:`PYTHONNOUSERSITE` environment variable.
+ Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
+ variable is set to a non-empty string.
- Default: ``1`` in Python mode, ``0`` in isolated mode.
+ Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
+ Windows specific code.
- .. c:member:: int verbose
+ Default: ``0``.
- Verbose mode. If greater than ``0``, print a message each time a module is
- imported, showing the place (filename or built-in module) from which
- it is loaded.
+ See also the :pep:`528` (Change Windows console encoding to UTF-8).
- If greater than or equal to ``2``, print a message for each file that is
- checked for when searching for a module. Also provides information on
- module cleanup at exit.
+ .. c:member:: int malloc_stats
- Incremented by the :option:`-v` command line option.
+ If non-zero, dump statistics on :ref:`Python pymalloc memory allocator
+ <pymalloc>` at exit.
- Set by the :envvar:`PYTHONVERBOSE` environment variable value.
+ Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable.
+
+ The option is ignored if Python is :option:`configured using
+ the --without-pymalloc option <--without-pymalloc>`.
Default: ``0``.
- .. c:member:: PyWideStringList warnoptions
+ .. c:member:: wchar_t* platlibdir
- Options of the :mod:`warnings` module to build warnings filters, lowest
- to highest priority: :data:`sys.warnoptions`.
+ Platform library directory name: :data:`sys.platlibdir`.
- The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse
- order: the last :c:member:`PyConfig.warnoptions` item becomes the first
- item of :data:`warnings.filters` which is checked first (highest
- priority).
+ Set by the :envvar:`PYTHONPLATLIBDIR` environment variable.
- The :option:`-W` command line options adds its value to
- :c:member:`~PyConfig.warnoptions`, it can be used multiple times.
+ Default: value of the ``PLATLIBDIR`` macro which is set by the
+ :option:`configure --with-platlibdir option <--with-platlibdir>`
+ (default: ``"lib"``, or ``"DLLs"`` on Windows).
- The :envvar:`PYTHONWARNINGS` environment variable can also be used to add
- warning options. Multiple options can be specified, separated by commas
- (``,``).
+ Part of the :ref:`Python Path Configuration <init-path-config>` input.
- Default: empty list.
+ .. versionadded:: 3.9
- .. c:member:: int write_bytecode
+ .. versionchanged:: 3.11
+ This macro is now used on Windows to locate the standard
+ library extension modules, typically under ``DLLs``. However,
+ for compatibility, note that this value is ignored for any
+ non-standard layouts, including in-tree builds and virtual
+ environments.
- If equal to ``0``, Python won't try to write ``.pyc`` files on the import of
- source modules.
+ .. c:member:: wchar_t* pythonpath_env
- Set to ``0`` by the :option:`-B` command line option and the
- :envvar:`PYTHONDONTWRITEBYTECODE` environment variable.
+ Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
+ (:data:`os.pathsep`).
- :data:`sys.dont_write_bytecode` is initialized to the inverted value of
- :c:member:`~PyConfig.write_bytecode`.
+ Set by the :envvar:`PYTHONPATH` environment variable.
- Default: ``1``.
+ Default: ``NULL``.
- .. c:member:: PyWideStringList xoptions
+ Part of the :ref:`Python Path Configuration <init-path-config>` input.
- Values of the :option:`-X` command line options: :data:`sys._xoptions`.
+ .. c:member:: PyWideStringList module_search_paths
+ .. c:member:: int module_search_paths_set
- Default: empty list.
+ Module search paths: :data:`sys.path`.
-If :c:member:`~PyConfig.parse_argv` is non-zero, :c:member:`~PyConfig.argv`
-arguments are parsed the same way the regular Python parses :ref:`command line
-arguments <using-on-cmdline>`, and Python arguments are stripped from
-:c:member:`~PyConfig.argv`.
+ If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
+ :c:func:`Py_InitializeFromConfig` will replace
+ :c:member:`~PyConfig.module_search_paths` and sets
+ :c:member:`~PyConfig.module_search_paths_set` to ``1``.
-The :c:member:`~PyConfig.xoptions` options are parsed to set other options: see
-the :option:`-X` command line option.
+ Default: empty list (``module_search_paths``) and ``0``
+ (``module_search_paths_set``).
-.. versionchanged:: 3.9
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
- The ``show_alloc_count`` field has been removed.
+ .. c:member:: int optimization_level
+ Compilation optimization level:
-.. _init-from-config:
+ * ``0``: Peephole optimizer, set ``__debug__`` to ``True``.
+ * ``1``: Level 0, remove assertions, set ``__debug__`` to ``False``.
+ * ``2``: Level 1, strip docstrings.
-Initialization with PyConfig
-----------------------------
+ Incremented by the :option:`-O` command line option. Set to the
+ :envvar:`PYTHONOPTIMIZE` environment variable value.
-Initializing the interpreter from a populated configuration struct is handled
-by calling :c:func:`Py_InitializeFromConfig`.
+ Default: ``0``.
-The caller is responsible to handle exceptions (error or exit) using
-:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
+ .. c:member:: PyWideStringList orig_argv
-If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
-:c:func:`PyImport_ExtendInittab` are used, they must be set or called after
-Python preinitialization and before the Python initialization. If Python is
-initialized multiple times, :c:func:`PyImport_AppendInittab` or
-:c:func:`PyImport_ExtendInittab` must be called before each Python
-initialization.
+ The list of the original command line arguments passed to the Python
+ executable: :data:`sys.orig_argv`.
-The current configuration (``PyConfig`` type) is stored in
-``PyInterpreterState.config``.
+ If :c:member:`~PyConfig.orig_argv` list is empty and
+ :c:member:`~PyConfig.argv` is not a list only containing an empty
+ string, :c:func:`PyConfig_Read` copies :c:member:`~PyConfig.argv` into
+ :c:member:`~PyConfig.orig_argv` before modifying
+ :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
+ non-zero).
-Example setting the program name::
+ See also the :c:member:`~PyConfig.argv` member and the
+ :c:func:`Py_GetArgcArgv` function.
- void init_python(void)
- {
- PyStatus status;
+ Default: empty list.
- PyConfig config;
- PyConfig_InitPythonConfig(&config);
+ .. versionadded:: 3.10
- /* Set the program name. Implicitly preinitialize Python. */
- status = PyConfig_SetString(&config, &config.program_name,
- L"/path/to/my_program");
- if (PyStatus_Exception(status)) {
- goto exception;
- }
+ .. c:member:: int parse_argv
- status = Py_InitializeFromConfig(&config);
- if (PyStatus_Exception(status)) {
- goto exception;
- }
- PyConfig_Clear(&config);
- return;
+ Parse command line arguments?
- exception:
- PyConfig_Clear(&config);
- Py_ExitStatusException(status);
- }
+ If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the regular
+ Python parses :ref:`command line arguments <using-on-cmdline>`, and strip
+ Python arguments from :c:member:`~PyConfig.argv`.
-More complete example modifying the default configuration, read the
-configuration, and then override some parameters. Note that since
-3.11, many parameters are not calculated until initialization, and
-so values cannot be read from the configuration structure. Any values
-set before initialize is called will be left unchanged by
-initialization::
+ The :c:func:`PyConfig_Read` function only parses
+ :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
+ is set to ``2`` after arguments are parsed. Since Python arguments are
+ stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
+ parse the application options as Python options.
- PyStatus init_python(const char *program_name)
- {
- PyStatus status;
+ Default: ``1`` in Python mode, ``0`` in isolated mode.
- PyConfig config;
- PyConfig_InitPythonConfig(&config);
+ .. versionchanged:: 3.10
+ The :c:member:`PyConfig.argv` arguments are now only parsed if
+ :c:member:`PyConfig.parse_argv` equals to ``1``.
- /* Set the program name before reading the configuration
- (decode byte string from the locale encoding).
+ .. c:member:: int parser_debug
- Implicitly preinitialize Python. */
- status = PyConfig_SetBytesString(&config, &config.program_name,
- program_name);
- if (PyStatus_Exception(status)) {
- goto done;
- }
+ Parser debug mode. If greater than ``0``, turn on parser debugging output (for expert only, depending
+ on compilation options).
- /* Read all configuration at once */
- status = PyConfig_Read(&config);
- if (PyStatus_Exception(status)) {
- goto done;
- }
+ Incremented by the :option:`-d` command line option. Set to the
+ :envvar:`PYTHONDEBUG` environment variable value.
- /* Specify sys.path explicitly */
- /* If you want to modify the default set of paths, finish
- initialization first and then use PySys_GetObject("path") */
- config.module_search_paths_set = 1;
- status = PyWideStringList_Append(&config.module_search_paths,
- L"/path/to/stdlib");
- if (PyStatus_Exception(status)) {
- goto done;
- }
- status = PyWideStringList_Append(&config.module_search_paths,
- L"/path/to/more/modules");
- if (PyStatus_Exception(status)) {
- goto done;
- }
+ Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
+ must be defined).
- /* Override executable computed by PyConfig_Read() */
- status = PyConfig_SetString(&config, &config.executable,
- L"/path/to/my_executable");
- if (PyStatus_Exception(status)) {
- goto done;
- }
+ Default: ``0``.
- status = Py_InitializeFromConfig(&config);
+ .. c:member:: int pathconfig_warnings
- done:
- PyConfig_Clear(&config);
- return status;
- }
+ If non-zero, calculation of path configuration is allowed to log
+ warnings into ``stderr``. If equals to ``0``, suppress these warnings.
+ Default: ``1`` in Python mode, ``0`` in isolated mode.
-.. _init-isolated-conf:
+ Part of the :ref:`Python Path Configuration <init-path-config>` input.
-Isolated Configuration
-----------------------
+ .. versionchanged:: 3.11
+ Now also applies on Windows.
-:c:func:`PyPreConfig_InitIsolatedConfig` and
-:c:func:`PyConfig_InitIsolatedConfig` functions create a configuration to
-isolate Python from the system. For example, to embed Python into an
-application.
+ .. c:member:: wchar_t* prefix
-This configuration ignores global configuration variables, environment
-variables, command line arguments (:c:member:`PyConfig.argv` is not parsed)
-and user site directory. The C standard streams (ex: ``stdout``) and the
-LC_CTYPE locale are left unchanged. Signal handlers are not installed.
-
-Configuration files are still used with this configuration to determine
-paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified
-to avoid computing the default path configuration.
+ The site-specific directory prefix where the platform independent Python
+ files are installed: :data:`sys.prefix`.
+ Default: ``NULL``.
-.. _init-python-config:
+ Part of the :ref:`Python Path Configuration <init-path-config>` output.
-Python Configuration
---------------------
+ See also :c:member:`PyConfig.base_prefix`.
-:c:func:`PyPreConfig_InitPythonConfig` and :c:func:`PyConfig_InitPythonConfig`
-functions create a configuration to build a customized Python which behaves as
-the regular Python.
+ .. c:member:: wchar_t* program_name
-Environments variables and command line arguments are used to configure
-Python, whereas global configuration variables are ignored.
+ Program name used to initialize :c:member:`~PyConfig.executable` and in
+ early error messages during Python initialization.
-This function enables C locale coercion (:pep:`538`)
-and :ref:`Python UTF-8 Mode <utf8-mode>`
-(:pep:`540`) depending on the LC_CTYPE locale, :envvar:`PYTHONUTF8` and
-:envvar:`PYTHONCOERCECLOCALE` environment variables.
+ * On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set.
+ * If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use
+ :envvar:`__PYVENV_LAUNCHER__` environment variable if set.
+ * Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and
+ non-empty.
+ * Otherwise, use ``L"python"`` on Windows, or ``L"python3"`` on other
+ platforms.
+ Default: ``NULL``.
-.. _init-path-config:
+ Part of the :ref:`Python Path Configuration <init-path-config>` input.
-Python Path Configuration
--------------------------
+ .. c:member:: wchar_t* pycache_prefix
-:c:type:`PyConfig` contains multiple fields for the path configuration:
+ Directory where cached ``.pyc`` files are written:
+ :data:`sys.pycache_prefix`.
-* Path configuration inputs:
+ Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and
+ the :envvar:`PYTHONPYCACHEPREFIX` environment variable.
+ The command-line option takes precedence.
- * :c:member:`PyConfig.home`
- * :c:member:`PyConfig.platlibdir`
- * :c:member:`PyConfig.pathconfig_warnings`
- * :c:member:`PyConfig.program_name`
- * :c:member:`PyConfig.pythonpath_env`
- * current working directory: to get absolute paths
- * ``PATH`` environment variable to get the program full path
- (from :c:member:`PyConfig.program_name`)
- * ``__PYVENV_LAUNCHER__`` environment variable
- * (Windows only) Application paths in the registry under
- "Software\Python\PythonCore\X.Y\PythonPath" of HKEY_CURRENT_USER and
- HKEY_LOCAL_MACHINE (where X.Y is the Python version).
+ If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``.
-* Path configuration output fields:
+ Default: ``NULL``.
- * :c:member:`PyConfig.base_exec_prefix`
- * :c:member:`PyConfig.base_executable`
- * :c:member:`PyConfig.base_prefix`
- * :c:member:`PyConfig.exec_prefix`
- * :c:member:`PyConfig.executable`
- * :c:member:`PyConfig.module_search_paths_set`,
- :c:member:`PyConfig.module_search_paths`
- * :c:member:`PyConfig.prefix`
+ .. c:member:: int quiet
-If at least one "output field" is not set, Python calculates the path
-configuration to fill unset fields. If
-:c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
-:c:member:`~PyConfig.module_search_paths` is overridden and
-:c:member:`~PyConfig.module_search_paths_set` is set to ``1``.
+ Quiet mode. If greater than ``0``, don't display the copyright and version at
+ Python startup in interactive mode.
-It is possible to completely ignore the function calculating 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.
-``module_search_paths`` is considered as set if
-``module_search_paths_set`` is set to ``1``. In this case,
-``module_search_paths`` will be used without modification.
+ Incremented by the :option:`-q` command line option.
-Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings when
-calculating the path configuration (Unix only, Windows does not log any warning).
+ Default: ``0``.
-If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig.base_exec_prefix`
-fields are not set, they inherit their value from :c:member:`~PyConfig.prefix`
-and :c:member:`~PyConfig.exec_prefix` respectively.
+ .. c:member:: wchar_t* run_command
-:c:func:`Py_RunMain` and :c:func:`Py_Main` modify :data:`sys.path`:
+ Value of the :option:`-c` command line option.
-* If :c:member:`~PyConfig.run_filename` is set and is a directory which contains a
- ``__main__.py`` script, prepend :c:member:`~PyConfig.run_filename` to
- :data:`sys.path`.
-* If :c:member:`~PyConfig.isolated` is zero:
+ Used by :c:func:`Py_RunMain`.
- * If :c:member:`~PyConfig.run_module` is set, prepend the current directory
- to :data:`sys.path`. Do nothing if the current directory cannot be read.
- * If :c:member:`~PyConfig.run_filename` is set, prepend the directory of the
- filename to :data:`sys.path`.
- * Otherwise, prepend an empty string to :data:`sys.path`.
+ Default: ``NULL``.
-If :c:member:`~PyConfig.site_import` is non-zero, :data:`sys.path` can be
-modified by the :mod:`site` module. If
-:c:member:`~PyConfig.user_site_directory` is non-zero and the user's
-site-package directory exists, the :mod:`site` module appends the user's
-site-package directory to :data:`sys.path`.
+ .. c:member:: wchar_t* run_filename
-The following configuration files are used by the path configuration:
+ Filename passed on the command line: trailing command line argument
+ without :option:`-c` or :option:`-m`. It is used by the
+ :c:func:`Py_RunMain` function.
-* ``pyvenv.cfg``
-* ``._pth`` file (ex: ``python._pth``)
-* ``pybuilddir.txt`` (Unix only)
+ For example, it is set to ``script.py`` by the ``python3 script.py arg``
+ command line.
-If a ``._pth`` file is present:
+ See also the :c:member:`PyConfig.skip_source_first_line` option.
-* Set :c:member:`~PyConfig.isolated` to ``1``.
-* Set :c:member:`~PyConfig.use_environment` to ``0``.
-* Set :c:member:`~PyConfig.site_import` to ``0``.
-* Set :c:member:`~PyConfig.safe_path` to ``1``.
+ Default: ``NULL``.
-If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is present in
-the same directory as :c:member:`~PyConfig.executable`, or its parent,
-:c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` are set that
-location. When this happens, :c:member:`~PyConfig.base_prefix` and
-:c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing to the
-base installation. See :ref:`sys-path-init-virtual-environments` for more
-information.
+ .. c:member:: wchar_t* run_module
-The ``__PYVENV_LAUNCHER__`` environment variable is used to set
-:c:member:`PyConfig.base_executable`.
+ Value of the :option:`-m` command line option.
-.. versionchanged:: 3.14
+ Used by :c:func:`Py_RunMain`.
- :c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix`, are now
- set to the ``pyvenv.cfg`` directory. This was previously done by :mod:`site`,
- therefore affected by :option:`-S`.
+ Default: ``NULL``.
-.. _pyinitconfig_api:
+ .. c:member:: wchar_t* run_presite
-PyInitConfig C API
-==================
+ ``package.module`` path to module that should be imported before
+ ``site.py`` is run.
-C API to configure the Python initialization (:pep:`741`).
+ Set by the :option:`-X presite=package.module <-X>` command-line
+ option and the :envvar:`PYTHON_PRESITE` environment variable.
+ The command-line option takes precedence.
-.. versionadded:: 3.14
+ Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
+ must be defined).
-Create Config
--------------
+ Default: ``NULL``.
-.. c:struct:: PyInitConfig
+ .. c:member:: int show_ref_count
- Opaque structure to configure the Python initialization.
+ Show total reference count at exit (excluding :term:`immortal` objects)?
+ Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
-.. c:function:: PyInitConfig* PyInitConfig_Create(void)
+ Needs a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
+ macro must be defined).
- Create a new initialization configuration using :ref:`Isolated Configuration
- <init-isolated-conf>` default values.
+ Default: ``0``.
- It must be freed by :c:func:`PyInitConfig_Free`.
+ .. c:member:: int site_import
- Return ``NULL`` on memory allocation failure.
+ Import the :mod:`site` module at startup?
+ If equal to zero, disable the import of the module site and the
+ site-dependent manipulations of :data:`sys.path` that it entails.
-.. c:function:: void PyInitConfig_Free(PyInitConfig *config)
+ Also disable these manipulations if the :mod:`site` module is explicitly
+ imported later (call :func:`site.main` if you want them to be triggered).
- Free memory of the initialization configuration *config*.
+ Set to ``0`` by the :option:`-S` command line option.
- If *config* is ``NULL``, no operation is performed.
+ :data:`sys.flags.no_site <sys.flags>` is set to the inverted value of
+ :c:member:`~PyConfig.site_import`.
+ Default: ``1``.
-Error Handling
---------------
+ .. c:member:: int skip_source_first_line
-.. c:function:: int PyInitConfig_GetError(PyInitConfig* config, const char **err_msg)
+ If non-zero, skip the first line of the :c:member:`PyConfig.run_filename`
+ source.
- Get the *config* error message.
+ It allows the usage of non-Unix forms of ``#!cmd``. This is intended for
+ a DOS specific hack only.
- * Set *\*err_msg* and return ``1`` if an error is set.
- * Set *\*err_msg* to ``NULL`` and return ``0`` otherwise.
+ Set to ``1`` by the :option:`-x` command line option.
- An error message is an UTF-8 encoded string.
+ Default: ``0``.
- If *config* has an exit code, format the exit code as an error
- message.
+ .. c:member:: wchar_t* stdio_encoding
+ .. c:member:: wchar_t* stdio_errors
- The error message remains valid until another ``PyInitConfig``
- function is called with *config*. The caller doesn't have to free the
- error message.
+ Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and
+ :data:`sys.stderr` (but :data:`sys.stderr` always uses
+ ``"backslashreplace"`` error handler).
+ Use the :envvar:`PYTHONIOENCODING` environment variable if it is
+ non-empty.
-.. c:function:: int PyInitConfig_GetExitCode(PyInitConfig* config, int *exitcode)
+ Default encoding:
- Get the *config* exit code.
+ * ``"UTF-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
+ * Otherwise, use the :term:`locale encoding`.
- * Set *\*exitcode* and return ``1`` if *config* has an exit code set.
- * Return ``0`` if *config* has no exit code set.
+ Default error handler:
- Only the ``Py_InitializeFromInitConfig()`` function can set an exit
- code if the ``parse_argv`` option is non-zero.
+ * On Windows: use ``"surrogateescape"``.
+ * ``"surrogateescape"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero,
+ or if the LC_CTYPE locale is "C" or "POSIX".
+ * ``"strict"`` otherwise.
- An exit code can be set when parsing the command line failed (exit
- code ``2``) or when a command line option asks to display the command
- line help (exit code ``0``).
+ See also :c:member:`PyConfig.legacy_windows_stdio`.
+ .. c:member:: int tracemalloc
-Get Options
------------
+ Enable tracemalloc?
-The configuration option *name* parameter must be a non-NULL
-null-terminated UTF-8 encoded string.
+ If non-zero, call :func:`tracemalloc.start` at startup.
-.. c:function:: int PyInitConfig_HasOption(PyInitConfig *config, const char *name)
+ Set by :option:`-X tracemalloc=N <-X>` command line option and by the
+ :envvar:`PYTHONTRACEMALLOC` environment variable.
- Test if the configuration has an option called *name*.
+ Default: ``-1`` in Python mode, ``0`` in isolated mode.
- Return ``1`` if the option exists, or return ``0`` otherwise.
+ .. c:member:: int perf_profiling
+ Enable the Linux ``perf`` profiler support?
-.. c:function:: int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)
+ If equals to ``1``, enable support for the Linux ``perf`` profiler.
- Get an integer configuration option.
+ If equals to ``2``, enable support for the Linux ``perf`` profiler with
+ DWARF JIT support.
- * Set *\*value*, and return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ Set to ``1`` by :option:`-X perf <-X>` command-line option and the
+ :envvar:`PYTHONPERFSUPPORT` environment variable.
+ Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and
+ the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable.
-.. c:function:: int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)
+ Default: ``-1``.
- Get a string configuration option as a null-terminated UTF-8
- encoded string.
+ .. seealso::
+ See :ref:`perf_profiling` for more information.
- * Set *\*value*, and return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ .. versionadded:: 3.12
- *\*value* can be set to ``NULL`` if the option is an optional string and the
- option is unset.
+ .. c:member:: int use_environment
- On success, the string must be released with ``free(value)`` if it's not
- ``NULL``.
+ Use :ref:`environment variables <using-on-envvars>`?
+ If equals to zero, ignore the :ref:`environment variables
+ <using-on-envvars>`.
-.. c:function:: int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)
+ Set to ``0`` by the :option:`-E` environment variable.
- Get a string list configuration option as an array of
- null-terminated UTF-8 encoded strings.
+ Default: ``1`` in Python config and ``0`` in isolated config.
- * Set *\*length* and *\*value*, and return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ .. c:member:: int use_system_logger
- On success, the string list must be released with
- ``PyInitConfig_FreeStrList(length, items)``.
+ If non-zero, ``stdout`` and ``stderr`` will be redirected to the system
+ log.
+ Only available on macOS 10.12 and later, and on iOS.
-.. c:function:: void PyInitConfig_FreeStrList(size_t length, char **items)
+ Default: ``0`` (don't use system log).
- Free memory of a string list created by
- ``PyInitConfig_GetStrList()``.
+ .. versionadded:: 3.13.2
+ .. c:member:: int user_site_directory
-Set Options
------------
+ If non-zero, add the user site directory to :data:`sys.path`.
-The configuration option *name* parameter must be a non-NULL null-terminated
-UTF-8 encoded string.
+ Set to ``0`` by the :option:`-s` and :option:`-I` command line options.
-Some configuration options have side effects on other options. This logic is
-only implemented when ``Py_InitializeFromInitConfig()`` is called, not by the
-"Set" functions below. For example, setting ``dev_mode`` to ``1`` does not set
-``faulthandler`` to ``1``.
+ Set to ``0`` by the :envvar:`PYTHONNOUSERSITE` environment variable.
-.. c:function:: int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)
+ Default: ``1`` in Python mode, ``0`` in isolated mode.
- Set an integer configuration option.
+ .. c:member:: int verbose
- * Return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ Verbose mode. If greater than ``0``, print a message each time a module is
+ imported, showing the place (filename or built-in module) from which
+ it is loaded.
+ If greater than or equal to ``2``, print a message for each file that is
+ checked for when searching for a module. Also provides information on
+ module cleanup at exit.
-.. c:function:: int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)
+ Incremented by the :option:`-v` command line option.
- Set a string configuration option from a null-terminated UTF-8
- encoded string. The string is copied.
+ Set by the :envvar:`PYTHONVERBOSE` environment variable value.
- * Return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ Default: ``0``.
+ .. c:member:: PyWideStringList warnoptions
-.. c:function:: int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char * const *items)
+ Options of the :mod:`warnings` module to build warnings filters, lowest
+ to highest priority: :data:`sys.warnoptions`.
- Set a string list configuration option from an array of
- null-terminated UTF-8 encoded strings. The string list is copied.
+ The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse
+ order: the last :c:member:`PyConfig.warnoptions` item becomes the first
+ item of :data:`warnings.filters` which is checked first (highest
+ priority).
- * Return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ The :option:`-W` command line options adds its value to
+ :c:member:`~PyConfig.warnoptions`, it can be used multiple times.
+ The :envvar:`PYTHONWARNINGS` environment variable can also be used to add
+ warning options. Multiple options can be specified, separated by commas
+ (``,``).
-Module
-------
+ Default: empty list.
-.. c:function:: int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject* (*initfunc)(void))
+ .. c:member:: int write_bytecode
- Add a built-in extension module to the table of built-in modules.
+ If equal to ``0``, Python won't try to write ``.pyc`` files on the import of
+ source modules.
- The new module can be imported by the name *name*, and uses the function
- *initfunc* as the initialization function called on the first attempted
- import.
+ Set to ``0`` by the :option:`-B` command line option and the
+ :envvar:`PYTHONDONTWRITEBYTECODE` environment variable.
- * Return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
+ :data:`sys.dont_write_bytecode` is initialized to the inverted value of
+ :c:member:`~PyConfig.write_bytecode`.
- If Python is initialized multiple times, ``PyInitConfig_AddModule()`` must
- be called at each Python initialization.
+ Default: ``1``.
- Similar to the :c:func:`PyImport_AppendInittab` function.
+ .. c:member:: PyWideStringList xoptions
+ Values of the :option:`-X` command line options: :data:`sys._xoptions`.
-Initialize Python
------------------
+ Default: empty list.
-.. c:function:: int Py_InitializeFromInitConfig(PyInitConfig *config)
+If :c:member:`~PyConfig.parse_argv` is non-zero, :c:member:`~PyConfig.argv`
+arguments are parsed the same way the regular Python parses :ref:`command line
+arguments <using-on-cmdline>`, and Python arguments are stripped from
+:c:member:`~PyConfig.argv`.
- Initialize Python from the initialization configuration.
+The :c:member:`~PyConfig.xoptions` options are parsed to set other options: see
+the :option:`-X` command line option.
- * Return ``0`` on success.
- * Set an error in *config* and return ``-1`` on error.
- * Set an exit code in *config* and return ``-1`` if Python wants to
- exit.
+.. versionchanged:: 3.9
- See ``PyInitConfig_GetExitcode()`` for the exit code case.
+ The ``show_alloc_count`` field has been removed.
-Example
--------
+.. _init-from-config:
-Example initializing Python, set configuration options of various types,
-return ``-1`` on error:
+Initialization with PyConfig
+----------------------------
-.. code-block:: c
+Initializing the interpreter from a populated configuration struct is handled
+by calling :c:func:`Py_InitializeFromConfig`.
- int init_python(void)
+The caller is responsible to handle exceptions (error or exit) using
+:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
+
+If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
+:c:func:`PyImport_ExtendInittab` are used, they must be set or called after
+Python preinitialization and before the Python initialization. If Python is
+initialized multiple times, :c:func:`PyImport_AppendInittab` or
+:c:func:`PyImport_ExtendInittab` must be called before each Python
+initialization.
+
+The current configuration (``PyConfig`` type) is stored in
+``PyInterpreterState.config``.
+
+Example setting the program name::
+
+ void init_python(void)
{
- PyInitConfig *config = PyInitConfig_Create();
- if (config == NULL) {
- printf("PYTHON INIT ERROR: memory allocation failed\n");
- return -1;
- }
+ PyStatus status;
- // Set an integer (dev mode)
- if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
- goto error;
+ 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 exception;
}
- // Set a list of UTF-8 strings (argv)
- char *argv[] = {"my_program", "-c", "pass"};
- if (PyInitConfig_SetStrList(config, "argv",
- Py_ARRAY_LENGTH(argv), argv) < 0) {
- goto error;
+ status = Py_InitializeFromConfig(&config);
+ if (PyStatus_Exception(status)) {
+ goto exception;
}
+ PyConfig_Clear(&config);
+ return;
- // Set a UTF-8 string (program name)
- if (PyInitConfig_SetStr(config, "program_name", L"my_program") < 0) {
- goto error;
+ exception:
+ PyConfig_Clear(&config);
+ Py_ExitStatusException(status);
+ }
+
+More complete example modifying the default configuration, read the
+configuration, and then override some parameters. Note that since
+3.11, many parameters are not calculated until initialization, and
+so values cannot be read from the configuration structure. Any values
+set before initialize is called will be left unchanged by
+initialization::
+
+ 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;
}
- // Initialize Python with the configuration
- if (Py_InitializeFromInitConfig(config) < 0) {
- goto error;
+ /* Read all configuration at once */
+ status = PyConfig_Read(&config);
+ if (PyStatus_Exception(status)) {
+ goto done;
}
- PyInitConfig_Free(config);
- return 0;
- error:
- {
- // Display the error message
- // This uncommon braces style is used, because you cannot make
- // goto targets point to variable declarations.
- const char *err_msg;
- (void)PyInitConfig_GetError(config, &err_msg);
- printf("PYTHON INIT ERROR: %s\n", err_msg);
- PyInitConfig_Free(config);
+ /* Specify sys.path explicitly */
+ /* If you want to modify the default set of paths, finish
+ initialization first and then use PySys_GetObject("path") */
+ config.module_search_paths_set = 1;
+ status = PyWideStringList_Append(&config.module_search_paths,
+ L"/path/to/stdlib");
+ if (PyStatus_Exception(status)) {
+ goto done;
+ }
+ status = PyWideStringList_Append(&config.module_search_paths,
+ L"/path/to/more/modules");
+ if (PyStatus_Exception(status)) {
+ goto done;
+ }
- return -1;
+ /* 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;
}
-Runtime Python configuration API
-================================
+.. _init-isolated-conf:
-The configuration option *name* parameter must be a non-NULL null-terminated
-UTF-8 encoded string.
+Isolated Configuration
+----------------------
-Some options are read from the :mod:`sys` attributes. For example, the option
-``"argv"`` is read from :data:`sys.argv`.
+:c:func:`PyPreConfig_InitIsolatedConfig` and
+:c:func:`PyConfig_InitIsolatedConfig` functions create a configuration to
+isolate Python from the system. For example, to embed Python into an
+application.
+This configuration ignores global configuration variables, environment
+variables, command line arguments (:c:member:`PyConfig.argv` is not parsed)
+and user site directory. The C standard streams (ex: ``stdout``) and the
+LC_CTYPE locale are left unchanged. Signal handlers are not installed.
-.. c:function:: PyObject* PyConfig_Get(const char *name)
+Configuration files are still used with this configuration to determine
+paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified
+to avoid computing the default path configuration.
- Get the current runtime value of a configuration option as a Python object.
- * Return a new reference on success.
- * Set an exception and return ``NULL`` on error.
+.. _init-python-config:
- The object type depends on the configuration option. It can be:
+Python Configuration
+--------------------
- * ``bool``
- * ``int``
- * ``str``
- * ``list[str]``
- * ``dict[str, str]``
+:c:func:`PyPreConfig_InitPythonConfig` and :c:func:`PyConfig_InitPythonConfig`
+functions create a configuration to build a customized Python which behaves as
+the regular Python.
- The caller must hold the GIL. The function cannot be called before
- Python initialization nor after Python finalization.
+Environments variables and command line arguments are used to configure
+Python, whereas global configuration variables are ignored.
- .. versionadded:: 3.14
+This function enables C locale coercion (:pep:`538`)
+and :ref:`Python UTF-8 Mode <utf8-mode>`
+(:pep:`540`) depending on the LC_CTYPE locale, :envvar:`PYTHONUTF8` and
+:envvar:`PYTHONCOERCECLOCALE` environment variables.
-.. c:function:: int PyConfig_GetInt(const char *name, int *value)
+.. _init-path-config:
- Similar to :c:func:`PyConfig_Get`, but get the value as a C int.
+Python Path Configuration
+-------------------------
- * Return ``0`` on success.
- * Set an exception and return ``-1`` on error.
+:c:type:`PyConfig` contains multiple fields for the path configuration:
- .. versionadded:: 3.14
+* Path configuration inputs:
+ * :c:member:`PyConfig.home`
+ * :c:member:`PyConfig.platlibdir`
+ * :c:member:`PyConfig.pathconfig_warnings`
+ * :c:member:`PyConfig.program_name`
+ * :c:member:`PyConfig.pythonpath_env`
+ * current working directory: to get absolute paths
+ * ``PATH`` environment variable to get the program full path
+ (from :c:member:`PyConfig.program_name`)
+ * ``__PYVENV_LAUNCHER__`` environment variable
+ * (Windows only) Application paths in the registry under
+ "Software\Python\PythonCore\X.Y\PythonPath" of HKEY_CURRENT_USER and
+ HKEY_LOCAL_MACHINE (where X.Y is the Python version).
-.. c:function:: PyObject* PyConfig_Names(void)
+* Path configuration output fields:
- Get all configuration option names as a ``frozenset``.
+ * :c:member:`PyConfig.base_exec_prefix`
+ * :c:member:`PyConfig.base_executable`
+ * :c:member:`PyConfig.base_prefix`
+ * :c:member:`PyConfig.exec_prefix`
+ * :c:member:`PyConfig.executable`
+ * :c:member:`PyConfig.module_search_paths_set`,
+ :c:member:`PyConfig.module_search_paths`
+ * :c:member:`PyConfig.prefix`
- * Return a new reference on success.
- * Set an exception and return ``NULL`` on error.
+If at least one "output field" is not set, Python calculates the path
+configuration to fill unset fields. If
+:c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
+:c:member:`~PyConfig.module_search_paths` is overridden and
+:c:member:`~PyConfig.module_search_paths_set` is set to ``1``.
- The caller must hold the GIL. The function cannot be called before
- Python initialization nor after Python finalization.
+It is possible to completely ignore the function calculating 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.
+``module_search_paths`` is considered as set if
+``module_search_paths_set`` is set to ``1``. In this case,
+``module_search_paths`` will be used without modification.
- .. versionadded:: 3.14
+Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings when
+calculating the path configuration (Unix only, Windows does not log any warning).
+If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig.base_exec_prefix`
+fields are not set, they inherit their value from :c:member:`~PyConfig.prefix`
+and :c:member:`~PyConfig.exec_prefix` respectively.
-.. c:function:: int PyConfig_Set(const char *name, PyObject *value)
+:c:func:`Py_RunMain` and :c:func:`Py_Main` modify :data:`sys.path`:
- Set the current runtime value of a configuration option.
+* If :c:member:`~PyConfig.run_filename` is set and is a directory which contains a
+ ``__main__.py`` script, prepend :c:member:`~PyConfig.run_filename` to
+ :data:`sys.path`.
+* If :c:member:`~PyConfig.isolated` is zero:
- * Raise a :exc:`ValueError` if there is no option *name*.
- * Raise a :exc:`ValueError` if *value* is an invalid value.
- * Raise a :exc:`ValueError` if the option is read-only (cannot be set).
- * Raise a :exc:`TypeError` if *value* has not the proper type.
+ * If :c:member:`~PyConfig.run_module` is set, prepend the current directory
+ to :data:`sys.path`. Do nothing if the current directory cannot be read.
+ * If :c:member:`~PyConfig.run_filename` is set, prepend the directory of the
+ filename to :data:`sys.path`.
+ * Otherwise, prepend an empty string to :data:`sys.path`.
- The caller must hold the GIL. The function cannot be called before
- Python initialization nor after Python finalization.
+If :c:member:`~PyConfig.site_import` is non-zero, :data:`sys.path` can be
+modified by the :mod:`site` module. If
+:c:member:`~PyConfig.user_site_directory` is non-zero and the user's
+site-package directory exists, the :mod:`site` module appends the user's
+site-package directory to :data:`sys.path`.
- .. versionadded:: 3.14
+The following configuration files are used by the path configuration:
+
+* ``pyvenv.cfg``
+* ``._pth`` file (ex: ``python._pth``)
+* ``pybuilddir.txt`` (Unix only)
+
+If a ``._pth`` file is present:
+
+* Set :c:member:`~PyConfig.isolated` to ``1``.
+* Set :c:member:`~PyConfig.use_environment` to ``0``.
+* Set :c:member:`~PyConfig.site_import` to ``0``.
+* Set :c:member:`~PyConfig.safe_path` to ``1``.
+
+If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is present in
+the same directory as :c:member:`~PyConfig.executable`, or its parent,
+:c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` are set that
+location. When this happens, :c:member:`~PyConfig.base_prefix` and
+:c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing to the
+base installation. See :ref:`sys-path-init-virtual-environments` for more
+information.
+
+The ``__PYVENV_LAUNCHER__`` environment variable is used to set
+:c:member:`PyConfig.base_executable`.
+
+.. versionchanged:: 3.14
+
+ :c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix`, are now
+ set to the ``pyvenv.cfg`` directory. This was previously done by :mod:`site`,
+ therefore affected by :option:`-S`.
Py_GetArgcArgv()
projects / thirdparty / Python / cpython.git / commitdiff
