Python 初始化配置

PyInitConfig C API

在 3.14 版本加入。

Python 可以使用 Py_InitializeFromInitConfig() 进行初始化。

Py_RunMain() 函数可以用来编写自定义的 Python 程序。

另请参阅 初始化、终止化和线程。

参见

PEP 741 “Python Configuration C API”。

示例

一个自定义 Python 始终在启用 Python 开发模式 下运行的示例；出错时返回 -1

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

创建配置

struct PyInitConfig

用于配置 Python 初始化的不透明结构。

PyInitConfig *PyInitConfig_Create(void)

使用 隔离配置 默认值创建新的初始化配置。

它必须通过 PyInitConfig_Free() 释放。

内存分配失败时返回 NULL。

void PyInitConfig_Free(PyInitConfig *config)

释放初始化配置 config 的内存。

如果 config 为 NULL，则不执行任何操作。

错误处理

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

获取 config 的错误消息。

• 如果设置了错误，则设置 *err_msg 并返回 1。

• 否则，将 *err_msg 设置为 NULL 并返回 0。

错误消息是 UTF-8 编码的字符串。

如果 config 有退出代码，则将退出代码格式化为错误消息。

错误消息在调用另一个带有 config 的 PyInitConfig 函数之前保持有效。调用者无需释放错误消息。

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)

获取 config 的退出代码。

• 如果 config 设置了退出代码，则设置 *exitcode 并返回 1。

• 如果 config 没有设置退出代码，则返回 0。

只有在 parse_argv 选项非零时，Py_InitializeFromInitConfig() 函数才能设置退出代码。

当命令行解析失败（退出代码 2）或命令行选项要求显示命令行帮助（退出代码 0）时，可以设置退出代码。

获取选项

配置选项 name 参数必须是一个非 NULL 的、以 null 结尾的 UTF-8 编码字符串。请参阅 配置选项。

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

测试配置是否有一个名为 name 的选项。

如果选项存在，则返回 1，否则返回 0。

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

获取整数配置选项。

• 设置 *value，成功时返回 0。

• 在 config 中设置错误并返回 -1。

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

将字符串配置选项获取为以 null 结尾的 UTF-8 编码字符串。

• 设置 *value，成功时返回 0。

• 在 config 中设置错误并返回 -1。

如果选项是可选字符串且未设置，*value 可以设置为 NULL。

成功时，如果字符串不为 NULL，则必须使用 free(value) 释放。

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

将字符串列表配置选项获取为以 null 结尾的 UTF-8 编码字符串数组。

• 设置 *length 和 *value，成功时返回 0。

• 在 config 中设置错误并返回 -1。

成功时，字符串列表必须通过 PyInitConfig_FreeStrList(length, items) 释放。

void PyInitConfig_FreeStrList(size_t length, char **items)

释放由 PyInitConfig_GetStrList() 创建的字符串列表的内存。

设置选项

配置选项 name 参数必须是一个非 NULL 的、以 null 结尾的 UTF-8 编码字符串。请参阅 配置选项。

某些配置选项对其他选项具有副作用。此逻辑仅在调用 Py_InitializeFromInitConfig() 时实现，而不是通过下面的“Set”函数实现。例如，将 dev_mode 设置为 1 并不会将 faulthandler 设置为 1。

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

设置整数配置选项。

• 成功时返回 0。

• 在 config 中设置错误并返回 -1。

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

从以 null 结尾的 UTF-8 编码字符串设置字符串配置选项。字符串被复制。

• 成功时返回 0。

• 在 config 中设置错误并返回 -1。

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

从以 null 结尾的 UTF-8 编码字符串数组设置字符串列表配置选项。字符串列表被复制。

• 成功时返回 0。

• 在 config 中设置错误并返回 -1。

模块

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

将内置扩展模块添加到内置模块表中。

新模块可以按名称 name 导入，并使用函数 initfunc 作为首次尝试导入时调用的初始化函数。

• 成功时返回 0。

• 在 config 中设置错误并返回 -1。

如果 Python 被多次初始化，PyInitConfig_AddModule() 必须在每次 Python 初始化时调用。

类似于 PyImport_AppendInittab() 函数。

初始化 Python

int Py_InitializeFromInitConfig(PyInitConfig *config)

从初始化配置初始化 Python。

• 成功时返回 0。

• 在 config 中设置错误并返回 -1。

• 如果 Python 需要退出，则在 config 中设置退出代码并返回 -1。

有关退出代码的情况，请参阅 PyInitConfig_GetExitcode()。

配置选项

