Python Initialization Configuration¶

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.

• Set *exitcode and return 1 if config has an exit code set.

• Return 0 if config has no exit code set.

Only the Py_InitializeFromInitConfig() function can set an exit code if the parse_argv option is non-zero.

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).

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 an optional string and the option is unset.

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 *value, 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.

• 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.

• Set an exit code in config and return -1 if Python wants to exit.

See PyInitConfig_GetExitcode() for the exit code case.

Example¶

Example of customized Python always running in isolated mode:

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

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);
}

PyWideStringList¶

type PyWideStringList¶

List of wchar_t* strings.

If length is non-zero, items must be non-NULL and all strings must be non-NULL.

Methods:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶

Append item to list.

Python must be preinitialized to call this function.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶

Insert item into list at index.

If index is greater than or equal to list length, append item to list.

index must be greater than or equal to 0.

Python must be preinitialized to call this function.

Structure fields:

Py_ssize_t length¶

List length.

wchar_t **items¶

List items.

PyStatus