Cấu hình khởi tạo Python

PyInitConfig C API

Added in version 3.14.

Python có thể được khởi tạo bằng Py_InitializeFromInitConfig().

Hàm Py_RunMain() có thể được sử dụng để viết chương trình Python tùy chỉnh.

Xem thêm Initialization, Finalization, and Threads.

Xem thêm

PEP 741 "Cấu hình Python C API".

Ví dụ

Ví dụ về Python tùy chỉnh luôn chạy khi bật Python Development Mode; trả về -1 do lỗi:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    nếu (cấu hình == NULL) {
        printf("PYTHON INIT ERROR: cấp phát bộ nhớ không thành công\n");
        trả về -1;
    }

    // Kích hoạt Chế độ phát triển Python
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        lỗi đi đến;
    }

    // Khởi tạo Python với cấu hình
    if (Py_InitializeFromInitConfig(config) < 0) {
        lỗi đi đến;
    }
    PyInitConfig_Free(config);
    trả về 0;

lỗi:
    {
        // Hiển thị thông báo lỗi.
        //
        // Kiểu niềng răng không phổ biến này được sử dụng vì bạn không thể tạo
        // mục tiêu goto trỏ đến khai báo biến.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);
        trả về -1;
    }
}

Tạo cấu hình

struct PyInitConfig

Cấu trúc mờ để định cấu hình khởi tạo Python.

PyInitConfig *PyInitConfig_Create(void)

Tạo cấu hình khởi tạo mới bằng cách sử dụng các giá trị mặc định Isolated Configuration.

Nó phải được giải phóng bởi PyInitConfig_Free().

Trả về NULL khi cấp phát bộ nhớ không thành công.

void PyInitConfig_Free(PyInitConfig *config)

Bộ nhớ trống của cấu hình khởi tạo config.

Nếu config là NULL thì không có thao tác nào được thực hiện.

Xử lý lỗi

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

Nhận được thông báo lỗi config.

  • Đặt *err_msg và trả về 1 nếu có lỗi được đặt.

  • Đặt *err_msg thành NULL và trả về 0 nếu không.

Thông báo lỗi là chuỗi được mã hóa UTF-8.

Nếu config có mã thoát, hãy định dạng mã thoát dưới dạng thông báo lỗi.

Thông báo lỗi vẫn có hiệu lực cho đến khi một hàm PyInitConfig khác được gọi với config. Người gọi không cần phải giải phóng thông báo lỗi.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)

Lấy mã thoát config.

  • Đặt *exitcode và trả về 1 nếu config có bộ mã thoát.

  • Trả về 0 nếu config chưa đặt mã thoát.

Chỉ chức năng Py_InitializeFromInitConfig() mới có thể đặt mã thoát nếu tùy chọn parse_argv khác 0.

Bạn có thể đặt mã thoát khi phân tích dòng lệnh không thành công (mã thoát 2) hoặc khi tùy chọn dòng lệnh yêu cầu hiển thị trợ giúp dòng lệnh (mã thoát 0).

Nhận tùy chọn

Tham số name tùy chọn cấu hình phải là chuỗi được mã hóa UTF-8 không kết thúc bằng NULL. Xem Configuration Options.

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

Kiểm tra xem cấu hình có tùy chọn tên là name không.

Trả về 1 nếu tùy chọn tồn tại hoặc trả về 0 nếu không.

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

Nhận tùy chọn cấu hình số nguyên.

  • Đặt *value và trả về 0 nếu thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

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

Nhận tùy chọn cấu hình chuỗi dưới dạng chuỗi được mã hóa UTF-8 kết thúc bằng null.

  • Đặt *value và trả về 0 nếu thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

*value có thể được đặt thành NULL nếu tùy chọn là một chuỗi tùy chọn và tùy chọn này không được đặt.

Nếu thành công, chuỗi phải được giải phóng bằng free(value) nếu nó không phải là NULL.

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

Nhận tùy chọn cấu hình danh sách chuỗi dưới dạng một mảng các chuỗi được mã hóa UTF-8 kết thúc bằng null.

  • Đặt *length và *value và trả về 0 nếu thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

Nếu thành công, danh sách chuỗi phải được phát hành với PyInitConfig_FreeStrList(length, items).

void PyInitConfig_FreeStrList(size_t length, char **items)

Bộ nhớ trống của danh sách chuỗi được tạo bởi PyInitConfig_GetStrList().

Đặt tùy chọn

Tham số name tùy chọn cấu hình phải là chuỗi được mã hóa UTF-8 không kết thúc bằng NULL. Xem Configuration Options.

Một số tùy chọn cấu hình có tác dụng phụ đối với các tùy chọn khác. Logic này chỉ được triển khai khi Py_InitializeFromInitConfig() được gọi chứ không phải bởi các hàm "Set" bên dưới. Ví dụ: đặt dev_mode thành 1 không đặt faulthandler thành 1.

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

Đặt tùy chọn cấu hình số nguyên.

  • Trả về 0 khi thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

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

Đặt tùy chọn cấu hình chuỗi từ chuỗi được mã hóa UTF-8 kết thúc bằng null. Chuỗi được sao chép.

  • Trả về 0 khi thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

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

Đặt tùy chọn cấu hình danh sách chuỗi từ một mảng các chuỗi được mã hóa UTF-8 kết thúc bằng null. Danh sách chuỗi được sao chép.

  • Trả về 0 khi thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

mô-đun

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

Thêm mô-đun mở rộng tích hợp vào bảng mô-đun tích hợp.

Mô-đun mới có thể được nhập theo tên name và sử dụng hàm initfunc làm hàm khởi tạo được gọi trong lần nhập đầu tiên.

  • Trả về 0 khi thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

Nếu Python được khởi tạo nhiều lần, PyInitConfig_AddModule() phải được gọi ở mỗi lần khởi tạo Python.

Tương tự như chức năng PyImport_AppendInittab().

Khởi tạo Python

int Py_InitializeFromInitConfig(PyInitConfig *config)

Khởi tạo Python từ cấu hình khởi tạo.

  • Trả về 0 khi thành công.

  • Đặt lỗi trong config và trả về -1 khi có lỗi.

  • Đặt mã thoát trong config và trả về -1 nếu Python muốn thoát.

Xem PyInitConfig_GetExitcode() để biết trường hợp mã thoát.

Tùy chọn cấu hình

Lựa chọn

Thành viên PyConfig/PyPreConfig

Kiểu

Khả năng hiển thị

"allocator"

allocator

int

Chỉ đọc

"argv"

argv

list[str]

Công cộng

"base_exec_prefix"

base_exec_prefix

str

Công cộng

"base_executable"

base_executable

str

Công cộng

"base_prefix"

base_prefix

str

Công cộng

"buffered_stdio"

buffered_stdio

bool

Chỉ đọc

"bytes_warning"

bytes_warning

int

Công cộng

"check_hash_pycs_mode"

check_hash_pycs_mode

str

Chỉ đọc

"code_debug_ranges"

code_debug_ranges

bool

Chỉ đọc

"coerce_c_locale"

coerce_c_locale

bool

Chỉ đọc

"coerce_c_locale_warn"

coerce_c_locale_warn

bool

Chỉ đọc

"configure_c_stdio"

configure_c_stdio

bool

Chỉ đọc

"configure_locale"

configure_locale

bool

Chỉ đọc

"cpu_count"

cpu_count

int

Công cộng

"dev_mode"

dev_mode

bool

Chỉ đọc

"dump_refs"

dump_refs

bool

Chỉ đọc

"dump_refs_file"

dump_refs_file

str

Chỉ đọc

"exec_prefix"

exec_prefix

str

Công cộng

"executable"

executable

str

Công cộng

"faulthandler"

faulthandler

bool

Chỉ đọc

"filesystem_encoding"

filesystem_encoding

str

Chỉ đọc

"filesystem_errors"

filesystem_errors

str

Chỉ đọc

"hash_seed"

hash_seed

int