选项	PyConfig/PyPreConfig 成员	类型	可见性
"allocator"	allocator	int	只读
"argv"	argv	list[str]	公开
"base_exec_prefix"	base_exec_prefix	str	公开
"base_executable"	base_executable	str	公开
"base_prefix"	base_prefix	str	公开
"buffered_stdio"	buffered_stdio	bool	只读
"bytes_warning"	bytes_warning	int	公开
"check_hash_pycs_mode"	check_hash_pycs_mode	str	只读
"code_debug_ranges"	code_debug_ranges	bool	只读
"coerce_c_locale"	coerce_c_locale	bool	只读
"coerce_c_locale_warn"	coerce_c_locale_warn	bool	只读
"configure_c_stdio"	configure_c_stdio	bool	只读
"configure_locale"	configure_locale	bool	只读
"cpu_count"	cpu_count	int	公开
"dev_mode"	dev_mode	bool	只读
"dump_refs"	dump_refs	bool	只读
"dump_refs_file"	dump_refs_file	str	只读
"exec_prefix"	exec_prefix	str	公开
"executable"	executable	str	公开
"faulthandler"	faulthandler	bool	只读
"filesystem_encoding"	filesystem_encoding	str	只读
"filesystem_errors"	filesystem_errors	str	只读
"hash_seed"	hash_seed	int	只读
"home"	home	str	只读
"import_time"	import_time	int	只读
"inspect"	inspect	bool	公开
"install_signal_handlers"	install_signal_handlers	bool	只读
"int_max_str_digits"	int_max_str_digits	int	公开
"interactive"	交互	bool	公开
"isolated"	isolated	bool	只读
"legacy_windows_fs_encoding"	legacy_windows_fs_encoding	bool	只读
"legacy_windows_stdio"	legacy_windows_stdio	bool	只读
"malloc_stats"	malloc_stats	bool	只读
"module_search_paths"	module_search_paths	list[str]	公开
"optimization_level"	optimization_level	int	公开
"orig_argv"	orig_argv	list[str]	只读
"parse_argv"	parse_argv	bool	只读
"parser_debug"	parser_debug	bool	公开
"pathconfig_warnings"	pathconfig_warnings	bool	只读
"perf_profiling"	perf_profiling	bool	只读
"platlibdir"	platlibdir	str	公开
"prefix"	prefix	str	公开
"program_name"	program_name	str	只读
"pycache_prefix"	pycache_prefix	str	公开
"quiet"	quiet	bool	公开
"run_command"	run_command	str	只读
"run_filename"	run_filename	str	只读
"run_module"	run_module	str	只读
"run_presite"	run_presite	str	只读
"safe_path"	safe_path	bool	只读
"show_ref_count"	show_ref_count	bool	只读
"site_import"	site_import	bool	只读
"skip_source_first_line"	skip_source_first_line	bool	只读
"stdio_encoding"	stdio_encoding	str	只读
"stdio_errors"	stdio_errors	str	只读
"stdlib_dir"	stdlib_dir	str	公开
"tracemalloc"	tracemalloc	int	只读
"use_environment"	use_environment	bool	公开
"use_frozen_modules"	use_frozen_modules	bool	只读
"use_hash_seed"	use_hash_seed	bool	只读
"use_system_logger"	use_system_logger	bool	只读
"user_site_directory"	user_site_directory	bool	只读
"utf8_mode"	utf8_mode	bool	只读
"verbose"	verbose	int	公开
"warn_default_encoding"	warn_default_encoding	bool	只读
"warnoptions"	warnoptions	list[str]	公开
"write_bytecode"	write_bytecode	bool	公开
"xoptions"	xoptions	dict[str, str]	公开
"_pystats"	_pystats	bool	只读

可见性

• 公共：可通过 PyConfig_Get() 获取，并通过 PyConfig_Set() 设置。

• 只读：可通过 PyConfig_Get() 获取，但不能通过 PyConfig_Set() 设置。

运行时 Python 配置 API

在运行时，可以使用 PyConfig_Get() 和 PyConfig_Set() 函数获取和设置配置选项。

配置选项 name 参数必须是一个非 NULL 的、以 null 结尾的 UTF-8 编码字符串。请参阅 配置选项。

某些选项从 sys 属性读取。例如，选项 "argv" 从 sys.argv 读取。

PyObject *PyConfig_Get(const char *name)

获取配置选项的当前运行时值作为 Python 对象。

• 成功时返回一个新引用。

• 出错时设置一个异常并返回 NULL。

对象类型取决于配置选项。它可以是

• bool

• int

• str

• list[str]

• dict[str, str]

调用者必须具有 附加的线程状态。该函数不能在 Python 初始化之前或 Python 终止之后调用。

在 3.14 版本加入。

int PyConfig_GetInt(const char *name, int *value)

类似于 PyConfig_Get()，但将值作为 C 整型获取。

• 成功时返回 0。

• 出错时设置一个异常并返回 -1。

在 3.14 版本加入。

PyObject *PyConfig_Names(void)

以 frozenset 形式获取所有配置选项名称。

• 成功时返回一个新引用。

• 出错时设置一个异常并返回 NULL。

调用者必须具有 附加的线程状态。该函数不能在 Python 初始化之前或 Python 终止之后调用。

在 3.14 版本加入。

int PyConfig_Set(const char *name, PyObject *value)

设置配置选项的当前运行时值。

• 如果没有选项 name，则引发 ValueError。

• 如果 value 是无效值，则引发 ValueError。

• 如果选项是只读的（不能设置），则引发 ValueError。

• 如果 value 没有正确的类型，则引发 TypeError。

调用者必须具有 附加的线程状态。该函数不能在 Python 初始化之前或 Python 终止之后调用。

使用参数 name, value 触发 审计事件 cpython.PyConfig_Set。

在 3.14 版本加入。

PyConfig C API

在 3.8 版本加入。

Python 可以使用 Py_InitializeFromConfig() 和 PyConfig 结构体进行初始化。它可以使用 Py_PreInitialize() 和 PyPreConfig 结构体进行预初始化。

有两种配置

• Python 配置 可用于构建一个行为与常规 Python 相同的自定义 Python。例如，环境变量和命令行参数用于配置 Python。

• 隔离配置 可用于将 Python 嵌入到应用程序中。它将 Python 与系统隔离。例如，环境变量被忽略，LC_CTYPE 语言环境保持不变，并且不注册信号处理程序。

Py_RunMain() 函数可以用来编写自定义的 Python 程序。

另请参阅 初始化、终止化和线程。

参见

PEP 587 “Python 初始化配置”。

示例

始终在隔离模式下运行的自定义 Python 示例

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

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 必须大于或等于 0。

必须预初始化 Python 才能调用此函数。

结构字段

Py_ssize_t length

列表长度。

wchar_t **items

列表项。

PyStatus

type PyStatus

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

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

结构字段

int exitcode

退出代码。传递给 exit() 的参数。

const char *err_msg

错误消息。

const char *func

创建错误的函数名称，可以是 NULL。

创建状态的函数

PyStatus PyStatus_Ok(void)

成功。

PyStatus PyStatus_Error(const char *err_msg)

带有消息的初始化错误。

err_msg 不得为 NULL。

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

type PyPreConfig

用于预初始化 Python 的结构体。

初始化预配置的函数

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

