Python Initialization Configuration¶

PyInitConfig C API¶

Added in version 3.14.

Python can be initialized with Py_InitializeFromInitConfig().

The Py_RunMain() function can be used to write a customized Python program.

Example¶

Example of customized Python always running with the Python Development Mode enabled; return -1 on error:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) {
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    }

    // Enable the Python Development Mode
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    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);
        return -1;
    }
}

Create Config¶

struct PyInitConfig¶: Opaque structure to configure the Python initialization.

PyInitConfig *PyInitConfig_Create(void)¶

Create a new initialization configuration using Isolated Configuration default values.

It must be freed by PyInitConfig_Free().

Return NULL on memory allocation failure.

void PyInitConfig_Free(PyInitConfig *config)¶

Free memory of the initialization configuration config.

If config is NULL, no operation is performed.

Error Handling¶

int PyInitConfig_GetError(PyInitConfig *config, const char **err_msg)¶

Get the config error message.

Set *err_msg and return 1 if an error is set.
Set *err_msg to NULL and return 0 otherwise.

An error message is a UTF-8 encoded string.

If config has an exit code, format the exit code as an error message.

The error message remains valid until another PyInitConfig function is called with config. The caller doesn’t have to free the error message.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶

Get the config exit code.

Return 0 and leave *exitcode unchanged.

In Python 3.15, Py_InitializeFromInitConfig() sets an exit code if a command line option wants to exit Python. This is no longer the case in Python 3.16. Instead, the option is now processed in Py_RunMain(). This function became useless.

Deprecated since version 3.16.

Get Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.

int PyInitConfig_HasOption(PyInitConfig *config, const char *name)¶

Test if the configuration has an option called name.

Return 1 if the option exists, or return 0 otherwise.

int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)¶

Get an integer configuration option.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)¶

Get a string configuration option as a null-terminated UTF-8 encoded string.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

*value can be set to NULL if the option is unset or if the option is an optional string. Optional strings are documented with the type str | None in the Configuration Options table.

On success, the string must be released with free(value) if it’s not NULL.

int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)¶

Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.

Set *length and *items, and return 0 on success.
Set an error in config and return -1 on error.

On success, the string list must be released with PyInitConfig_FreeStrList(length, items).

void PyInitConfig_FreeStrList(size_t length, char **items)¶: Free memory of a string list created by PyInitConfig_GetStrList().

Set Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration 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.

int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)¶

Set an integer configuration option.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)¶

Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.

Options documented with the type str | None in the Configuration Options table can be set to NULL.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char *const *items)¶

Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.

Return 0 on success.
Set an error in config and return -1 on error.

Module¶

int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))¶

Add a built-in extension module to the table of built-in 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.

Return 0 on success.
Set an error in config and return -1 on error.

If Python is initialized multiple times, PyInitConfig_AddModule() must be called at each Python initialization.

Similar to the PyImport_AppendInittab() function.

Initialize Python¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

Initialize Python from the initialization configuration.

Return 0 on success.
Set an error in config and return -1 on error.

Changed in version 3.16: The function no longer sets an exit code if a command line option wants to exit Python. Instead, the option is now processed in Py_RunMain().

Configuration Options¶

Option	PyConfig/PyPreConfig member	Type	Visibility
`"allocator"`	`allocator`	`int`	Read-only
`"argv"`	`argv`	`list[str]`	Public
`"base_exec_prefix"`	`base_exec_prefix`	`str \| None`	Public
`"base_executable"`	`base_executable`	`str \| None`	Public
`"base_prefix"`	`base_prefix`	`str \| None`	Public
`"buffered_stdio"`	`buffered_stdio`	`bool`	Read-only
`"bytes_warning"`	`bytes_warning`	`int`	Public
`"check_hash_pycs_mode"`	`check_hash_pycs_mode`	`str`	Read-only
`"code_debug_ranges"`	`code_debug_ranges`	`bool`	Read-only
`"coerce_c_locale"`	`coerce_c_locale`	`bool`	Read-only
`"coerce_c_locale_warn"`	`coerce_c_locale_warn`	`bool`	Read-only
`"configure_c_stdio"`	`configure_c_stdio`	`bool`	Read-only
`"configure_locale"`	`configure_locale`	`bool`	Read-only
`"cpu_count"`	`cpu_count`	`int`	Public
`"dev_mode"`	`dev_mode`	`bool`	Read-only
`"dump_refs"`	`dump_refs`	`bool`	Read-only
`"dump_refs_file"`	`dump_refs_file`	`str \| None`	Read-only
`"exec_prefix"`	`exec_prefix`	`str \| None`	Public
`"executable"`	`executable`	`str \| None`	Public
`"faulthandler"`	`faulthandler`	`bool`	Read-only
`"filesystem_encoding"`	`filesystem_encoding`	`str`	Read-only
`"filesystem_errors"`	`filesystem_errors`	`str`	Read-only
`"hash_seed"`	`hash_seed`	`int`	Read-only
`"home"`	`home`	`str \| None`	Read-only
`"import_time"`	`import_time`	`int`	Read-only
`"inspect"`	`inspect`	`bool`	Public
`"install_signal_handlers"`	`install_signal_handlers`	`bool`	Read-only
`"int_max_str_digits"`	`int_max_str_digits`	`int`	Public
`"interactive"`	`interactive`	`bool`	Public
`"isolated"`	`isolated`	`bool`	Read-only
`"lazy_imports"`	`lazy_imports`	`int`	Public
`"legacy_windows_fs_encoding"`	`legacy_windows_fs_encoding`	`bool`	Read-only
`"legacy_windows_stdio"`	`legacy_windows_stdio`	`bool`	Read-only
`"malloc_stats"`	`malloc_stats`	`bool`	Read-only
`"module_search_paths"`	`module_search_paths`	`list[str]`	Public
`"optimization_level"`	`optimization_level`	`int`	Public
`"orig_argv"`	`orig_argv`	`list[str]`	Read-only
`"parse_argv"`	`parse_argv`	`bool`	Read-only
`"parser_debug"`	`parser_debug`	`bool`	Public
`"pathconfig_warnings"`	`pathconfig_warnings`	`bool`	Read-only
`"perf_profiling"`	`perf_profiling`	`bool`	Read-only
`"platlibdir"`	`platlibdir`	`str`	Public
`"prefix"`	`prefix`	`str \| None`	Public
`"program_name"`	`program_name`	`str`	Read-only
`"pycache_prefix"`	`pycache_prefix`	`str \| None`	Public
`"quiet"`	`quiet`	`bool`	Public
`"run_command"`	`run_command`	`str \| None`	Read-only
`"run_filename"`	`run_filename`	`str \| None`	Read-only
`"run_module"`	`run_module`	`str \| None`	Read-only
`"run_presite"`	`run_presite`	`str \| None`	Read-only
`"safe_path"`	`safe_path`	`bool`	Read-only
`"show_ref_count"`	`show_ref_count`	`bool`	Read-only
`"site_import"`	`site_import`	`bool`	Read-only
`"skip_source_first_line"`	`skip_source_first_line`	`bool`	Read-only
`"stdio_encoding"`	`stdio_encoding`	`str \| None`	Read-only
`"stdio_errors"`	`stdio_errors`	`str`	Read-only
`"stdlib_dir"`	`stdlib_dir`