Chỉ đọc

"home"

home

str

Chỉ đọc

"import_time"

import_time

int

Chỉ đọc

"inspect"

inspect

bool

Công cộng

"install_signal_handlers"

install_signal_handlers

bool

Chỉ đọc

"int_max_str_digits"

int_max_str_digits

int

Công cộng

"interactive"

interactive

bool

Công cộng

"isolated"

isolated

bool

Chỉ đọc

"legacy_windows_fs_encoding"

legacy_windows_fs_encoding

bool

Chỉ đọc

"legacy_windows_stdio"

legacy_windows_stdio

bool

Chỉ đọc

"malloc_stats"

malloc_stats

bool

Chỉ đọc

"module_search_paths"

module_search_paths

list[str]

Công cộng

"optimization_level"

optimization_level

int

Công cộng

"orig_argv"

orig_argv

list[str]

Chỉ đọc

"parse_argv"

parse_argv

bool

Chỉ đọc

"parser_debug"

parser_debug

bool

Công cộng

"pathconfig_warnings"

pathconfig_warnings

bool

Chỉ đọc

"perf_profiling"

perf_profiling

bool

Chỉ đọc

"platlibdir"

platlibdir

str

Công cộng

"prefix"

prefix

str

Công cộng

"program_name"

program_name

str

Chỉ đọc

"pycache_prefix"

pycache_prefix

str

Công cộng

"quiet"

quiet

bool

Công cộng

"run_command"

run_command

str

Chỉ đọc

"run_filename"

run_filename

str

Chỉ đọc

"run_module"

run_module

str

Chỉ đọc

"run_presite"

run_presite

str

Chỉ đọc

"safe_path"

safe_path

bool

Chỉ đọc

"show_ref_count"

show_ref_count

bool

Chỉ đọc

"site_import"

site_import

bool

Chỉ đọc

"skip_source_first_line"

skip_source_first_line

bool

Chỉ đọc

"stdio_encoding"

stdio_encoding

str

Chỉ đọc

"stdio_errors"

stdio_errors

str

Chỉ đọc

"stdlib_dir"

stdlib_dir

str

Công cộng

"tracemalloc"

tracemalloc

int

Chỉ đọc

"use_environment"

use_environment

bool

Công cộng

"use_frozen_modules"

use_frozen_modules

bool

Chỉ đọc

"use_hash_seed"

use_hash_seed

bool

Chỉ đọc

"use_system_logger"

use_system_logger

bool

Chỉ đọc

"user_site_directory"

user_site_directory

bool

Chỉ đọc

"utf8_mode"

utf8_mode

bool

Chỉ đọc

"verbose"

verbose

int

Công cộng

"warn_default_encoding"

warn_default_encoding

bool

Chỉ đọc

"warnoptions"

warnoptions

list[str]

Công cộng

"write_bytecode"

write_bytecode

bool

Công cộng

"xoptions"

xoptions

dict[str, str]

Công cộng

"_pystats"

_pystats

bool

Chỉ đọc

Tầm nhìn:

Cấu hình Python thời gian chạy API

Trong thời gian chạy, có thể lấy và đặt các tùy chọn cấu hình bằng cách sử dụng các hàm PyConfig_Get() và PyConfig_Set().

Tham số name tùy chọn cấu hình phải là chuỗi được mã hóa UTF-8 không kết thúc bằng NULL. Xem Configuration Options.

Một số tùy chọn được đọc từ thuộc tính sys. Ví dụ: tùy chọn "argv" được đọc từ sys.argv.

PyObject *PyConfig_Get(const char *name)

Lấy giá trị thời gian chạy hiện tại của tùy chọn cấu hình dưới dạng đối tượng Python.

  • Trả lại một tài liệu tham khảo mới về thành công.

  • Đặt một ngoại lệ và trả về NULL khi có lỗi.

Loại đối tượng phụ thuộc vào tùy chọn cấu hình. Nó có thể là:

  • bool

  • int

  • str

  • list[str]

  • dict[str, str]

Người gọi phải có attached thread state. Hàm không thể được gọi trước khi khởi tạo Python cũng như sau khi hoàn thiện Python.

Added in version 3.14.

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

Tương tự như PyConfig_Get(), nhưng nhận giá trị dưới dạng C int.

  • Trả về 0 khi thành công.

  • Đặt một ngoại lệ và trả về -1 khi có lỗi.

Added in version 3.14.

PyObject *PyConfig_Names(void)

Nhận tất cả các tên tùy chọn cấu hình dưới dạng frozenset.

  • Trả lại một tài liệu tham khảo mới về thành công.

  • Đặt một ngoại lệ và trả về NULL khi có lỗi.

Người gọi phải có attached thread state. Hàm không thể được gọi trước khi khởi tạo Python cũng như sau khi hoàn thiện Python.

Added in version 3.14.

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

Đặt giá trị thời gian chạy hiện tại của tùy chọn cấu hình.

  • Tăng ValueError nếu không có tùy chọn name.

  • Tăng ValueError nếu value là giá trị không hợp lệ.

  • Tăng ValueError nếu tùy chọn ở chế độ chỉ đọc (không thể đặt).

  • Tăng TypeError nếu value không có loại thích hợp.

Người gọi phải có attached thread state. Hàm không thể được gọi trước khi khởi tạo Python cũng như sau khi hoàn thiện Python.

Tăng một auditing event cpython.PyConfig_Set với các đối số name, value.

Added in version 3.14.

PyConfig C API

Added in version 3.8.

Python có thể được khởi tạo bằng Py_InitializeFromConfig() và cấu trúc PyConfig. Nó có thể được khởi tạo trước với cấu trúc Py_PreInitialize() và PyPreConfig.

Có hai loại cấu hình:

  • Zz000zz có thể được sử dụng để xây dựng một Python tùy chỉnh hoạt động như Python thông thường. Ví dụ: các biến môi trường và đối số dòng lệnh được sử dụng để định cấu hình Python.

  • Zz000zz có thể được sử dụng để nhúng Python vào một ứng dụng. Nó cô lập Python khỏi hệ thống. Ví dụ: các biến môi trường bị bỏ qua, ngôn ngữ LC_CTYPE được giữ nguyên và không có bộ xử lý tín hiệu nào được đăng ký.

Hàm Py_RunMain() có thể được sử dụng để viết chương trình Python tùy chỉnh.

Xem thêm Initialization, Finalization, and Threads.

Xem thêm

PEP 587 "Cấu hình khởi tạo Python".

Ví dụ

Ví dụ về Python tùy chỉnh luôn chạy ở chế độ biệt lập:

int main(int argc, char **argv)
{
    Trạng thái PyStatus;

    Cấu hình PyConfig;
    PyConfig_InitPythonConfig(&config);
    config.isolat = 1;

    /* Giải mã các đối số dòng lệnh.
       Hoàn toàn khởi tạo trước Python (ở chế độ biệt lập). */
    trạng thái = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(trạng thái)) {
        ngoại lệ goto;
    }

    trạng thái = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(trạng thái)) {
        ngoại lệ goto;
    }
    PyConfig_Clear(&config);

    trả về Py_RunMain();

ngoại lệ:
    PyConfig_Clear(&config);
    nếu (PyStatus_IsExit(trạng thái)) {
        trả lại trạng thái.exitcode;
    }
    /* Hiển thị thông báo lỗi và thoát khỏi quá trình với
       mã thoát khác 0 */
    Py_ExitStatusException(trạng thái);
}

PyWideStringDanh sách

type PyWideStringList

Danh sách các chuỗi wchar_t*.

Nếu length khác 0 thì items phải khác NULL và tất cả các chuỗi phải khác NULL.

Phương pháp:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)

Nối item vào list.

Python phải được khởi tạo trước để gọi hàm này.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)

Chèn item vào list tại index.

Nếu index lớn hơn hoặc bằng độ dài list, hãy nối item vào list.

index phải lớn hơn hoặc bằng 0.