使用 Python 配置 初始化预配置。

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

使用 隔离配置 初始化预配置。

结构字段

int allocator

Python 内存分配器的名称

• PYMEM_ALLOCATOR_NOT_SET (0)：不改变内存分配器（使用默认值）。

• PYMEM_ALLOCATOR_DEFAULT (1)：默认内存分配器。

• PYMEM_ALLOCATOR_DEBUG (2)：带有 调试钩子 的默认内存分配器。

• PYMEM_ALLOCATOR_MALLOC (3)：使用 C 库的 malloc()。

• PYMEM_ALLOCATOR_MALLOC_DEBUG (4)：强制使用带有 调试钩子 的 malloc()。

• PYMEM_ALLOCATOR_PYMALLOC (5)：Python pymalloc 内存分配器。

• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6)：带有 调试钩子 的Python pymalloc 内存分配器。

• PYMEM_ALLOCATOR_MIMALLOC (6)：使用 mimalloc，一个快速的 malloc 替代品。

• PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7)：使用 mimalloc，一个带有 调试钩子 的快速 malloc 替代品。

如果 Python 使用 --without-pymalloc 配置，则不支持 PYMEM_ALLOCATOR_PYMALLOC 和 PYMEM_ALLOCATOR_PYMALLOC_DEBUG。

如果 Python 使用 --without-mimalloc 配置 或底层原子支持不可用，则不支持 PYMEM_ALLOCATOR_MIMALLOC 和 PYMEM_ALLOCATOR_MIMALLOC_DEBUG。

请参阅 内存管理。

默认值：PYMEM_ALLOCATOR_NOT_SET。

int configure_locale

将 LC_CTYPE 语言环境设置为用户首选语言环境。

如果等于 0，则将 coerce_c_locale 和 coerce_c_locale_warn 成员设置为 0。

请参阅 语言环境编码。

默认值：Python 配置中为 1，隔离配置中为 0。

int coerce_c_locale

如果等于 2，则强制 C 语言环境。

如果等于 1，则读取 LC_CTYPE 语言环境以决定是否应强制。

请参阅 语言环境编码。

默认值：Python 配置中为 -1，隔离配置中为 0。

int coerce_c_locale_warn

如果非零，则在强制 C 语言环境时发出警告。

默认值：Python 配置中为 -1，隔离配置中为 0。

int dev_mode

Python 开发模式：请参阅 PyConfig.dev_mode。

默认值：Python 模式下为 -1，隔离模式下为 0。

int isolated

隔离模式：请参阅 PyConfig.isolated。

默认值：Python 模式下为 0，隔离模式下为 1。

int legacy_windows_fs_encoding

如果非零

• 将 PyPreConfig.utf8_mode 设置为 0，

• 将 PyConfig.filesystem_encoding 设置为 "mbcs"，

• 将 PyConfig.filesystem_errors 设置为 "replace"。

从 PYTHONLEGACYWINDOWSFSENCODING 环境变量值初始化。

仅在 Windows 上可用。#ifdef MS_WINDOWS 宏可用于 Windows 特定的代码。

默认值：0。

int parse_argv

如果非零，Py_PreInitializeFromArgs() 和 Py_PreInitializeFromBytesArgs() 将以常规 Python 解析命令行参数的相同方式解析其 argv 参数：请参阅 命令行参数。

默认值：Python 配置中为 1，隔离配置中为 0。

int use_environment

使用 环境变量？请参阅 PyConfig.use_environment。

默认值：Python 配置中为 1，隔离配置中为 0。

int utf8_mode

如果非零，则启用 Python UTF-8 模式。

通过 -X utf8 命令行选项和 PYTHONUTF8 环境变量设置为 0 或 1。

如果 LC_CTYPE 语言环境是 C 或 POSIX，也设置为 1。

默认值：Python 配置中为 -1，隔离配置中为 0。

使用 PyPreConfig 预初始化 Python

Python 的预初始化

• 设置 Python 内存分配器 (PyPreConfig.allocator)

• 配置 LC_CTYPE 语言环境 (语言环境编码)

• 设置 Python UTF-8 模式 (PyPreConfig.utf8_mode)

当前的预配置（PyPreConfig 类型）存储在 _PyRuntime.preconfig 中。

预初始化 Python 的函数

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

从 preconfig 预配置预初始化 Python。

preconfig 不得为 NULL。

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)

从 preconfig 预配置预初始化 Python。

如果 preconfig 的 parse_argv 非零，则解析 argv 命令行参数（字节字符串）。

preconfig 不得为 NULL。

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)

从 preconfig 预配置预初始化 Python。

如果 preconfig 的 parse_argv 非零，则解析 argv 命令行参数（宽字符串）。

preconfig 不得为 NULL。

调用者有责任使用 PyStatus_Exception() 和 Py_ExitStatusException() 处理异常（错误或退出）。

对于 Python 配置 (PyPreConfig_InitPythonConfig())，如果 Python 使用命令行参数初始化，则命令行参数也必须传递给预初始化 Python，因为它们对预配置（如编码）有影响。例如，-X utf8 命令行选项启用 Python UTF-8 模式。

PyMem_SetAllocator() 可以在 Py_PreInitialize() 之后和 Py_InitializeFromConfig() 之前调用，以安装自定义内存分配器。如果 PyPreConfig.allocator 设置为 PYMEM_ALLOCATOR_NOT_SET，则可以在 Py_PreInitialize() 之前调用它。

Python 内存分配函数（如 PyMem_RawMalloc()）在 Python 预初始化之前不得使用，而直接调用 malloc() 和 free() 始终是安全的。Py_DecodeLocale() 在 Python 预初始化之前不得调用。

使用预初始化启用 Python UTF-8 模式 的示例

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 speaks UTF-8 */

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

PyConfig

type PyConfig

包含大多数配置 Python 参数的结构体。

完成后，必须使用 PyConfig_Clear() 函数释放配置内存。

