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 必须被预初始化以便调用此函数。

结构体字段:

Py_ssize_t length¶: List 长度。

wchar_t** items¶: 列表项目。

PyStatus¶

PyStatus¶

存储初始函数状态：成功、错误或退出的结构体。

对于错误，它可以存储造成错误的 C 函数的名称。

结构体字段:

int exitcode¶: 退出码。传给 exit() 的参数。

const char *err_msg¶: 错误信息

const char *func¶: 造成错误的函数的名称，可以为 NULL。

创建状态的函数:

PyStatus PyStatus_Ok(void)¶: 完成。

PyStatus PyStatus_Error(const char *err_msg)¶: 带消息的初始化错误。

PyStatus PyStatus_NoMemory(void)¶: 内存分配失败（内存不足）。

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

处理状态的函数:

int PyStatus_Exception(PyStatus status)¶: 状态为错误还是退出？如为真值，则异常必须被处理；例如通过调用 Py_ExitStatusException()。

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

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

void Py_ExitStatusException(PyStatus status)¶: 如果 status 是一个退出码则调用 exit(exitcode)。如果 status 是一个错误码则打印错误消息并设置一个非零退出码再退出。必须在 PyStatus_Exception(status) 为非零值时才能被调用。

注解

在内部，Python 将使用设置 PyStatus.func 的宏，而创建状态的函数则会将 func 设为 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 模式

用于初始化预先配置的函数:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: 通过 Python 配置来初始化预先配置。

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: 通过隔离配置来初始化预先配置。

结构体字段:

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¶: 如为非零值，则会在 C 语言区域被强制转换时发出警告。

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.

仅在 Windows 上可用。 #ifdef MS_WINDOWS 宏可被用于 Windows 专属的代码。

int parse_argv¶: 如为非零值，Py_PreInitializeFromArgs() 和 Py_PreInitializeFromBytesArgs() 将以与常规 Python 解析命令行参数的相同方式解析其 argv 参数：参见命令行参数。

int use_environment¶: 参见 PyConfig.use_environment.

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

Preinitialization with PyPreConfig¶

用于预初始化 Python 的函数：

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶: 根据 preconfig 预配置来预初始化 Python。

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

调用方要负责使用 PyStatus_Exception() 和 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() 可在 Py_PreInitialize() 之后、Py_InitializeFromConfig() 之前被调用以安装自定义的内存分配器。如果 PyPreConfig.allocator 被设为 PYMEM_ALLOCATOR_NOT_SET 则可在 Py_PreInitialize() 之前被调用。

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¶

包含了大部分用于配置 Python 的形参的结构体。

结构体方法:

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

将宽字符串 str 拷贝至 *config_str。