Python phải được khởi tạo trước để gọi hàm này.

Các trường cấu trúc:

Py_ssize_t length

Độ dài danh sách.

wchar_t **items

Liệt kê các mục.

Trạng thái Py

type PyStatus

Cấu trúc lưu trữ trạng thái hàm khởi tạo: thành công, lỗi hoặc thoát.

Khi có lỗi, nó có thể lưu tên hàm C đã tạo ra lỗi.

Các trường cấu trúc:

int exitcode

Mã thoát. Đối số được chuyển tới exit().

const char *err_msg

Thông báo lỗi.

const char *func

Tên của hàm tạo ra lỗi có thể là NULL.

Chức năng tạo trạng thái:

PyStatus PyStatus_Ok(void)

Thành công.

PyStatus PyStatus_Error(const char *err_msg)

Lỗi khởi tạo với một tin nhắn.

err_msg không được là NULL.

PyStatus PyStatus_NoMemory(void)

Lỗi cấp phát bộ nhớ (hết bộ nhớ).

PyStatus PyStatus_Exit(int exitcode)

Thoát Python với mã thoát được chỉ định.

Các hàm xử lý trạng thái:

int PyStatus_Exception(PyStatus status)

Trạng thái là lỗi hay thoát? Nếu đúng thì ngoại lệ phải được xử lý; bằng cách gọi Py_ExitStatusException() chẳng hạn.

int PyStatus_IsError(PyStatus status)

Kết quả có phải là lỗi không?

int PyStatus_IsExit(PyStatus status)

Kết quả là một lối thoát?

void Py_ExitStatusException(PyStatus status)

Gọi exit(exitcode) nếu status là một lối thoát. In thông báo lỗi và thoát với mã thoát khác 0 nếu status bị lỗi. Chỉ được gọi nếu PyStatus_Exception(status) khác 0.

Ghi chú

Trong nội bộ, Python sử dụng macro đặt PyStatus.func, trong khi các hàm tạo trạng thái được đặt func thành NULL.

Ví dụ:

Phân bổ PyStatus(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(kích thước);
    nếu (*ptr == NULL) {
        trả về PyStatus_NoMemory();
    }
    trả về PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    Trạng thái PyStatus = cấp phát(&ptr, 16);
    if (PyStatus_Exception(trạng thái)) {
        Py_ExitStatusException(trạng thái);
    }
    PyMem_Free(ptr);
    trả về 0;
}

PyPreConfig

type PyPreConfig

Cấu trúc được sử dụng để khởi tạo trước Python.

Chức năng khởi tạo cấu hình sẵn:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

Khởi tạo cấu hình sẵn với Python Configuration.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

Khởi tạo cấu hình sẵn với Isolated Configuration.

Các trường cấu trúc:

int allocator

Tên của bộ cấp phát bộ nhớ Python:

PYMEM_ALLOCATOR_PYMALLOC và PYMEM_ALLOCATOR_PYMALLOC_DEBUG không được hỗ trợ nếu Python là configured using --without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC và PYMEM_ALLOCATOR_MIMALLOC_DEBUG không được hỗ trợ nếu Python là configured using --without-mimalloc hoặc nếu không có hỗ trợ nguyên tử cơ bản.

Xem Memory Management.

Mặc định: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale

Đặt ngôn ngữ LC_CTYPE thành ngôn ngữ ưa thích của người dùng.

Nếu bằng 0, đặt các thành viên coerce_c_locale và coerce_c_locale_warn thành 0.

Xem locale encoding.

Mặc định: 1 trong cấu hình Python, 0 trong cấu hình biệt lập.

int coerce_c_locale

Nếu bằng 2, hãy ép buộc ngôn ngữ C.

Nếu bằng 1, hãy đọc ngôn ngữ LC_CTYPE để quyết định xem có nên ép buộc hay không.

Xem locale encoding.

Mặc định: -1 trong cấu hình Python, 0 trong cấu hình biệt lập.

int coerce_c_locale_warn

Nếu khác 0, hãy đưa ra cảnh báo nếu ngôn ngữ C bị ép buộc.

Mặc định: -1 trong cấu hình Python, 0 trong cấu hình biệt lập.

int dev_mode

Python Development Mode: xem PyConfig.dev_mode.

Mặc định: -1 ở chế độ Python, 0 ở chế độ biệt lập.

int isolated

Chế độ cách ly: xem PyConfig.isolated.

Mặc định: 0 ở chế độ Python, 1 ở chế độ biệt lập.

int legacy_windows_fs_encoding

Nếu khác 0:

Được khởi tạo từ giá trị biến môi trường PYTHONLEGACYWINDOWSFSENCODING.

Chỉ có sẵn trên Windows. Macro #ifdef MS_WINDOWS có thể được sử dụng cho mã cụ thể của Windows.

Mặc định: 0.

int parse_argv

Nếu khác 0, Py_PreInitializeFromArgs() và Py_PreInitializeFromBytesArgs() phân tích đối số argv của chúng giống như cách Python thông thường phân tích các đối số dòng lệnh: xem Command Line Arguments.

Mặc định: 1 trong cấu hình Python, 0 trong cấu hình biệt lập.

int use_environment

Sử dụng environment variables? Xem PyConfig.use_environment.

Mặc định: 1 trong cấu hình Python và 0 trong cấu hình biệt lập.

int utf8_mode

Nếu khác 0, hãy bật Python UTF-8 Mode.

Đặt thành 0 hoặc 1 bằng tùy chọn dòng lệnh -X utf8 và biến môi trường PYTHONUTF8.

Đồng thời đặt thành 1 nếu ngôn ngữ LC_CTYPE là C hoặc POSIX.

Mặc định: -1 trong cấu hình Python và 0 trong cấu hình biệt lập.

Khởi tạo trước Python bằng PyPreConfig

Quá trình khởi tạo trước của Python:

Cấu hình sẵn hiện tại (loại PyPreConfig) được lưu trữ trong _PyRuntime.preconfig.

Các hàm khởi tạo trước Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

Khởi tạo trước Python từ cấu hình sẵn preconfig.

preconfig không được là NULL.

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

Khởi tạo trước Python từ cấu hình sẵn preconfig.

Phân tích các đối số dòng lệnh argv (chuỗi byte) nếu parse_argv của preconfig khác 0.

preconfig không được là NULL.

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

Khởi tạo trước Python từ cấu hình sẵn preconfig.

Phân tích các đối số dòng lệnh argv (chuỗi rộng) nếu parse_argv của preconfig khác 0.

preconfig không được là NULL.

Người gọi có trách nhiệm xử lý các trường hợp ngoại lệ (lỗi hoặc thoát) bằng PyStatus_Exception() và Py_ExitStatusException().

Đối với Python Configuration (PyPreConfig_InitPythonConfig()), nếu Python được khởi tạo bằng các đối số dòng lệnh thì các đối số dòng lệnh cũng phải được chuyển để khởi tạo trước Python, vì chúng có ảnh hưởng đến cấu hình trước như mã hóa. Ví dụ: tùy chọn dòng lệnh -X utf8 kích hoạt Python UTF-8 Mode.

PyMem_SetAllocator() có thể được gọi sau Py_PreInitialize() và trước Py_InitializeFromConfig() để cài đặt bộ cấp phát bộ nhớ tùy chỉnh. Nó có thể được gọi trước Py_PreInitialize() nếu PyPreConfig.allocator được đặt thành PYMEM_ALLOCATOR_NOT_SET.

Không được sử dụng các hàm cấp phát bộ nhớ Python như PyMem_RawMalloc() trước khi khởi tạo trước Python, trong khi việc gọi trực tiếp malloc() và free() luôn an toàn. Py_DecodeLocale() không được gọi trước khi khởi tạo trước Python.

Ví dụ sử dụng quá trình khởi tạo trước để bật Python UTF-8 Mode:

Trạng thái PyStatus;
Cấu hình sẵn PyPreConfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