结构方法

void PyConfig_InitPythonConfig(PyConfig *config)

使用 Python 配置 初始化配置。

void PyConfig_InitIsolatedConfig(PyConfig *config)

使用 隔离配置 初始化配置。

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

将宽字符字符串 str 复制到 *config_str 中。

如果需要，预初始化 Python。

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)

使用 Py_DecodeLocale() 解码 str，并将结果设置到 *config_str 中。

如果需要，预初始化 Python。

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)

从宽字符字符串列表 argv 设置命令行参数（config 的 argv 成员）。

如果需要，预初始化 Python。

PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)

从字节字符串列表 argv 设置命令行参数（config 的 argv 成员）。使用 Py_DecodeLocale() 解码字节。

如果需要，预初始化 Python。

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)

将宽字符串列表 list 设置为 length 和 items。

如果需要，预初始化 Python。

PyStatus PyConfig_Read(PyConfig *config)

读取所有 Python 配置。

已初始化的字段保持不变。

从 Python 3.11 开始，调用此函数时不再计算或修改 路径配置 的字段。

PyConfig_Read() 函数只解析 PyConfig.argv 参数一次：在参数解析后，PyConfig.parse_argv 设置为 2。由于 Python 参数从 PyConfig.argv 中删除，两次解析参数会将应用程序选项解析为 Python 选项。

如果需要，预初始化 Python。

3.10 版中已更改: PyConfig.argv 参数现在只解析一次，参数解析后 PyConfig.parse_argv 设置为 2，并且只有当 PyConfig.parse_argv 等于 1 时才解析参数。

3.11 版中已更改: PyConfig_Read() 不再计算所有路径，因此在调用 Py_InitializeFromConfig() 之前，Python 路径配置 下列出的字段可能不再更新。

void PyConfig_Clear(PyConfig *config)

释放配置内存。

大多数 PyConfig 方法会在需要时预初始化 Python。在这种情况下，Python 预初始化配置（PyPreConfig）基于 PyConfig。如果调整了与 PyPreConfig 相同的配置字段，则必须在调用 PyConfig 方法之前设置它们。

• PyConfig.dev_mode

• PyConfig.isolated

• PyConfig.parse_argv

• PyConfig.use_environment

此外，如果使用了 PyConfig_SetArgv() 或 PyConfig_SetBytesArgv()，则此方法必须在其他方法之前调用，因为预初始化配置依赖于命令行参数（如果 parse_argv 非零）。

这些方法的调用者负责使用 PyStatus_Exception() 和 Py_ExitStatusException() 处理异常（错误或退出）。

结构字段

PyWideStringList argv

根据 argv 设置 sys.argv 命令行参数。这些参数与传递给程序的 main() 函数的参数类似，不同之处在于第一个条目应指向要执行的脚本文件，而不是托管 Python 解释器的可执行文件。如果没有要运行的脚本，则 argv 中的第一个条目可以为空字符串。

将 parse_argv 设置为 1，以与常规 Python 解析 Python 命令行参数相同的方式解析 argv，然后从 argv 中删除 Python 参数。

如果 argv 为空，则添加一个空字符串以确保 sys.argv 始终存在且从不为空。

默认值：NULL。

另请参阅 orig_argv 成员。

int safe_path

如果等于零，则 Py_RunMain() 在启动时将一个可能不安全的路径添加到 sys.path 中。

• 如果 argv[0] 等于 L"-m"（python -m module），则预置当前工作目录。

• 如果运行脚本（python script.py），则预置脚本的目录。如果是符号链接，则解析符号链接。

• 否则（python -c code 和 python），预置一个空字符串，这意味着当前工作目录。

由 -P 命令行选项和 PYTHONSAFEPATH 环境变量设置为 1。

默认值：Python 配置中为 0，隔离配置中为 1。

在 3.11 版本中新增。

wchar_t *base_exec_prefix

sys.base_exec_prefix.

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.exec_prefix。

wchar_t *base_executable

Python 基础可执行文件：sys._base_executable。

由 __PYVENV_LAUNCHER__ 环境变量设置。

如果 NULL，则从 PyConfig.executable 设置。

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.executable。

wchar_t *base_prefix

sys.base_prefix.

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.prefix。

int buffered_stdio

如果等于 0 并且 configure_c_stdio 非零，则禁用 C 标准输出和标准错误流上的缓冲。

由 -u 命令行选项和 PYTHONUNBUFFERED 环境变量设置为 0。

标准输入始终以缓冲模式打开。

默认值：1。

int bytes_warning

如果等于 1，则在比较 bytes 或 bytearray 与 str 时发出警告，或在比较 bytes 与 int 时发出警告。

如果等于或大于 2，则在这些情况下引发 BytesWarning 异常。

由 -b 命令行选项递增。

默认值：0。

int warn_default_encoding

如果非零，当 io.TextIOWrapper 使用其默认编码时，发出 EncodingWarning 警告。有关详细信息，请参阅 Opt-in EncodingWarning。

默认值：0。

在 3.10 版本加入。

int code_debug_ranges

如果等于 0，则禁用在代码对象中包含结束行和列映射。还禁用追溯打印插入符号到特定错误位置。

由 PYTHONNODEBUGRANGES 环境变量和 -X no_debug_ranges 命令行选项设置为 0。

默认值：1。

在 3.11 版本中新增。

wchar_t *check_hash_pycs_mode

控制基于哈希的 .pyc 文件的验证行为：--check-hash-based-pycs 命令行选项的值。

有效值

• L"always"：无论“check_source”标志的值如何，都对源文件进行哈希以进行失效。

• L"never"：假设基于哈希的 pycs 始终有效。

• L"default"：基于哈希的 pycs 中的“check_source”标志决定失效。

默认值：L"default"。

另请参阅 PEP 552 “确定性 pycs”。

int configure_c_stdio

如果非零，则配置 C 标准流。

