Python 初始化配置 — Python 文档

来自菜鸟教程
Python/docs/3.10/c-api/init config
跳转至：导航、​搜索

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)

将 项目 插入 列表 的 索引 。

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

index 必须大于或等于 0。

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

结构字段：

Py_ssize_t length

列表长度。

wchar_t **items

列出项目。


状态

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

预配置

type PyPreConfig

用于预初始化 Python 的结构。

初始化预配置的函数：

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

使用 Python Configuration 初始化预配置。

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

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

结构字段：

int allocator

Python 内存分配器的名称：

如果使用 --without-pymalloc 配置 Python ，则不支持 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。

请参阅 语言环境编码 。

默认值：1 在 Python 配置中，0 在独立配置中。

int coerce_c_locale

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

如果等于 1，则读取 LC_CTYPE 语言环境以决定是否应该对其进行强制转换。

请参阅 语言环境编码 。

默认值：-1 在 Python 配置中，0 在独立配置中。

int coerce_c_locale_warn

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

默认值：-1 在 Python 配置中，0 在独立配置中。

int dev_mode

如果非零，则启用 Python 开发模式 ：参见 PyConfig.dev_mode。

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

int isolated

隔离模式：参见 PyConfig.isolated。

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

int legacy_windows_fs_encoding

如果非零：

从 PYTHONLEGACYWINDOWSFSENCODING 环境变量值初始化。

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

默认值：0。

int parse_argv

如果非零，Py_PreInitializeFromArgs() 和 Py_PreInitializeFromBytesArgs() 解析它们的 argv 参数与常规 Python 解析命令行参数的方式相同：参见 Command Line参数。

默认值：1 在 Python 配置中，0 在独立配置中。

int use_environment

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

默认值：Python 配置中的 1 和独立配置中的 0。

int utf8_mode

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

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

默认值：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 内存分配函数如 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();

配置文件

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 配置。

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

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 时才会解析参数。

void PyConfig_Clear(PyConfig *config)

释放配置内存。

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

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

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

结构字段：

PyWideStringList argv

命令行参数：sys.argv。

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

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

默认值：NULL。

另请参阅 orig_argv 成员。

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 警告。 有关详细信息，请参阅 选择加入编码警告 。

默认值：0。

3.10 版中的新功能。

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 等于 0，则禁用 stdin、stdout 和 stderr 流的缓冲。

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

默认值：1 在 Python 配置中，0 在独立配置中。

int dev_mode

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

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

int dump_refs

转储 Python 引用？

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

通过 PYTHONDUMPREFS 环境变量设置为 1。

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

默认值：0。

wchar_t *exec_prefix

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

默认值：NULL。

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

wchar_t *executable

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

默认值：NULL。

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

int faulthandler

启用故障处理程序？

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

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

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

wchar_t *filesystem_encoding

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

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

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

其他平台的默认编码：

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

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

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

  • 否则，使用 语言环境编码 : 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 值：-1 在 Python 模式下，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 信号处理程序？

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

int interactive

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

通过 -i 命令行选项增加。

默认值：0。

int isolated

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

  • sys.path 既不包含脚本目录（从 argv[0] 或当前目录计算）也不包含用户的站点包目录。

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

  • 将 use_environment 和 user_site_directory 设置为 0。

默认值：0 在 Python 模式下，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。

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

默认值：0。

wchar_t *platlibdir

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

由 PYTHONPLATLIBDIR 环境变量设置。

默认值：由 configure --with-platlibdir 选项 设置的 PLATLIBDIR 宏的值（默认值："lib"）。

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

3.9 版中的新功能。

wchar_t *pythonpath_env

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

由 PYTHONPATH 环境变量设置。

默认值：NULL。

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

PyWideStringList module_search_paths
int module_search_paths_set

模块搜索路径：sys.path。

如果 module_search_paths_set 等于 0，计算 Python 路径配置 的函数会覆盖 module_search_paths 并将 module_search_paths_set[X12037]X[X12037]X ]。

默认值：空列表 (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 复制到 orig_argv 在修改 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 选项。

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

3.10 版更改： PyConfig.argv 参数现在仅在 PyConfig.parse_argv 等于 1 时才会解析。

int parser_debug

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

通过 -d 命令行选项增加。 设置为 PYTHONDEBUG 环境变量值。

默认值：0。

int pathconfig_warnings

在 Unix 上，如果非零，计算 Python 路径配置 可以将警告记录到 stderr。 如果等于 0，则取消这些警告。

它对 Windows 没有影响。

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

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

wchar_t *prefix

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

默认值：NULL。

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

wchar_t *program_name

用于初始化 可执行文件 和 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 的尾随命令行参数。

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

由 Py_RunMain() 使用。

默认值：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模块？

如果等于 0，则禁用模块站点的导入和它需要的 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 环境变量非空，请使用它。

默认编码：

默认错误处理程序：

  • 在 Windows 上：使用 "surrogateescape"。

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

  • "strict" 否则。

int tracemalloc

启用tracemalloc？

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

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

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

int use_environment

使用环境变量？

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

默认值：Python 配置中的 1 和独立配置中的 0。

int user_site_directory

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

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

通过 PYTHONNOUSERSITE 环境变量设置为 0。

默认值：1 在 Python 模式下，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 解析 命令行参数 的方式相同，并且从 argv 中删除 Python 参数。

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

更完整的例子修改默认配置，读取配置，然后覆盖一些参数： 

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

    /* Append our custom search path to sys.path */
    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 语言环境保持不变。 未安装信号处理程序。

配置文件仍然与此配置一起使用。 设置Python Path Configuration（“输出字段”）忽略这些配置文件，避免函数计算默认路径配置。


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 已设置。 在这种情况下，路径配置输入字段也会被忽略。

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

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

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

如果 site_import 非零，sys.path 可以被 site 模块修改。 如果 user_site_directory 非零且用户的站点包目录存在，则 site 模块将用户的站点包目录附加到 sys.path。

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

  • pyvenv.cfg
  • python._pth（仅限 Windows）
  • pybuilddir.txt（仅限 Unix）

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


Py_RunMain()

int Py_RunMain(void)

执行在命令行或在配置。

默认情况下，如果使用 -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 尚不存在）。
  • “Main”初始化阶段，Python完全初始化：

私有临时 API：

  • PyConfig._init_main：如果设置为 0，则 Py_InitializeFromConfig() 在“Core”初始化阶段停止。
  • PyConfig._isolated_interpreter：如果非零，则禁止线程、子进程和分叉。
PyStatus _Py_InitializeMain(void)
进入“Main”初始化阶段，完成Python初始化。

在“Core”阶段没有导入模块，并且没有配置importlib模块：Path Configuration仅在“Main”阶段应用。 它可能允许在 Python 中自定义 Python 以覆盖或调整 路径配置 ，可能安装自定义 sys.meta_path 导入器或导入钩子等。

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

“核心”阶段没有正确定义：在这个阶段什么应该可用，什么不应该可用还没有指定。 API 被标记为私有和临时：在设计出合适的公共 API 之前，可以随时修改甚至删除 API。

在“Core”和“Main”初始化阶段之间运行 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);
    }
}


取自“https://cainiaojiaocheng.com/index.php?title=Python/docs/3.10/c-api/init_config&oldid=22978”
Powered by MediaWiki