Python 初始化配置

3.8 版本中新增。

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

有两种配置类型：

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

在 index 处将 item 插入到 list 中。

如果 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 内存分配器的名称

如果 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

如果非零

从 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 的预初始化

当前的预配置（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 预初始化之前，不得使用 Python 内存分配函数，例如 PyMem_RawMalloc()，而直接调用 malloc() 和 free() 始终是安全的。在 Python 预初始化之前，不得调用 Py_DecodeLocale()。

使用预初始化来启用 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。在这种情况下，基于 PyConfig 的 Python 预初始化配置 (PyPreConfig)。如果调整了与 PyPreConfig 公用的配置字段，则必须在调用 PyConfig 方法之前设置它们。

此外，如果使用 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 模块），则前置当前工作目录。

  • 如果正在运行脚本（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 流 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 警告。 有关详细信息，请参阅 选择加入 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"：假定基于哈希的 pyc 始终有效。

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

默认值：L"default"。

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

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。

需要一个特殊的 Python 版本，其中定义了 Py_TRACE_REFS 宏：请参阅 configure --with-trace-refs 选项。

默认值：0。

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？

如果非零，则在启动时调用 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"。

  • 否则，使用区域设置编码： 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 成员。

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

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

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

默认值：0。

int inspect

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

如果大于 0，则启用 inspect：当脚本作为第一个参数传递或使用 -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 环境变量设置。

默认值：由 configure --with-platlibdir 选项 设置的 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 之前将 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

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

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

需要 Python 的调试版本（必须定义 Py_DEBUG 宏）。

默认值：NULL。

int show_ref_count

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

通过 -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 环境变量非空，则使用该变量。

默认编码：

默认错误处理程序：

  • 在 Windows 上：使用 "surrogateescape"。

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

  • 否则为 "strict"。

另请参阅 PyConfig.legacy_windows_stdio。

int tracemalloc

启用 tracemalloc？

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

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

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

int perf_profiling

启用与 perf profiler 的兼容模式？

如果非零，则初始化 perf trampoline。有关详细信息，请参阅 对 Linux perf profiler 的 Python 支持。

通过 -X perf 命令行选项和 PYTHON_PERF_JIT_SUPPORT 环境变量设置，以支持带有堆栈指针的 perf，以及通过 -X perf_jit 命令行选项和 PYTHON_PERF_JIT_SUPPORT 环境变量设置，以支持带有 DWARF JIT 信息的 perf。

默认值：-1。

在 3.12 版本中添加。

int use_environment

使用 环境变量 吗？

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

通过 -E 环境变量设置为 0。

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

int use_system_logger

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

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

默认值：0 (不使用系统日志)。

在 3.13.2 版本中添加。

int user_site_directory

如果非零，则将用户 site 目录添加到 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 非零，则会像常规 Python 解析 命令行参数 一样解析 argv 参数，并从 argv 中去除 Python 参数。

解析 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 版本起，许多参数要到初始化时才会计算，因此无法从配置结构中读取值。 在调用 initialize 之前设置的任何值都将在初始化时保持不变。

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，而忽略全局配置变量。

此函数启用 C 区域设置强制转换（PEP 538）和 Python UTF-8 模式（PEP 540），具体取决于 LC_CTYPE 区域设置、PYTHONUTF8 和 PYTHONCOERCECLOCALE 环境变量。

Python 路径配置

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

如果至少有一个“输出字段”未设置，则 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 文件

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

Py_GetArgcArgv()

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

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

另请参阅 PyConfig.orig_argv 成员。

多阶段初始化私有临时 API

本节是一个私有临时 API，引入了多阶段初始化，这是 PEP 432 的核心功能。

  • “核心”初始化阶段，“最基本的 Python”

    • 内置类型;

    • 内置异常;

    • 内置模块和冻结模块;

    • sys 模块仅部分初始化（例如：sys.path 尚不存在）。

  • “主”初始化阶段，Python 完全初始化

私有临时 API

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