trạng thái = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(trạng thái)) {
    Py_ExitStatusException(trạng thái);
}

/* tại thời điểm này, Python nói UTF-8 */

Py_Initialize();
/* ... sử dụng Python API tại đây ... */
Py_Finalize();

PyConfig

type PyConfig

Cấu trúc chứa hầu hết các tham số để cấu hình Python.

Khi hoàn tất, chức năng PyConfig_Clear() phải được sử dụng để giải phóng bộ nhớ cấu hình.

Phương pháp kết cấu:

void PyConfig_InitPythonConfig(PyConfig *config)

Khởi tạo cấu hình với Python Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)

Khởi tạo cấu hình với Isolated Configuration.

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

Sao chép chuỗi ký tự rộng str vào *config_str.

Preinitialize Python nếu cần.

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

Giải mã str bằng Py_DecodeLocale() và đặt kết quả thành *config_str.

Preinitialize Python nếu cần.

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

Đặt đối số dòng lệnh (argv thành viên của config) từ danh sách argv gồm các chuỗi ký tự rộng.

Preinitialize Python nếu cần.

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

Đặt đối số dòng lệnh (thành viên argv của config) từ danh sách chuỗi byte argv. Giải mã byte bằng Py_DecodeLocale().

Preinitialize Python nếu cần.

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

Đặt danh sách các chuỗi rộng list thành length và items.

Preinitialize Python nếu cần.

PyStatus PyConfig_Read(PyConfig *config)

Đọc tất cả cấu hình Python.

Các trường đã được khởi tạo sẽ không thay đổi.

Các trường cho path configuration không còn được tính toán hoặc sửa đổi khi gọi hàm này kể từ Python 3.11.

Hàm PyConfig_Read() chỉ phân tích các đối số PyConfig.argv một lần: PyConfig.parse_argv được đặt thành 2 sau khi các đối số được phân tích cú pháp. Vì các đối số Python bị loại bỏ khỏi PyConfig.argv nên việc phân tích cú pháp các đối số hai lần sẽ phân tích các tùy chọn ứng dụng dưới dạng tùy chọn Python.

Preinitialize Python nếu cần.

Thay đổi trong phiên bản 3.10: Các đối số PyConfig.argv hiện chỉ được phân tích cú pháp một lần, PyConfig.parse_argv được đặt thành 2 sau khi các đối số được phân tích cú pháp và các đối số chỉ được phân tích cú pháp nếu PyConfig.parse_argv bằng 1.

Thay đổi trong phiên bản 3.11: PyConfig_Read() không còn tính toán tất cả các đường dẫn và do đó các trường được liệt kê trong Python Path Configuration có thể không còn được cập nhật cho đến khi Py_InitializeFromConfig() được gọi.

void PyConfig_Clear(PyConfig *config)

Giải phóng bộ nhớ cấu hình.

Hầu hết các phương pháp PyConfig preinitialize Python nếu cần. Trong trường hợp đó, cấu hình khởi tạo trước Python (PyPreConfig) dựa trên PyConfig. Nếu các trường cấu hình chung với PyPreConfig được điều chỉnh, chúng phải được đặt trước khi gọi phương thức PyConfig:

Hơn nữa, nếu PyConfig_SetArgv() hoặc PyConfig_SetBytesArgv() được sử dụng, phương thức này phải được gọi trước các phương thức khác, vì cấu hình khởi tạo trước phụ thuộc vào đối số dòng lệnh (nếu parse_argv khác 0).

Người gọi các phương thức này có trách nhiệm xử lý các trường hợp ngoại lệ (lỗi hoặc thoát) bằng PyStatus_Exception() và Py_ExitStatusException().

Các trường cấu trúc:

PyWideStringList argv

Đặt đối số dòng lệnh sys.argv dựa trên argv. Các tham số này tương tự như các tham số được truyền cho hàm main() của chương trình với điểm khác biệt là mục nhập đầu tiên phải đề cập đến tệp tập lệnh sẽ được thực thi thay vì tệp thực thi lưu trữ trình thông dịch Python. Nếu không có tập lệnh nào được chạy thì mục nhập đầu tiên trong argv có thể là một chuỗi trống.

Đặt parse_argv thành 1 để phân tích argv giống như cách Python thông thường phân tích các đối số dòng lệnh Python và sau đó loại bỏ các đối số Python khỏi argv.

Nếu argv trống, một chuỗi trống sẽ được thêm vào để đảm bảo rằng sys.argv luôn tồn tại và không bao giờ trống.

Mặc định: NULL.

Xem thêm thành viên orig_argv.

int safe_path

Nếu bằng 0, Py_RunMain() sẽ thêm một đường dẫn có thể không an toàn tới sys.path khi khởi động:

  • Nếu argv[0] bằng L"-m" (python -m module), hãy thêm vào thư mục làm việc hiện tại.

  • Nếu chạy tập lệnh (python script.py), hãy thêm thư mục của tập lệnh vào trước. Nếu đó là liên kết tượng trưng, ​​hãy giải quyết các liên kết tượng trưng.

  • Nếu không (python -c code và python), hãy thêm một chuỗi trống vào trước, có nghĩa là thư mục làm việc hiện tại.

Đặt thành 1 bằng tùy chọn dòng lệnh -P và biến môi trường PYTHONSAFEPATH.

Mặc định: 0 trong cấu hình Python, 1 trong cấu hình biệt lập.

Added in version 3.11.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.exec_prefix.

wchar_t *base_executable

Thực thi cơ sở Python: sys._base_executable.

Được đặt bởi biến môi trường __PYVENV_LAUNCHER__.

Đặt từ PyConfig.executable nếu NULL.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.executable.

wchar_t *base_prefix

sys.base_prefix.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.prefix.

int buffered_stdio

Nếu bằng 0 và configure_c_stdio khác 0, hãy tắt tính năng đệm trên thiết bị xuất chuẩn và thiết bị xuất chuẩn của luồng C.

Đặt thành 0 bằng tùy chọn dòng lệnh -u và biến môi trường PYTHONUNBUFFERED.

stdin luôn được mở ở chế độ đệm.

Mặc định: 1.

int bytes_warning

Nếu bằng 1, đưa ra cảnh báo khi so sánh bytes hoặc bytearray với str hoặc so sánh bytes với int.

Nếu bằng hoặc lớn hơn 2, hãy đưa ra ngoại lệ BytesWarning trong những trường hợp này.

Tăng lên bởi tùy chọn dòng lệnh -b.

Mặc định: 0.

int warn_default_encoding

Nếu khác 0, hãy phát ra cảnh báo EncodingWarning khi io.TextIOWrapper sử dụng mã hóa mặc định. Xem Cảnh báo mã hóa chọn tham gia để biết chi tiết.

Mặc định: 0.

Added in version 3.10.

int code_debug_ranges

Nếu bằng 0, sẽ vô hiệu hóa việc bao gồm ánh xạ dòng và cột cuối cùng trong đối tượng mã. Đồng thời vô hiệu hóa dấu mũ in truy ngược tới các vị trí lỗi cụ thể.

Đặt thành 0 theo biến môi trường PYTHONNODEBUGRANGES và theo tùy chọn dòng lệnh -X no_debug_ranges.

Mặc định: 1.

Added in version 3.11.

wchar_t *check_hash_pycs_mode

Kiểm soát hành vi xác thực của các tệp .pyc dựa trên hàm băm: giá trị của tùy chọn dòng lệnh --check-hash-based-pycs.

Giá trị hợp lệ:

  • L"always": Băm tệp nguồn để vô hiệu hóa bất kể giá trị của cờ 'check_source'.

  • L"never": Giả sử rằng pycs dựa trên hàm băm luôn hợp lệ.

  • L"default": Cờ 'check_source' trong pycs dựa trên hàm băm xác định tính vô hiệu.

Mặc định: L"default".

Xem thêm PEP 552 "pycs xác định".

int configure_c_stdio

