Python 初始化配置¶

在 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 内存分配器以及调试钩子.

如果 Python 使用 --without-pymalloc 配置，则不支持 PYMEM_ALLOCATOR_PYMALLOC 和 PYMEM_ALLOCATOR_PYMALLOC_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() 解析其 argv 参数的方式与常规 Python 解析命令行参数的方式相同：参见命令行参数。

默认值：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¶

命令行参数：sys.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 路径配置输出的一部分。

wchar_t *base_executable¶

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

由 __PYVENV_LAUNCHER__ 环境变量设置。

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

默认值：NULL。

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

wchar_t *base_prefix¶

sys.base_prefix.

默认值：NULL。

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

int buffered_stdio¶

如果等于 0 并且 configure_c_stdio 不为零，则禁用 C 流 stdout 和 stderr 的缓冲。

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

stdin 始终以缓冲模式打开。

默认值：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 *exec_prefix¶

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

默认值：NULL。

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

wchar_t *executable¶

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

默认值：NULL。

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

int faulthandler¶

启用 faulthandler？

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

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

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

wchar_t *filesystem_encoding¶

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

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

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

其他平台上的默认编码

如果 PyPreConfig.utf8_mode 非零，则使用 "utf-8"。
如果 Python 检测到 nl_langinfo(CODESET) 宣布 ASCII 编码，而 mbstowcs() 函数从不同的编码（通常是 Latin1）解码，则使用 "ascii"。
如果 nl_langinfo(CODESET) 返回空字符串，则使用 "utf-8"。
否则，使用区域设置编码：nl_langinfo(CODESET) 结果。

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

另请参见 filesystem_errors 成员。

wchar_t *filesystem_errors¶

文件系统错误处理程序：sys.getfilesystemencodeerrors().

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

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

支持的错误处理程序

"strict"
"surrogateescape"
"surrogatepass"（仅在 UTF-8 编码中支持）

另请参见 filesystem_encoding 成员。

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 主目录。

如果 Py_SetPythonHome() 已被调用，则使用其参数（如果它不是 NULL）。

由 PYTHONHOME 环境变量设置。

默认值：NULL。

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

int import_time¶

如果非零，则分析导入时间。

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

默认值：0。

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

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

如果 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 选项 设置（默认值："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 之前（如果 parse_argv 非零）将 argv 复制到 orig_argv 中。

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

默认：空列表。

在 3.10 版本中添加。

int parse_argv¶

解析命令行参数？

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

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 路径配置输出的一部分。

wchar_t *program_name¶

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

如果已调用 Py_SetProgramName()，则使用其参数。
在 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。

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 特定的 hack。

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

默认值：0。

wchar_t *stdio_encoding¶

wchar_t *stdio_errors¶

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

如果已调用 Py_SetStandardStreamEncoding()，则使用其 error 和 errors 参数（如果它们不为 NULL）。

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

默认编码

如果 PyPreConfig.utf8_mode 不为零，则为 "UTF-8"。
否则，使用区域设置编码。

默认错误处理程序

在 Windows 上：使用 "surrogateescape"。
如果 PyPreConfig.utf8_mode 不为零，或者 LC_CTYPE 区域设置是“C”或“POSIX”，则为 "surrogateescape"。
否则为 "strict"。

int tracemalloc¶

启用 tracemalloc 吗？

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

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

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

int perf_profiling¶

启用与 perf 分析器兼容的模式吗？

如果非零，则初始化 perf 跳板。有关更多信息，请参见 Python 对 Linux perf 分析器的支持。

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

默认值：-1。

在 3.12 版本中添加。

int use_environment¶

使用环境变量吗？

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

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

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

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。

默认：空列表。

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

xoptions 选项被解析以设置其他选项：参见 -X 命令行选项。

版本 3.9 中的变更: 已移除 show_alloc_count 字段。

使用 PyConfig 初始化¶

用于初始化 Python 的函数

PyStatus Py_InitializeFromConfig(const PyConfig *config)¶: 从 config 配置初始化 Python。

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

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

当前配置（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) 注册表中“SoftwarePythonPythonCoreX.YPythonPath”下的应用程序路径，位于 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE（其中 X.Y 是 Python 版本）。
路径配置输出字段

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

可以通过显式设置上面列出的所有路径配置输出字段来完全忽略计算默认路径配置的函数。即使字符串非空，也认为它已设置。如果 module_search_paths_set 设置为 1，则认为 module_search_paths 已设置。在这种情况下，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。

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

Py_RunMain()¶

int Py_RunMain(void)¶

执行命令行或配置中指定的命令 (PyConfig.run_command)、脚本 (PyConfig.run_filename) 或模块 (PyConfig.run_module)。

默认情况下，以及当使用 -i 选项时，运行 REPL。

最后，完成 Python 并返回一个可以传递给 exit() 函数的退出状态。

有关使用 Py_RunMain() 使自定义 Python 始终在隔离模式下运行的示例，请参见 Python 配置。

Py_GetArgcArgv()¶

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

获取原始命令行参数，在 Python 修改它们之前。

另请参阅 PyConfig.orig_argv 成员。

多阶段初始化私有临时 API¶

本节是介绍多阶段初始化的私有临时 API，这是 PEP 432 的核心功能。

“核心”初始化阶段，“最少 Python”
- 内置类型；
- 内置异常；
- 内置和冻结模块；
- sys 模块仅部分初始化（例如：sys.path 尚未存在）。
“主”初始化阶段，Python 已完全初始化
- 安装和配置 importlib；
- 应用路径配置；
- 安装信号处理程序；
- 完成 sys 模块初始化（例如：创建 sys.stdout 和 sys.path）；
- 启用可选功能，如 faulthandler 和 tracemalloc；
- 导入 site 模块；
- 等等。

私有临时 API

PyConfig._init_main：如果设置为 0，Py_InitializeFromConfig() 在“核心”初始化阶段停止。

PyStatus _Py_InitializeMain(void)¶: 进入“主”初始化阶段，完成 Python 初始化。

在“核心”阶段不会导入任何模块，并且 importlib 模块未配置：路径配置仅在“主”阶段应用。它可能允许在 Python 中自定义 Python 以覆盖或调整路径配置，也许安装自定义的 sys.meta_path 导入器或导入钩子，等等。

它可能能够在 Python 中计算路径配置，在核心阶段之后和主阶段之前，这是 PEP 432 的动机之一。

“核心”阶段尚未明确定义：该阶段应该提供什么，不应该提供什么尚未确定。API 被标记为私有和临时：在设计出正式的公共 API 之前，API 随时可能被修改甚至删除。

“核心”和“主”初始化阶段之间运行 Python 代码的示例

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

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

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}

Python 初始化配置¶

示例¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

使用 PyPreConfig 预初始化 Python¶

PyConfig¶

使用 PyConfig 初始化¶

隔离配置¶

Python 配置¶

Python 路径配置¶

Py_RunMain()¶

Py_GetArgcArgv()¶

多阶段初始化私有临时 API¶

目录

上一主题

下一主题

本页