• 在 Windows 上，设置 stdin、stdout 和 stderr 的二进制模式（O_BINARY）。

• 如果 buffered_stdio 等于零，则禁用 stdin、stdout 和 stderr 流的缓冲。

• 如果 interactive 非零，则启用 stdin 和 stdout 上的流缓冲（Windows 上仅 stdout）。

默认值：Python 配置中为 1，隔离配置中为 0。

int dev_mode

如果非零，则启用 Python 开发模式。

由 -X dev 选项和 PYTHONDEVMODE 环境变量设置为 1。

默认值：Python 模式下为 -1，隔离模式下为 0。

int dump_refs

转储 Python 引用？

如果非零，则转储退出时仍然活动的所有对象。

由 PYTHONDUMPREFS 环境变量设置为 1。

需要使用定义了 Py_TRACE_REFS 宏的特殊 Python 构建：请参阅 configure --with-trace-refs option。

默认值：0。

wchar_t *dump_refs_file

转储 Python 引用的文件名。

由 PYTHONDUMPREFSFILE 环境变量设置。

默认值：NULL。

在 3.11 版本中新增。

wchar_t *exec_prefix

安装平台相关 Python 文件的特定于站点的目录前缀：sys.exec_prefix。

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.base_exec_prefix。

wchar_t *executable

Python 解释器可执行二进制文件的绝对路径：sys.executable。

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.base_executable。

int faulthandler

启用错误处理器？

如果非零，则在启动时调用 faulthandler.enable()。

由 -X faulthandler 和 PYTHONFAULTHANDLER 环境变量设置为 1。

默认值：Python 模式下为 -1，隔离模式下为 0。

wchar_t *filesystem_encoding

文件系统编码：sys.getfilesystemencoding()。

在 macOS、Android 和 VxWorks 上：默认使用 "utf-8"。

在 Windows 上：默认使用 "utf-8"，如果 PyPreConfig 的 legacy_windows_fs_encoding 非零，则使用 "mbcs"。

其他平台上的默认编码

• 如果 PyPreConfig.utf8_mode 非零，则为 "utf-8"。

• 如果 Python 检测到 nl_langinfo(CODESET) 宣布 ASCII 编码，而 mbstowcs() 函数从不同的编码（通常是 Latin1）解码，则为 "ascii"。

• 如果 nl_langinfo(CODESET) 返回空字符串，则为 "utf-8"。

• 否则，使用 locale encoding：nl_langinfo(CODESET) 结果。

在 Python 启动时，编码名称被规范化为 Python 编解码器名称。例如，"ANSI_X3.4-1968" 被替换为 "ascii"。

另请参阅 filesystem_errors 成员。

wchar_t *filesystem_errors

文件系统错误处理器：sys.getfilesystemencodeerrors()。

在 Windows 上：默认使用 "surrogatepass"，如果 PyPreConfig 的 legacy_windows_fs_encoding 非零，则使用 "replace"。

在其他平台：默认使用 "surrogateescape"。

支持的错误处理器

• "strict"

• "surrogateescape"

• "surrogatepass"（仅支持 UTF-8 编码）

另请参阅 filesystem_encoding 成员。

int use_frozen_modules

如果非零，则使用冻结模块。

由 PYTHON_FROZEN_MODULES 环境变量设置。

默认值：发布版本中为 1，调试版本中为 0。

unsigned long hash_seed

int use_hash_seed

随机化哈希函数种子。

如果 use_hash_seed 为零，则在 Python 启动时随机选择一个种子，并忽略 hash_seed。

由 PYTHONHASHSEED 环境变量设置。

默认的 use_hash_seed 值：Python 模式下为 -1，隔离模式下为 0。

wchar_t *home

设置默认的 Python “home” 目录，即标准 Python 库的位置（请参阅 PYTHONHOME）。

由 PYTHONHOME 环境变量设置。

默认值：NULL。

Python 路径配置 输入的一部分。

int import_time

如果为 1，则分析导入时间。如果为 2，则包含额外的输出，指示导入的模块何时已加载。

由 -X importtime 选项和 PYTHONPROFILEIMPORTTIME 环境变量设置。

默认值：0。

3.14 版本中的变化: 增加了对 import_time = 2 的支持。

int inspect

执行脚本或命令后进入交互模式。

如果大于 0，则启用检查模式：当脚本作为第一个参数传递或使用 -c 选项时，执行脚本或命令后进入交互模式，即使 sys.stdin 似乎不是终端。

由 -i 命令行选项递增。如果 PYTHONINSPECT 环境变量非空，则设置为 1。

默认值：0。

int install_signal_handlers

安装 Python 信号处理器？

默认值：Python 模式下为 1，隔离模式下为 0。

int interactive

如果大于 0，则启用交互模式 (REPL)。

由 -i 命令行选项递增。

默认值：0。

int int_max_str_digits

配置整数字符串转换长度限制。初始值 -1 表示该值将从命令行或环境变量中获取，否则默认为 4300（sys.int_info.default_max_str_digits）。值为 0 会禁用限制。大于零但小于 640（sys.int_info.str_digits_check_threshold）的值不受支持，并将产生错误。

由 -X int_max_str_digits 命令行标志或 PYTHONINTMAXSTRDIGITS 环境变量配置。

默认值：Python 模式下为 -1。隔离模式下为 4300（sys.int_info.default_max_str_digits）。

3.12 新版功能.

int cpu_count

如果 cpu_count 的值不是 -1，那么它将覆盖 os.cpu_count()、os.process_cpu_count() 和 multiprocessing.cpu_count() 的返回值。

由 -X cpu_count=n|default 命令行标志或 PYTHON_CPU_COUNT 环境变量配置。

默认值：-1。

在 3.13 版本加入。

int isolated

如果大于 0，则启用隔离模式。

• 将 safe_path 设置为 1：在 Python 启动时，不要将可能不安全的路径（如当前目录、脚本目录或空字符串）添加到 sys.path 中。