Nếu khác 0, hãy định cấu hình luồng tiêu chuẩn C:

  • Trên Windows, đặt chế độ nhị phân (O_BINARY) trên stdin, stdout và stderr.

  • Nếu buffered_stdio bằng 0, hãy tắt tính năng đệm của các luồng stdin, stdout và stderr.

  • Nếu interactive khác 0, hãy bật tính năng đệm luồng trên stdin và stdout (chỉ thiết bị xuất chuẩn trên Windows).

Mặc định: 1 trong cấu hình Python, 0 trong cấu hình biệt lập.

int dev_mode

Nếu khác 0, hãy bật Python Development Mode.

Đặt thành 1 bằng tùy chọn -X dev và biến môi trường PYTHONDEVMODE.

Mặc định: -1 ở chế độ Python, 0 ở chế độ biệt lập.

int dump_refs

Kết xuất tài liệu tham khảo Python?

Nếu khác 0, hãy đổ tất cả các đối tượng vẫn còn tồn tại khi thoát.

Đặt thành 1 bằng biến môi trường PYTHONDUMPREFS.

Cần một bản dựng Python đặc biệt với macro Py_TRACE_REFS được xác định: xem configure --with-trace-refs option.

Mặc định: 0.

wchar_t *dump_refs_file

Tên tệp nơi chứa tham chiếu Python.

Được đặt bởi biến môi trường PYTHONDUMPREFSFILE.

Mặc định: NULL.

Added in version 3.11.

wchar_t *exec_prefix

Tiền tố thư mục dành riêng cho trang web nơi cài đặt các tệp Python phụ thuộc vào nền tảng: sys.exec_prefix.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.base_exec_prefix.

wchar_t *executable

Đường dẫn tuyệt đối của tệp nhị phân thực thi cho trình thông dịch Python: sys.executable.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.base_executable.

int faulthandler

Bật trình xử lý lỗi?

Nếu khác 0, hãy gọi faulthandler.enable() khi khởi động.

Được đặt thành 1 bởi -X faulthandler và biến môi trường PYTHONFAULTHANDLER.

Mặc định: -1 ở chế độ Python, 0 ở chế độ biệt lập.

wchar_t *filesystem_encoding

Filesystem encoding: sys.getfilesystemencoding().

Trên macOS, Android và VxWorks: sử dụng "utf-8" theo mặc định.

Trên Windows: sử dụng "utf-8" theo mặc định hoặc "mbcs" nếu legacy_windows_fs_encoding của PyPreConfig khác 0.

Mã hóa mặc định trên các nền tảng khác:

  • "utf-8" nếu PyPreConfig.utf8_mode khác 0.

  • "ascii" nếu Python phát hiện ra rằng nl_langinfo(CODESET) thông báo mã hóa ASCII, trong khi hàm mbstowcs() giải mã từ một mã hóa khác (thường là Latin1).

  • "utf-8" nếu nl_langinfo(CODESET) trả về một chuỗi trống.

  • Nếu không, hãy sử dụng kết quả locale encoding: nl_langinfo(CODESET).

Khi khởi động Python, tên mã hóa được chuẩn hóa thành tên codec Python. Ví dụ: "ANSI_X3.4-1968" được thay thế bằng "ascii".

Xem thêm thành viên filesystem_errors.

wchar_t *filesystem_errors

Filesystem error handler: sys.getfilesystemencodeerrors().

Trên Windows: sử dụng "surrogatepass" theo mặc định hoặc "replace" nếu legacy_windows_fs_encoding của PyPreConfig khác 0.

Trên các nền tảng khác: sử dụng "surrogateescape" theo mặc định.

Trình xử lý lỗi được hỗ trợ:

  • "strict"

  • "surrogateescape"

  • "surrogatepass" (chỉ được hỗ trợ với mã hóa UTF-8)

Xem thêm thành viên filesystem_encoding.

int use_frozen_modules

Nếu khác 0, hãy sử dụng các mô-đun cố định.

Được đặt bởi biến môi trường PYTHON_FROZEN_MODULES.

Mặc định: 1 trong bản phát hành hoặc 0 trong debug build.

unsigned long hash_seed
int use_hash_seed

Hạt giống hàm băm ngẫu nhiên.

Nếu use_hash_seed bằng 0, một hạt giống được chọn ngẫu nhiên khi khởi động Python và hash_seed bị bỏ qua.

Được đặt bởi biến môi trường PYTHONHASHSEED.

Giá trị use_hash_seed mặc định: -1 ở chế độ Python, 0 ở chế độ biệt lập.

wchar_t *home

Đặt thư mục "nhà" Python mặc định, nghĩa là vị trí của các thư viện Python tiêu chuẩn (xem PYTHONHOME).

Được đặt bởi biến môi trường PYTHONHOME.

Mặc định: NULL.

Một phần của đầu vào Python Path Configuration.

int import_time

Nếu 1, thời gian nhập hồ sơ. Nếu 2, hãy bao gồm đầu ra bổ sung cho biết thời điểm mô-đun nhập đã được tải.

Được đặt theo tùy chọn -X importtime và biến môi trường PYTHONPROFILEIMPORTTIME.

Mặc định: 0.

Thay đổi trong phiên bản 3.14: Đã thêm hỗ trợ cho import_time = 2

int inspect

Vào chế độ tương tác sau khi thực thi tập lệnh hoặc lệnh.

Nếu lớn hơn 0, hãy bật kiểm tra: khi tập lệnh được chuyển làm đối số đầu tiên hoặc tùy chọn -c được sử dụng, hãy chuyển sang chế độ tương tác sau khi thực thi tập lệnh hoặc lệnh, ngay cả khi sys.stdin dường như không phải là thiết bị đầu cuối.

Tăng lên bởi tùy chọn dòng lệnh -i. Đặt thành 1 nếu biến môi trường PYTHONINSPECT không trống.

Mặc định: 0.

int install_signal_handlers

Cài đặt trình xử lý tín hiệu Python?

Mặc định: 1 ở chế độ Python, 0 ở chế độ biệt lập.

int interactive

Nếu lớn hơn 0, hãy bật chế độ tương tác (REPL).

Tăng lên bởi tùy chọn dòng lệnh -i.

Mặc định: 0.

int int_max_str_digits

Định cấu hình integer string conversion length limitation. Giá trị ban đầu của -1 có nghĩa là giá trị sẽ được lấy từ dòng lệnh hoặc môi trường hoặc mặc định là 4300 (sys.int_info.default_max_str_digits). Giá trị 0 vô hiệu hóa giới hạn. Các giá trị lớn hơn 0 nhưng nhỏ hơn 640 (sys.int_info.str_digits_check_threshold) không được hỗ trợ và sẽ gây ra lỗi.

Được định cấu hình bằng cờ dòng lệnh -X int_max_str_digits hoặc biến môi trường PYTHONINTMAXSTRDIGITS.

Mặc định: -1 ở chế độ Python. 4300 (sys.int_info.default_max_str_digits) ở chế độ cách ly.

Added in version 3.12.

int cpu_count

Nếu giá trị của cpu_count không phải là -1 thì nó sẽ ghi đè các giá trị trả về của os.cpu_count(), os.process_cpu_count() và multiprocessing.cpu_count().

Được định cấu hình bằng cờ dòng lệnh -X cpu_count=n|default hoặc biến môi trường PYTHON_CPU_COUNT.

Mặc định: -1.

Added in version 3.13.

int isolated

Nếu lớn hơn 0, hãy bật chế độ cách ly:

  • Đặt safe_path thành 1: không thêm đường dẫn có thể không an toàn tới sys.path khi khởi động Python, chẳng hạn như thư mục hiện tại, thư mục của tập lệnh hoặc một chuỗi trống.

  • Đặt use_environment thành 0: bỏ qua các biến môi trường PYTHON.

  • Đặt user_site_directory thành 0: không thêm thư mục trang web của người dùng vào sys.path.

  • Python REPL không nhập readline cũng như không bật cấu hình dòng đọc mặc định trên lời nhắc tương tác.

