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 記憶體分配器的名稱

• 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 預初始化之前，不得使用 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.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 模組），則前置當前工作目錄。

• 如果正在執行指令碼（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 環境變數非空，則使用該變數。

預設編碼：

• 如果 PyPreConfig.utf8_mode 非零，則為 "UTF-8"。

• 否則，使用locale 編碼。

預設錯誤處理程式：

• 在 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 包含路徑配置的多個欄位

• 路徑配置輸入

  • 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 下的“SoftwarePythonPythonCoreX.YPythonPath”中的應用程式路徑（其中 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_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_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);
    }
}