• 将 use_environment 设置为 0：忽略 PYTHON 环境变量。

• 将 user_site_directory 设置为 0：不要将用户站点目录添加到 sys.path。

• Python REPL 不会导入 readline，也不会在交互式提示符下启用默认的 readline 配置。

由 -I 命令行选项设置为 1。

默认值：Python 模式下为 0，隔离模式下为 1。

另请参阅 隔离配置 和 PyPreConfig.isolated。

int legacy_windows_stdio

如果非零，则对 sys.stdin、sys.stdout 和 sys.stderr 使用 io.FileIO 而不是 io._WindowsConsoleIO。

如果 PYTHONLEGACYWINDOWSSTDIO 环境变量设置为非空字符串，则设置为 1。

仅在 Windows 上可用。#ifdef MS_WINDOWS 宏可用于 Windows 特定的代码。

默认值：0。

另请参阅 PEP 528（更改 Windows 控制台编码为 UTF-8）。

int malloc_stats

如果非零，则在退出时转储 Python pymalloc 内存分配器 的统计信息。

由 PYTHONMALLOCSTATS 环境变量设置为 1。

如果 Python 使用 --without-pymalloc 选项 配置，则忽略该选项。

默认值：0。

wchar_t *platlibdir

平台库目录名称：sys.platlibdir。

由 PYTHONPLATLIBDIR 环境变量设置。

默认值：PLATLIBDIR 宏的值，该值由 configure --with-platlibdir option 设置（默认值："lib"，Windows 上为 "DLLs"）。

Python 路径配置 输入的一部分。

在 3.9 版本中新增。

3.11 版本中的变化: 此宏现在在 Windows 上用于定位标准库扩展模块，通常在 DLLs 下。然而，为了兼容性，请注意，对于任何非标准布局（包括树内构建和虚拟环境），此值都会被忽略。

wchar_t *pythonpath_env

模块搜索路径（sys.path）作为由 DELIM（os.pathsep）分隔的字符串。

由 PYTHONPATH 环境变量设置。

默认值：NULL。

Python 路径配置 输入的一部分。

PyWideStringList module_search_paths

int module_search_paths_set

模块搜索路径：sys.path。

如果 module_search_paths_set 等于 0，Py_InitializeFromConfig() 将替换 module_search_paths 并将 module_search_paths_set 设置为 1。

默认值：空列表（module_search_paths）和 0（module_search_paths_set）。

Python 路径配置 输出的一部分。

int optimization_level

编译优化级别。

• 0：窥孔优化器，将 __debug__ 设置为 True。

• 1：级别 0，移除断言，将 __debug__ 设置为 False。

• 2：级别 1，移除文档字符串。

由 -O 命令行选项递增。设置为 PYTHONOPTIMIZE 环境变量的值。

默认值：0。

PyWideStringList orig_argv

传递给 Python 可执行文件的原始命令行参数列表：sys.orig_argv。

如果 orig_argv 列表为空且 argv 不是仅包含空字符串的列表，PyConfig_Read() 在修改 argv 之前将 argv 复制到 orig_argv（如果 parse_argv 非零）。

另请参阅 argv 成员和 Py_GetArgcArgv() 函数。

默认值：空列表。

在 3.10 版本加入。

int parse_argv

解析命令行参数？

如果等于 1，则以常规 Python 解析命令行参数的相同方式解析 argv，并从 argv 中删除 Python 参数。

PyConfig_Read() 函数只解析 PyConfig.argv 参数一次：在参数解析后，PyConfig.parse_argv 设置为 2。由于 Python 参数从 PyConfig.argv 中删除，两次解析参数会将应用程序选项解析为 Python 选项。

默认值：Python 模式下为 1，隔离模式下为 0。

3.10 版本中的变化: 现在仅当 PyConfig.parse_argv 等于 1 时，才解析 PyConfig.argv 参数。

int parser_debug

解析器调试模式。如果大于 0，则打开解析器调试输出（仅限专家，取决于编译选项）。

由 -d 命令行选项递增。设置为 PYTHONDEBUG 环境变量的值。

需要 Python 的调试构建（必须定义 Py_DEBUG 宏）。

默认值：0。

int pathconfig_warnings

如果非零，则允许路径配置计算将警告记录到 stderr 中。如果等于 0，则抑制这些警告。

默认值：Python 模式下为 1，隔离模式下为 0。

Python 路径配置 输入的一部分。

3.11 版本中的变化: 现在也适用于 Windows。

wchar_t *prefix

安装平台无关 Python 文件的特定于站点的目录前缀：sys.prefix。

默认值：NULL。

Python 路径配置 输出的一部分。

另请参阅 PyConfig.base_prefix。

wchar_t *program_name

用于初始化 executable 和在 Python 初始化期间早期错误消息中使用的程序名称。

• 在 macOS 上，如果设置了 PYTHONEXECUTABLE 环境变量，则使用它。

• 如果定义了 WITH_NEXT_FRAMEWORK 宏，则如果设置了 __PYVENV_LAUNCHER__ 环境变量，则使用它。

• 如果可用且非空，则使用 argv 的 argv[0]。

• 否则，在 Windows 上使用 L"python"，在其他平台使用 L"python3"。

默认值：NULL。

Python 路径配置 输入的一部分。

wchar_t *pycache_prefix

缓存的 .pyc 文件写入的目录：sys.pycache_prefix。

由 -X pycache_prefix=PATH 命令行选项和 PYTHONPYCACHEPREFIX 环境变量设置。命令行选项优先。

如果为 NULL，则将 sys.pycache_prefix 设置为 None。

默认值：NULL。

int quiet

静默模式。如果大于 0，则在交互模式下 Python 启动时不显示版权和版本。

由 -q 命令行选项递增。

默认值：0。

wchar_t *run_command

-c 命令行选项的值。

由 Py_RunMain() 使用。

默认值：NULL。

wchar_t *run_filename