Đặt thành 1 bằng tùy chọn dòng lệnh -I.

Mặc định: 0 ở chế độ Python, 1 ở chế độ biệt lập.

Xem thêm Isolated Configuration và PyPreConfig.isolated.

int legacy_windows_stdio

Nếu khác 0, hãy sử dụng io.FileIO thay vì io._WindowsConsoleIO cho sys.stdin, sys.stdout và sys.stderr.

Đặt thành 1 nếu biến môi trường PYTHONLEGACYWINDOWSSTDIO được đặt thành một chuỗi không trống.

Chỉ có sẵn trên Windows. Macro #ifdef MS_WINDOWS có thể được sử dụng cho mã cụ thể của Windows.

Mặc định: 0.

Xem thêm PEP 528 (Thay đổi mã hóa bảng điều khiển Windows thành UTF-8).

int malloc_stats

Nếu khác 0, hãy kết xuất số liệu thống kê trên Python pymalloc memory allocator khi thoát.

Đặt thành 1 bằng biến môi trường PYTHONMALLOCSTATS.

Tùy chọn này bị bỏ qua nếu Python là configured using the --without-pymalloc option.

Mặc định: 0.

wchar_t *platlibdir

Tên thư mục thư viện nền tảng: sys.platlibdir.

Được đặt bởi biến môi trường PYTHONPLATLIBDIR.

Mặc định: giá trị của macro PLATLIBDIR được đặt bởi configure --with-platlibdir option (mặc định: "lib" hoặc "DLLs" trên Windows).

Một phần của đầu vào Python Path Configuration.

Added in version 3.9.

Thay đổi trong phiên bản 3.11: Macro này hiện được sử dụng trên Windows để định vị các mô-đun mở rộng thư viện tiêu chuẩn, thường dưới DLLs. Tuy nhiên, để tương thích, hãy lưu ý rằng giá trị này bị bỏ qua đối với mọi bố cục không chuẩn, bao gồm các bản dựng trong cây và môi trường ảo.

wchar_t *pythonpath_env

Đường dẫn tìm kiếm mô-đun (sys.path) dưới dạng một chuỗi được phân tách bằng DELIM (os.pathsep).

Được đặt bởi biến môi trường PYTHONPATH.

Mặc định: NULL.

Một phần của đầu vào Python Path Configuration.

PyWideStringList module_search_paths
int module_search_paths_set

Đường dẫn tìm kiếm mô-đun: sys.path.

Nếu module_search_paths_set bằng 0, Py_InitializeFromConfig() sẽ thay thế module_search_paths và đặt module_search_paths_set thành 1.

Mặc định: danh sách trống (module_search_paths) và 0 (module_search_paths_set).

Một phần của đầu ra Python Path Configuration.

int optimization_level

Mức độ tối ưu hóa biên dịch:

  • 0: Trình tối ưu hóa lỗ nhìn trộm, đặt __debug__ thành True.

  • 1: Cấp 0, xóa xác nhận, đặt __debug__ thành False.

  • 2: Cấp 1, loại bỏ chuỗi tài liệu.

Tăng lên bởi tùy chọn dòng lệnh -O. Đặt thành giá trị biến môi trường PYTHONOPTIMIZE.

Mặc định: 0.

PyWideStringList orig_argv

Danh sách các đối số dòng lệnh ban đầu được truyền cho tệp thực thi Python: sys.orig_argv.

Nếu danh sách orig_argv trống và argv không phải là danh sách chỉ chứa một chuỗi trống, PyConfig_Read() sao chép argv vào orig_argv trước khi sửa đổi argv (nếu parse_argv khác 0).

Xem thêm thành viên argv và hàm Py_GetArgcArgv().

Mặc định: danh sách trống.

Added in version 3.10.

int parse_argv

Phân tích đối số dòng lệnh?

Nếu bằng 1, hãy phân tích argv giống như cách Python thông thường phân tích command line arguments và loại bỏ các đối số Python khỏi argv.

Hàm PyConfig_Read() chỉ phân tích các đối số PyConfig.argv một lần: PyConfig.parse_argv được đặt thành 2 sau khi các đối số được phân tích cú pháp. Vì các đối số Python bị loại bỏ khỏi PyConfig.argv nên việc phân tích cú pháp các đối số hai lần sẽ phân tích các tùy chọn ứng dụng dưới dạng tùy chọn Python.

Mặc định: 1 ở chế độ Python, 0 ở chế độ biệt lập.

Thay đổi trong phiên bản 3.10: Các đối số PyConfig.argv hiện chỉ được phân tích cú pháp nếu PyConfig.parse_argv bằng 1.

int parser_debug

Chế độ gỡ lỗi của trình phân tích cú pháp. Nếu lớn hơn 0, hãy bật đầu ra gỡ lỗi của trình phân tích cú pháp (chỉ dành cho chuyên gia, tùy thuộc vào các tùy chọn biên dịch).

Tăng lên bởi tùy chọn dòng lệnh -d. Đặt thành giá trị biến môi trường PYTHONDEBUG.

Cần một debug build of Python (phải xác định macro Py_DEBUG).

Mặc định: 0.

int pathconfig_warnings

Nếu khác 0, việc tính toán cấu hình đường dẫn được phép ghi cảnh báo vào stderr. Nếu bằng 0, hãy chặn những cảnh báo này.

Mặc định: 1 ở chế độ Python, 0 ở chế độ biệt lập.

Một phần của đầu vào Python Path Configuration.

Thay đổi trong phiên bản 3.11: Bây giờ cũng áp dụng trên Windows.

wchar_t *prefix

Tiền tố thư mục dành riêng cho trang web nơi cài đặt các tệp Python độc lập với nền tảng: sys.prefix.

Mặc định: NULL.

Một phần của đầu ra Python Path Configuration.

Xem thêm PyConfig.base_prefix.

wchar_t *program_name

Tên chương trình được sử dụng để khởi tạo executable và trong các thông báo lỗi ban đầu trong quá trình khởi tạo Python.

  • Trên macOS, sử dụng biến môi trường PYTHONEXECUTABLE nếu được đặt.

  • Nếu macro WITH_NEXT_FRAMEWORK được xác định, hãy sử dụng biến môi trường __PYVENV_LAUNCHER__ nếu được đặt.

  • Sử dụng argv[0] của argv nếu có và không trống.

  • Nếu không, hãy sử dụng L"python" trên Windows hoặc L"python3" trên các nền tảng khác.

Mặc định: NULL.

Một phần của đầu vào Python Path Configuration.

wchar_t *pycache_prefix

Thư mục chứa các tệp .pyc được lưu trong bộ nhớ cache: sys.pycache_prefix.

Được đặt bởi tùy chọn dòng lệnh -X pycache_prefix=PATH và biến môi trường PYTHONPYCACHEPREFIX. Tùy chọn dòng lệnh được ưu tiên.

Nếu NULL, sys.pycache_prefix được đặt thành None.

Mặc định: NULL.

int quiet

Chế độ yên tĩnh. Nếu lớn hơn 0, không hiển thị bản quyền và phiên bản khi khởi động Python ở chế độ tương tác.

Tăng lên bởi tùy chọn dòng lệnh -q.

Mặc định: 0.

wchar_t *run_command

Giá trị của tùy chọn dòng lệnh -c.

Được sử dụng bởi Py_RunMain().

Mặc định: NULL.

wchar_t *run_filename

Tên tệp được truyền trên dòng lệnh: đối số dòng lệnh ở cuối không có -c hoặc -m. Nó được sử dụng bởi hàm Py_RunMain().

Ví dụ: nó được đặt thành script.py bằng dòng lệnh python3 script.py arg.

Xem thêm tùy chọn PyConfig.skip_source_first_line.

Mặc định: NULL.

wchar_t *run_module

Giá trị của tùy chọn dòng lệnh -m.

Được sử dụng bởi Py_RunMain().

Mặc định: NULL.

