Python初始化配置¶

3.8 新版功能.

结构

PyConfig
PyPreConfig
PyStatus
PyWideStringList

函数

The preconfiguration (PyPreConfig type) is stored in _PyRuntime.preconfig and the configuration (PyConfig type) is stored in PyInterpreterState.config.

参见 Initialization, Finalization, and Threads.

参见

PEP 587 "Python 初始化配置".

PyWideStringList¶

PyWideStringList¶

由 wchar_t* 字符串组成的列表。

如果 length 为非零值，则 items 必须不为 NULL 并且所有字符串均必须不为 NULL。

方法

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

将 item 添加到 list。

Python 必须被预初始化以便调用此函数。

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

将 item 插入到 list 的 index 位置上。

如果 index 大于等于 list 的长度，则将 item 添加到 list。

index must be greater than or equal to 0.

Python 必须被预初始化以便调用此函数。

Structure fields:

Py_ssize_t length¶: List 长度。

wchar_t** items¶: 列表项目。

PyStatus¶

PyStatus¶

Structure to store an initialization function status: success, error or exit.

For an error, it can store the C function name which created the error.

Structure fields:

int exitcode¶: Exit code. Argument passed to exit().

const char *err_msg¶: 错误信息

const char *func¶: Name of the function which created an error, can be NULL.

Functions to create a status:

PyStatus PyStatus_Ok(void)¶: 完成。

PyStatus PyStatus_Error(const char *err_msg)¶: Initialization error with a message.

PyStatus PyStatus_NoMemory(void)¶: Memory allocation failure (out of memory).

PyStatus PyStatus_Exit(int exitcode)¶: 以指定的退出代码退出 Python。

Functions to handle a status:

int PyStatus_Exception(PyStatus status)¶: Is the status an error or an exit? If true, the exception must be handled; by calling Py_ExitStatusException() for example.

int PyStatus_IsError(PyStatus status)¶: 结果错误吗？

int PyStatus_IsExit(PyStatus status)¶: 结果是否退出？

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.

注解

Internally, Python uses macros which set PyStatus.func, whereas functions to create a status set func to NULL.

示例:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig¶

PyPreConfig¶

Structure used to preinitialize Python:

Set the Python memory allocator
Configure the LC_CTYPE locale
设置为 UTF-8 模式

Function to initialize a preconfiguration:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: Initialize the preconfiguration with Python Configuration.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: Initialize the preconfiguration with Isolated Configuration.

Structure fields:

int allocator¶

Name of the memory allocator:

PYMEM_ALLOCATOR_NOT_SET (0): don't change memory allocators (use defaults)
PYMEM_ALLOCATOR_DEFAULT (1): default memory allocators
PYMEM_ALLOCATOR_DEBUG (2): default memory allocators with debug hooks
PYMEM_ALLOCATOR_MALLOC (3): force usage of malloc()
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage of malloc() with debug hooks
PYMEM_ALLOCATOR_PYMALLOC (5): Python pymalloc memory allocator
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python pymalloc memory allocator with debug hooks

PYMEM_ALLOCATOR_PYMALLOC and PYMEM_ALLOCATOR_PYMALLOC_DEBUG are not supported if Python is configured using --without-pymalloc

参见 Memory Management.

int configure_locale¶: Set the LC_CTYPE locale to the user preferred locale? If equals to 0, set coerce_c_locale and coerce_c_locale_warn to 0.

int coerce_c_locale¶: If equals to 2, coerce the C locale; if equals to 1, read the LC_CTYPE locale to decide if it should be coerced.

int coerce_c_locale_warn¶: If non-zero, emit a warning if the C locale is coerced.

int dev_mode¶: 参见 PyConfig.dev_mode.

int isolated¶: 参见 PyConfig.isolated.

int legacy_windows_fs_encoding(Windows only)¶

If non-zero, disable UTF-8 Mode, set the Python filesystem encoding to mbcs, set the filesystem error handler to replace.

Only available on Windows. #ifdef MS_WINDOWS macro can be used for Windows specific code.

int parse_argv¶: If non-zero, Py_PreInitializeFromArgs() and Py_PreInitializeFromBytesArgs() parse their argv argument the same way the regular Python parses command line arguments: see Command Line Arguments.

int use_environment¶: 参见 PyConfig.use_environment.

int utf8_mode¶: If non-zero, enable the UTF-8 mode.

Preinitialization with PyPreConfig¶

Functions to preinitialize Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶: Preinitialize Python from preconfig preconfiguration.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)¶: Preinitialize Python from preconfig preconfiguration and command line arguments (bytes strings).

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)¶: Preinitialize Python from preconfig preconfiguration and command line arguments (wide strings).

The caller is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().

For Python Configuration (PyPreConfig_InitPythonConfig()), if Python is initialized with command line arguments, the command line arguments must also be passed to preinitialize Python, since they have an effect on the pre-configuration like encodings. For example, the -X utf8 command line option enables the UTF-8 Mode.

PyMem_SetAllocator() can be called after Py_PreInitialize() and before Py_InitializeFromConfig() to install a custom memory allocator. It can be called before Py_PreInitialize() if PyPreConfig.allocator is set to PYMEM_ALLOCATOR_NOT_SET.

Python memory allocation functions like PyMem_RawMalloc() must not be used before Python preinitialization, whereas calling directly malloc() and free() is always safe. Py_DecodeLocale() must not be called before the preinitialization.

Example using the preinitialization to enable the UTF-8 Mode:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python will speak UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig¶

PyConfig¶

Structure containing most parameters to configure Python.

Structure methods:

void PyConfig_InitPythonConfig(PyConfig *config)¶: Initialize configuration with Python Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Initialize configuration with Isolated Configuration.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)¶

Copy the wide character string str into *config_str.