命令行上传递的文件名：不带 -c 或 -m 的尾随命令行参数。它由 Py_RunMain() 函数使用。

例如，通过 python3 script.py arg 命令行设置为 script.py。

另请参阅 PyConfig.skip_source_first_line 选项。

默认值：NULL。

wchar_t *run_module

-m 命令行选项的值。

由 Py_RunMain() 使用。

默认值：NULL。

wchar_t *run_presite

package.module 路径，指向应在 site.py 运行之前导入的模块。

由 -X presite=package.module 命令行选项和 PYTHON_PRESITE 环境变量设置。命令行选项优先。

需要 Python 的调试构建（必须定义 Py_DEBUG 宏）。

默认值：NULL。

int show_ref_count

在退出时显示总引用计数（不包括永生对象）？

由 -X showrefcount 命令行选项设置为 1。

需要 Python 的调试构建（必须定义 Py_REF_DEBUG 宏）。

默认值：0。

int site_import

在启动时导入 site 模块？

如果等于零，则禁用模块 site 的导入以及它所导致的 sys.path 的站点相关操作。

如果 site 模块稍后被显式导入，也会禁用这些操作（如果您希望触发它们，请调用 site.main()）。

由 -S 命令行选项设置为 0。

sys.flags.no_site 被设置为 site_import 的反转值。

默认值：1。

int skip_source_first_line

如果非零，则跳过 PyConfig.run_filename 源的第一行。

它允许使用非 Unix 形式的 #!cmd。这仅用于 DOS 特定的黑客手段。

由 -x 命令行选项设置为 1。

默认值：0。

wchar_t *stdio_encoding

wchar_t *stdio_errors

sys.stdin、sys.stdout 和 sys.stderr 的编码和编码错误（但 sys.stderr 始终使用 "backslashreplace" 错误处理器）。

如果 PYTHONIOENCODING 环境变量非空，则使用它。

默认编码

• 如果 PyPreConfig.utf8_mode 非零，则为 "UTF-8"。

• 否则，使用locale encoding。

默认错误处理器

• 在 Windows 上：使用 "surrogateescape"。

• 如果 PyPreConfig.utf8_mode 非零，或者 LC_CTYPE 区域设置为“C”或“POSIX”，则为 "surrogateescape"。

• 否则为 "strict"。

另请参阅 PyConfig.legacy_windows_stdio。

int tracemalloc

启用 tracemalloc？

如果非零，则在启动时调用 tracemalloc.start()。

由 -X tracemalloc=N 命令行选项和 PYTHONTRACEMALLOC 环境变量设置。

默认值：Python 模式下为 -1，隔离模式下为 0。

int perf_profiling

启用 Linux perf 分析器支持？

如果等于 1，则启用对 Linux perf 分析器的支持。

如果等于 2，则启用对带 DWARF JIT 支持的 Linux perf 分析器的支持。

由 -X perf 命令行选项和 PYTHONPERFSUPPORT 环境变量设置为 1。

由 -X perf_jit 命令行选项和 PYTHON_PERF_JIT_SUPPORT 环境变量设置为 2。

默认值：-1。

参见

有关详细信息，请参阅 Python 对 Linux perf 分析器的支持。

3.12 新版功能.

wchar_t *stdlib_dir

Python 标准库的目录。

默认值：NULL。

在 3.11 版本中新增。

int use_environment

使用环境变量？

如果等于零，则忽略环境变量。

由 -E 环境变量设置为 0。

默认值：Python 配置中为 1，隔离配置中为 0。

int use_system_logger

如果非零，则 stdout 和 stderr 将重定向到系统日志。

仅在 macOS 10.12 及更高版本以及 iOS 上可用。

默认值：macOS 上为 0（不使用系统日志）；iOS 上为 1（使用系统日志）。

在 3.14 版本加入。

int user_site_directory

如果非零，则将用户站点目录添加到 sys.path。

由 -s 和 -I 命令行选项设置为 0。

由 PYTHONNOUSERSITE 环境变量设置为 0。

默认值：Python 模式下为 1，隔离模式下为 0。

int verbose

详细模式。如果大于 0，则每次导入模块时打印一条消息，显示其加载位置（文件名或内置模块）。

如果大于或等于 2，则为搜索模块时检查的每个文件打印一条消息。还提供退出时模块清理的信息。

由 -v 命令行选项递增。

由 PYTHONVERBOSE 环境变量值设置。

默认值：0。

PyWideStringList warnoptions

warnings 模块的选项，用于构建警告过滤器，优先级从低到高：sys.warnoptions。

warnings 模块按相反顺序添加 sys.warnoptions：最后一个 PyConfig.warnoptions 项成为 warnings.filters 的第一个项，该项首先被检查（最高优先级）。

-W 命令行选项将其值添加到 warnoptions，它可以多次使用。

PYTHONWARNINGS 环境变量也可以用于添加警告选项。可以指定多个选项，用逗号（,）分隔。

默认值：空列表。

int write_bytecode

如果等于 0，则 Python 不会尝试在导入源模块时写入 .pyc 文件。

由 -B 命令行选项和 PYTHONDONTWRITEBYTECODE 环境变量设置为 0。

sys.dont_write_bytecode 初始化为 write_bytecode 的反转值。

默认值：1。

PyWideStringList xoptions

-X 命令行选项的值：sys._xoptions。

默认值：空列表。

int _pystats

如果非零，则在 Python 退出时写入性能统计信息。

需要使用 Py_STATS 宏进行特殊构建：请参阅 --enable-pystats。

默认值：0。

如果 parse_argv 为非零，argv 参数的解析方式与常规 Python 解析 命令行参数 的方式相同，并且 Python 参数将从 argv 中移除。

xoptions 选项用于设置其他选项：请参阅 -X 命令行选项。

3.9 版中的变化: show_alloc_count 字段已被移除。

使用 PyConfig 进行初始化

通过调用 Py_InitializeFromConfig() 来处理从已填充的配置结构初始化解释器。