wchar_t *run_presite

Đường dẫn package.module đến mô-đun cần được nhập trước khi chạy site.py.

Được đặt bởi tùy chọn dòng lệnh -X presite=package.module và biến môi trường PYTHON_PRESITE. Tùy chọn dòng lệnh được ưu tiên.

Cần một debug build of Python (phải xác định macro Py_DEBUG).

Mặc định: NULL.

int show_ref_count

Hiển thị tổng số tham chiếu khi thoát (không bao gồm các đối tượng immortal)?

Đặt thành 1 bằng tùy chọn dòng lệnh -X showrefcount.

Cần một debug build of Python (phải xác định macro Py_REF_DEBUG).

Mặc định: 0.

int site_import

Nhập mô-đun site khi khởi động?

Nếu bằng 0, hãy vô hiệu hóa việc nhập trang web mô-đun và các thao tác phụ thuộc vào trang web của sys.path mà nó đòi hỏi.

Đồng thời tắt các thao tác này nếu mô-đun site được nhập rõ ràng sau này (gọi site.main() nếu bạn muốn chúng được kích hoạt).

Đặt thành 0 bằng tùy chọn dòng lệnh -S.

sys.flags.no_site được đặt thành giá trị đảo ngược của site_import.

Mặc định: 1.

int skip_source_first_line

Nếu khác 0, hãy bỏ qua dòng đầu tiên của nguồn PyConfig.run_filename.

Nó cho phép sử dụng các dạng #!cmd không phải Unix. Điều này chỉ dành cho một bản hack cụ thể DOS.

Đặt thành 1 bằng tùy chọn dòng lệnh -x.

Mặc định: 0.

wchar_t *stdio_encoding
wchar_t *stdio_errors

Mã hóa và lỗi mã hóa của sys.stdin, sys.stdout và sys.stderr (nhưng sys.stderr luôn sử dụng trình xử lý lỗi "backslashreplace").

Sử dụng biến môi trường PYTHONIOENCODING nếu nó không trống.

Mã hóa mặc định:

Trình xử lý lỗi mặc định:

  • Trên Windows: sử dụng "surrogateescape".

  • "surrogateescape" nếu PyPreConfig.utf8_mode khác 0 hoặc nếu ngôn ngữ LC_CTYPE là "C" hoặc "POSIX".

  • "strict" nếu không thì.

Xem thêm PyConfig.legacy_windows_stdio.

int tracemalloc

Kích hoạt tracemalloc?

Nếu khác 0, hãy gọi tracemalloc.start() khi khởi động.

Được đặt theo tùy chọn dòng lệnh -X tracemalloc=N và bởi biến môi trường PYTHONTRACEMALLOC.

Mặc định: -1 ở chế độ Python, 0 ở chế độ biệt lập.

int perf_profiling

Kích hoạt tính năng hỗ trợ trình hồ sơ Linux perf?

Nếu bằng 1, hãy bật hỗ trợ cho trình lược tả perf của Linux.

Nếu bằng 2, hãy bật hỗ trợ cho trình lược tả perf Linux với hỗ trợ DWARF JIT.

Đặt thành 1 bằng tùy chọn dòng lệnh -X perf và biến môi trường PYTHONPERFSUPPORT.

Đặt thành 2 bằng tùy chọn dòng lệnh -X perf_jit và biến môi trường PYTHON_PERF_JIT_SUPPORT.

Mặc định: -1.

Xem thêm

Xem Hỗ trợ Python cho trình lược tả Linux perf để biết thêm thông tin.

Added in version 3.12.

wchar_t *stdlib_dir

Thư mục của thư viện chuẩn Python.

Mặc định: NULL.

Added in version 3.11.

int use_environment

Sử dụng environment variables?

Nếu bằng 0, bỏ qua environment variables.

Đặt thành 0 bằng biến môi trường -E.

Mặc định: 1 trong cấu hình Python và 0 trong cấu hình biệt lập.

int use_system_logger

Nếu khác 0, stdout và stderr sẽ được chuyển hướng đến nhật ký hệ thống.

Chỉ khả dụng trên macOS 10.12 trở lên và trên iOS.

Mặc định: 0 (không sử dụng nhật ký hệ thống) trên macOS; 1 trên iOS (sử dụng nhật ký hệ thống).

Added in version 3.14.

int user_site_directory

Nếu khác 0, hãy thêm thư mục trang web của người dùng vào sys.path.

Đặt thành 0 bằng các tùy chọn dòng lệnh -s và -I.

Đặt thành 0 bằng biến môi trường PYTHONNOUSERSITE.

Mặc định: 1 ở chế độ Python, 0 ở chế độ biệt lập.

int verbose

Chế độ dài dòng. Nếu lớn hơn 0, hãy in thông báo mỗi khi mô-đun được nhập, hiển thị vị trí (tên tệp hoặc mô-đun tích hợp) mà mô-đun được tải từ đó.

Nếu lớn hơn hoặc bằng 2, hãy in thông báo cho từng tệp được kiểm tra khi tìm kiếm mô-đun. Cũng cung cấp thông tin về việc dọn dẹp mô-đun khi thoát.

Tăng lên bởi tùy chọn dòng lệnh -v.

Được đặt theo giá trị biến môi trường PYTHONVERBOSE.

Mặc định: 0.

PyWideStringList warnoptions

Các tùy chọn của mô-đun warnings để xây dựng bộ lọc cảnh báo, mức ưu tiên thấp nhất đến cao nhất: sys.warnoptions.

Mô-đun warnings thêm sys.warnoptions theo thứ tự ngược lại: mục PyConfig.warnoptions cuối cùng trở thành mục đầu tiên của warnings.filters được kiểm tra đầu tiên (mức độ ưu tiên cao nhất).

Các tùy chọn dòng lệnh -W thêm giá trị của nó vào warnoptions, nó có thể được sử dụng nhiều lần.

Biến môi trường PYTHONWARNINGS cũng có thể được sử dụng để thêm các tùy chọn cảnh báo. Nhiều tùy chọn có thể được chỉ định, phân tách bằng dấu phẩy (,).

Mặc định: danh sách trống.

int write_bytecode

Nếu bằng 0, Python sẽ không cố ghi các tệp .pyc khi nhập mô-đun nguồn.

Đặt thành 0 bằng tùy chọn dòng lệnh -B và biến môi trường PYTHONDONTWRITEBYTECODE.

sys.dont_write_bytecode được khởi tạo thành giá trị đảo ngược của write_bytecode.

Mặc định: 1.

PyWideStringList xoptions

Giá trị của các tùy chọn dòng lệnh -X: sys._xoptions.

Mặc định: danh sách trống.

int _pystats

Nếu khác 0, hãy ghi thống kê hiệu suất tại lối ra Python.

Cần bản dựng đặc biệt với macro Py_STATS: xem --enable-pystats.

Mặc định: 0.

Nếu parse_argv khác 0, các đối số argv sẽ được phân tích cú pháp giống như cách Python thông thường phân tích cú pháp command line arguments và các đối số Python sẽ bị loại bỏ khỏi argv.

Các tùy chọn xoptions được phân tích cú pháp để đặt các tùy chọn khác: xem tùy chọn dòng lệnh -X.

Thay đổi trong phiên bản 3.9: Trường show_alloc_count đã bị xóa.

Khởi tạo với PyConfig

Việc khởi tạo trình thông dịch từ cấu trúc cấu hình đã được điền được xử lý bằng cách gọi Py_InitializeFromConfig().

Người gọi có trách nhiệm xử lý các trường hợp ngoại lệ (lỗi hoặc thoát) bằng PyStatus_Exception() và Py_ExitStatusException().

Nếu PyImport_FrozenModules(), PyImport_AppendInittab() hoặc PyImport_ExtendInittab() được sử dụng, chúng phải được đặt hoặc gọi sau quá trình khởi tạo trước Python và trước khi khởi tạo Python. Nếu Python được khởi tạo nhiều lần, PyImport_AppendInittab() hoặc PyImport_ExtendInittab() phải được gọi trước mỗi lần khởi tạo Python.