调用者有责任使用 PyStatus_Exception() 和 Py_ExitStatusException() 处理异常（错误或退出）。

如果使用了 PyImport_FrozenModules()、PyImport_AppendInittab() 或 PyImport_ExtendInittab()，则必须在 Python 预初始化之后和 Python 初始化之前设置或调用它们。如果 Python 被多次初始化，PyImport_AppendInittab() 或 PyImport_ExtendInittab() 必须在每次 Python 初始化之前调用。

当前配置（PyConfig 类型）存储在 PyInterpreterState.config 中。

设置程序名称的示例

void init_python(void)
{
    PyStatus status;

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

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

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
}

更完整的示例：修改默认配置，读取配置，然后覆盖一些参数。请注意，自 3.11 版本以来，许多参数在初始化之前不会计算，因此无法从配置结构中读取值。在调用初始化之前设置的任何值在初始化后将保持不变。

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

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* 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;
    }

    /* 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;
}

隔离配置

PyPreConfig_InitIsolatedConfig() 和 PyConfig_InitIsolatedConfig() 函数用于创建隔离 Python 与系统的配置。例如，将 Python 嵌入到应用程序中。

此配置忽略全局配置变量、环境变量、命令行参数（PyConfig.argv 未解析）和用户站点目录。C 标准流（例如：stdout）和 LC_CTYPE 区域设置保持不变。不安装信号处理程序。

此配置仍使用配置文件来确定未指定的路径。确保指定 PyConfig.home 以避免计算默认路径配置。

Python 配置

PyPreConfig_InitPythonConfig() 和 PyConfig_InitPythonConfig() 函数用于创建配置，以构建行为与常规 Python 相同的定制 Python。

环境变量和命令行参数用于配置 Python，而全局配置变量被忽略。

此函数根据 LC_CTYPE 区域设置、PYTHONUTF8 和 PYTHONCOERCECLOCALE 环境变量启用 C 语言环境强制转换 (PEP 538) 和 Python UTF-8 模式 (PEP 540)。

Python 路径配置

PyConfig 包含用于路径配置的多个字段

• 路径配置输入

  • PyConfig.home

  • PyConfig.platlibdir

  • PyConfig.pathconfig_warnings

  • PyConfig.program_name

  • PyConfig.pythonpath_env

  • 当前工作目录：获取绝对路径

  • PATH 环境变量以获取程序完整路径（来自 PyConfig.program_name）

  • __PYVENV_LAUNCHER__ 环境变量

  • （仅限 Windows）注册表中的应用程序路径，位于 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE 的“Software\Python\PythonCore\X.Y\PythonPath”下（其中 X.Y 是 Python 版本）。

• 路径配置输出字段

  • PyConfig.base_exec_prefix

  • PyConfig.base_executable

  • PyConfig.base_prefix

  • PyConfig.exec_prefix

  • PyConfig.executable

  • PyConfig.module_search_paths_set, PyConfig.module_search_paths

  • PyConfig.prefix

如果至少有一个“输出字段”未设置，Python 会计算路径配置以填充未设置的字段。如果 module_search_paths_set 等于 0，则 module_search_paths 会被覆盖，并且 module_search_paths_set 会被设置为 1。

通过显式设置上面列出的所有路径配置输出字段，可以完全忽略计算默认路径配置的函数。即使字符串不为空，也被视为已设置。module_search_paths 在 module_search_paths_set 设置为 1 时被视为已设置。在这种情况下，module_search_paths 将不加修改地使用。

将 pathconfig_warnings 设置为 0 以抑制计算路径配置时的警告（仅限 Unix，Windows 不会记录任何警告）。

如果 base_prefix 或 base_exec_prefix 字段未设置，它们将分别从 prefix 和 exec_prefix 继承其值。

Py_RunMain() 和 Py_Main() 修改 sys.path

• 如果设置了 run_filename 并且它是一个包含 __main__.py 脚本的目录，则将 run_filename 添加到 sys.path 的开头。

• 如果 isolated 为零

  • 如果设置了 run_module，则将当前目录添加到 sys.path 的开头。如果无法读取当前目录，则不执行任何操作。

  • 如果设置了 run_filename，则将文件名的目录添加到 sys.path 的开头。

  • 否则，将空字符串添加到 sys.path 的开头。

如果 site_import 非零，sys.path 可以由 site 模块修改。如果 user_site_directory 非零且用户站点包目录存在，site 模块会将用户站点包目录添加到 sys.path 中。

路径配置使用以下配置文件

• pyvenv.cfg

• ._pth 文件（例如：python._pth）

• pybuilddir.txt（仅限 Unix）

如果存在 ._pth 文件

• 将 isolated 设置为 1。

• 将 use_environment 设置为 0。

• 将 site_import 设置为 0。

• 将 safe_path 设置为 1。

如果 home 未设置，并且在与 executable 相同或其父目录中存在 pyvenv.cfg 文件，则 prefix 和 exec_prefix 将设置为该位置。发生这种情况时，base_prefix 和 base_exec_prefix 仍保留其值，指向基本安装。有关更多信息，请参阅 虚拟环境。

__PYVENV_LAUNCHER__ 环境变量用于设置 PyConfig.base_executable。

3.14 版中的变化: prefix 和 exec_prefix 现在设置为 pyvenv.cfg 目录。这以前由 site 完成，因此受 -S 影响。

Py_GetArgcArgv()

void Py_GetArgcArgv(int *argc, wchar_t ***argv)

获取 Python 修改之前的原始命令行参数。

另请参阅 PyConfig.orig_argv 成员。

延迟主模块执行

在某些嵌入用例中，可能需要将解释器初始化与主模块的执行分开。

这种分离可以通过在初始化期间将 PyConfig.run_command 设置为空字符串（以防止解释器进入交互式提示符），然后随后使用 __main__.__dict__ 作为全局命名空间执行所需的主模块代码来实现。