Cấu hình hiện tại (loại PyConfig) được lưu trữ trong PyInterpreterState.config.

Ví dụ đặt tên chương trình:

void init_python(void)
{
    Trạng thái PyStatus;

    Cấu hình PyConfig;
    PyConfig_InitPythonConfig(&config);

    /* Đặt tên chương trình. Hoàn toàn khởi tạo trước Python. */
    trạng thái = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(trạng thái)) {
        ngoại lệ goto;
    }

    trạng thái = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(trạng thái)) {
        ngoại lệ goto;
    }
    PyConfig_Clear(&config);
    trở lại;

ngoại lệ:
    PyConfig_Clear(&config);
    Py_ExitStatusException(trạng thái);
}

Ví dụ đầy đủ hơn về sửa đổi cấu hình mặc định, đọc cấu hình và sau đó ghi đè một số tham số. Lưu ý rằng kể từ phiên bản 3.11, nhiều tham số không được tính toán cho đến khi khởi tạo và do đó không thể đọc được các giá trị từ cấu trúc cấu hình. Mọi giá trị được đặt trước khi khởi tạo được gọi sẽ không thay đổi khi khởi tạo

PyStatus init_python(const char *program_name)
{
    Trạng thái PyStatus;

    Cấu hình PyConfig;
    PyConfig_InitPythonConfig(&config);

    /* Đặt tên chương trình trước khi đọc cấu hình
       (giải mã chuỗi byte từ mã hóa miền địa phương).

       Hoàn toàn khởi tạo trước Python. */
    trạng thái = PyConfig_SetBytesString(&config, &config.program_name,
                                     tên_chương trình);
    if (PyStatus_Exception(trạng thái)) {
        phải làm xong;
    }

    /* Đọc tất cả cấu hình cùng một lúc */
    trạng thái = PyConfig_Read(&config);
    if (PyStatus_Exception(trạng thái)) {
        phải làm xong;
    }

    /* Chỉ định rõ ràng sys.path */
    /* Nếu bạn muốn sửa đổi tập hợp đường dẫn mặc định, hãy hoàn tất
       khởi tạo trước rồi sử dụng PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    trạng thái = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(trạng thái)) {
        phải làm xong;
    }
    trạng thái = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(trạng thái)) {
        phải làm xong;
    }

    /* Ghi đè tệp thực thi được tính toán bởi PyConfig_Read() */
    trạng thái = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(trạng thái)) {
        phải làm xong;
    }

    trạng thái = Py_InitializeFromConfig(&config);

xong:
    PyConfig_Clear(&config);
    trạng thái trả lại;
}

Cấu hình biệt lập

Các hàm PyPreConfig_InitIsolatedConfig() và PyConfig_InitIsolatedConfig() tạo cấu hình để tách Python khỏi hệ thống. Ví dụ: để nhúng Python vào một ứng dụng.

Cấu hình này bỏ qua các biến cấu hình chung, biến môi trường, đối số dòng lệnh (PyConfig.argv không được phân tích cú pháp) và thư mục trang web của người dùng. Các luồng tiêu chuẩn C (ví dụ: stdout) và ngôn ngữ LC_CTYPE không thay đổi. Bộ xử lý tín hiệu chưa được cài đặt.

Các tệp cấu hình vẫn được sử dụng với cấu hình này để xác định các đường dẫn không được chỉ định. Đảm bảo PyConfig.home được chỉ định để tránh tính toán cấu hình đường dẫn mặc định.

Cấu hình Python

Các hàm PyPreConfig_InitPythonConfig() và PyConfig_InitPythonConfig() tạo cấu hình để xây dựng một Python tùy chỉnh hoạt động như Python thông thường.

Các biến môi trường và đối số dòng lệnh được sử dụng để định cấu hình Python, trong khi các biến cấu hình chung bị bỏ qua.

Hàm này cho phép ép buộc ngôn ngữ C (PEP 538) và Python UTF-8 Mode (PEP 540) tùy thuộc vào các biến môi trường LC_CTYPE locale, PYTHONUTF8 và PYTHONCOERCECLOCALE.

Cấu hình đường dẫn Python

PyConfig chứa nhiều trường cho cấu hình đường dẫn:

Nếu ít nhất một "trường đầu ra" không được đặt, Python sẽ tính toán cấu hình đường dẫn để điền vào các trường chưa được đặt. Nếu module_search_paths_set bằng 0, module_search_paths bị ghi đè và module_search_paths_set được đặt thành 1.

Có thể bỏ qua hoàn toàn chức năng tính toán cấu hình đường dẫn mặc định bằng cách đặt rõ ràng tất cả các trường đầu ra cấu hình đường dẫn được liệt kê ở trên. Một chuỗi được coi là đã đặt ngay cả khi nó không trống. module_search_paths được coi là được đặt nếu module_search_paths_set được đặt thành 1. Trong trường hợp này, module_search_paths sẽ được sử dụng mà không sửa đổi.

Đặt pathconfig_warnings thành 0 để chặn cảnh báo khi tính toán cấu hình đường dẫn (Chỉ Unix, Windows không ghi lại bất kỳ cảnh báo nào).

Nếu các trường base_prefix hoặc base_exec_prefix không được đặt, chúng sẽ kế thừa giá trị tương ứng từ prefix và exec_prefix.

Py_RunMain() và Py_Main() sửa đổi sys.path:

  • Nếu run_filename được đặt và là thư mục chứa tập lệnh __main__.py, hãy thêm run_filename vào sys.path.

  • Nếu isolated bằng 0:

    • Nếu run_module được đặt, hãy thêm thư mục hiện tại vào sys.path. Không làm gì nếu thư mục hiện tại không thể đọc được.

    • Nếu run_filename được đặt, hãy thêm thư mục tên tệp vào sys.path.

    • Nếu không, hãy thêm một chuỗi trống vào sys.path.

Nếu site_import khác 0, sys.path có thể được sửa đổi bằng mô-đun site. Nếu user_site_directory khác 0 và thư mục gói trang web của người dùng tồn tại, mô-đun site sẽ nối thêm thư mục gói trang web của người dùng vào sys.path.

Các tệp cấu hình sau được sử dụng bởi cấu hình đường dẫn:

  • pyvenv.cfg

  • tập tin ._pth (ví dụ: python._pth)

  • pybuilddir.txt (chỉ Unix)

Nếu có tệp ._pth:

Nếu home không được đặt và tệp pyvenv.cfg có trong cùng thư mục với executable hoặc tệp mẹ của nó, prefix và exec_prefix được đặt ở vị trí đó. Khi điều này xảy ra, base_prefix và base_exec_prefix vẫn giữ giá trị của chúng, trỏ đến cài đặt cơ sở. Xem Môi trường ảo để biết thêm thông tin.

Biến môi trường __PYVENV_LAUNCHER__ được sử dụng để đặt PyConfig.base_executable.

Thay đổi trong phiên bản 3.14: prefix và exec_prefix hiện được đặt vào thư mục pyvenv.cfg. Điều này trước đây đã được thực hiện bởi site, do đó bị ảnh hưởng bởi -S.

Py_GetArgcArgv()

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

Lấy các đối số dòng lệnh ban đầu trước khi Python sửa đổi chúng.

Xem thêm thành viên PyConfig.orig_argv.

Trì hoãn việc thực thi mô-đun chính

Trong một số trường hợp sử dụng tính năng nhúng, có thể nên tách riêng việc khởi tạo trình thông dịch khỏi việc thực thi mô-đun chính.

Có thể đạt được sự phân tách này bằng cách đặt PyConfig.run_command thành chuỗi trống trong quá trình khởi tạo (để ngăn trình thông dịch rơi vào dấu nhắc tương tác), sau đó thực thi mã mô-đun chính mong muốn bằng cách sử dụng __main__.__dict__ làm không gian tên chung.