Конфігурація ініціалізації Python¶

PyInitConfig C API¶

Added in version 3.14.

Python can be initialized with Py_InitializeFromInitConfig().

Функцію Py_RunMain() можна використовувати для написання спеціальної програми Python.

Дивіться також Ініціалізація, фіналізація та потоки.

Дивись також

PEP 741 «Python Configuration C API».

приклад¶

Example of customized Python always running with the Python Development Mode enabled; return -1 on error:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) {
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    }

    // Enable the Python Development Mode
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    PyInitConfig_Free(config);
    return 0;

error:
    {
        // Display the error message.
        //
        // This uncommon braces style is used, because you cannot make
        // goto targets point to variable declarations.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);
        return -1;
    }
}

Create Config¶

struct PyInitConfig¶: Opaque structure to configure the Python initialization.

PyInitConfig *PyInitConfig_Create(void)¶

Create a new initialization configuration using Isolated Configuration default values.

It must be freed by PyInitConfig_Free().

Return NULL on memory allocation failure.

void PyInitConfig_Free(PyInitConfig *config)¶

Free memory of the initialization configuration config.

If config is NULL, no operation is performed.

Error Handling¶

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

Get the config error message.

Set *err_msg and return 1 if an error is set.
Set *err_msg to NULL and return 0 otherwise.

An error message is an UTF-8 encoded string.

If config has an exit code, format the exit code as an error message.

The error message remains valid until another PyInitConfig function is called with config. The caller doesn’t have to free the error message.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶

Get the config exit code.

Set *exitcode and return 1 if config has an exit code set.
Return 0 if config has no exit code set.

Only the Py_InitializeFromInitConfig() function can set an exit code if the parse_argv option is non-zero.

An exit code can be set when parsing the command line failed (exit code 2) or when a command line option asks to display the command line help (exit code 0).

Get Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.

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

Test if the configuration has an option called name.

Return 1 if the option exists, or return 0 otherwise.

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

Get an integer configuration option.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

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

Get a string configuration option as a null-terminated UTF-8 encoded string.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

*value can be set to NULL if the option is an optional string and the option is unset.

On success, the string must be released with free(value) if it’s not NULL.

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

Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.

Set *length and *value, and return 0 on success.
Set an error in config and return -1 on error.

On success, the string list must be released with PyInitConfig_FreeStrList(length, items).

void PyInitConfig_FreeStrList(size_t length, char **items)¶: Free memory of a string list created by PyInitConfig_GetStrList().

Set Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.

Some configuration options have side effects on other options. This logic is only implemented when Py_InitializeFromInitConfig() is called, not by the «Set» functions below. For example, setting dev_mode to 1 does not set faulthandler to 1.

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

Set an integer configuration option.

Return 0 on success.
Set an error in config and return -1 on error.

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

Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.

Return 0 on success.
Set an error in config and return -1 on error.

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

Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.

Return 0 on success.
Set an error in config and return -1 on error.

Module¶

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

Add a built-in extension module to the table of built-in modules.

The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import.

Return 0 on success.
Set an error in config and return -1 on error.

If Python is initialized multiple times, PyInitConfig_AddModule() must be called at each Python initialization.

Similar to the PyImport_AppendInittab() function.

Initialize Python¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

Initialize Python from the initialization configuration.

Return 0 on success.
Set an error in config and return -1 on error.
Set an exit code in config and return -1 if Python wants to exit.

See PyInitConfig_GetExitcode() for the exit code case.

Configuration Options¶

Option	PyConfig/PyPreConfig member	Type	Visibility
`"allocator"`	`allocator`	`int`	Read-only
`"argv"`	`argv`	`list[str]`	Public
`"base_exec_prefix"`	`base_exec_prefix`	`str`	Public
`"base_executable"`	`base_executable`	`str`	Public
`"base_prefix"`	`base_prefix`	`str`	Public
`"buffered_stdio"`	`buffered_stdio`	`bool`	Read-only
`"bytes_warning"`	`bytes_warning`	`int`	Public
`"check_hash_pycs_mode"`	`check_hash_pycs_mode`	`str`	Read-only
`"code_debug_ranges"`	`code_debug_ranges`	`bool`	Read-only
`"coerce_c_locale"`	`coerce_c_locale`	`bool`	Read-only
`"coerce_c_locale_warn"`	`coerce_c_locale_warn`	`bool`	Read-only
`"configure_c_stdio"`	`configure_c_stdio`	`bool`	Read-only
`"configure_locale"`	`configure_locale`	`bool`	Read-only
`"cpu_count"`	`cpu_count`	`int`	Public
`"dev_mode"`	`dev_mode`	`bool`	Read-only
`"dump_refs"`	`dump_refs`	`bool`	Read-only
`"dump_refs_file"`	`dump_refs_file`	`str`	Read-only
`"exec_prefix"`	`exec_prefix`	`str`	Public
`"executable"`	`executable`	`str`	Public
`"faulthandler"`	`faulthandler`	`bool`	Read-only
`"filesystem_encoding"`	`filesystem_encoding`	`str`	Read-only
`"filesystem_errors"`	`filesystem_errors`	`str`	Read-only
`"hash_seed"`	`hash_seed`	`int`	Read-only
`"home"`	`home`	`str`	Read-only
`"import_time"`	`import_time`	`int`	Read-only
`"inspect"`	`inspect`	`bool`	Public
`"install_signal_handlers"`	`install_signal_handlers`	`bool`	Read-only
`"int_max_str_digits"`	`int_max_str_digits`	`int`	Public
`"interactive"`	`interactive`	`bool`	Public
`"isolated"`	`isolated`	`bool`	Read-only
`"legacy_windows_fs_encoding"`	`legacy_windows_fs_encoding`	`bool`	Read-only
`"legacy_windows_stdio"`	`legacy_windows_stdio`	`bool`	Read-only
`"malloc_stats"`	`malloc_stats`	`bool`	Read-only
`"module_search_paths"`	`module_search_paths`	`list[str]`	Public
`"optimization_level"`	`optimization_level`	`int`	Public
`"orig_argv"`	`orig_argv`	`list[str]`	Read-only
`"parse_argv"`	`parse_argv`	`bool`	Read-only
`"parser_debug"`	`parser_debug`	`bool`	Public
`"pathconfig_warnings"`	`pathconfig_warnings`	`bool`	Read-only
`"perf_profiling"`	`perf_profiling`	`bool`	Read-only
`"platlibdir"`	`platlibdir`	`str`	Public
`"prefix"`	`prefix`	`str`	Public
`"program_name"`	`program_name`	`str`	Read-only
`"pycache_prefix"`	`pycache_prefix`	`str`	Public
`"quiet"`	`quiet`	`bool`	Public
`"run_command"`	`run_command`	`str`	Read-only
`"run_filename"`	`run_filename`	`str`	Read-only
`"run_module"`	`run_module`	`str`	Read-only
`"run_presite"`	`run_presite`	`str`	Read-only
`"safe_path"`	`safe_path`	`bool`	Read-only
`"show_ref_count"`	`show_ref_count`	`bool`	Read-only
`"site_import"`	`site_import`	`bool`	Read-only
`"skip_source_first_line"`	`skip_source_first_line`	`bool`	Read-only
`"stdio_encoding"`	`stdio_encoding`	`str`	Read-only
`"stdio_errors"`	`stdio_errors`	`str`	Read-only
`"stdlib_dir"`	`stdlib_dir`	`str`	Public
`"tracemalloc"`	`tracemalloc`	`int`	Read-only
`"use_environment"`	`use_environment`	`bool`	Public
`"use_frozen_modules"`	`use_frozen_modules`	`bool`	Read-only
`"use_hash_seed"`	`use_hash_seed`	`bool`	Read-only
`"use_system_logger"`	`use_system_logger`	`bool`	Read-only
`"user_site_directory"`	`user_site_directory`	`bool`	Read-only
`"utf8_mode"`	`utf8_mode`	`bool`	Read-only
`"verbose"`	`verbose`	`int`	Public
`"warn_default_encoding"`	`warn_default_encoding`	`bool`	Read-only
`"warnoptions"`	`warnoptions`	`list[str]`	Public
`"write_bytecode"`	`write_bytecode`	`bool`	Public
`"xoptions"`	`xoptions`	`dict[str, str]`	Public
`"_pystats"`	`_pystats`	`bool`	Read-only

Visibility:

Public: Can by get by PyConfig_Get() and set by PyConfig_Set().
Read-only: Can by get by PyConfig_Get(), but cannot be set by PyConfig_Set().

Runtime Python configuration API¶

At runtime, it’s possible to get and set configuration options using PyConfig_Get() and PyConfig_Set() functions.

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.

Some options are read from the sys attributes. For example, the option "argv" is read from sys.argv.

PyObject *PyConfig_Get(const char *name)¶

Get the current runtime value of a configuration option as a Python object.

Return a new reference on success.
Set an exception and return NULL on error.

The object type depends on the configuration option. It can be:

bool
int
str
list[str]
dict[str, str]

The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

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

Similar to PyConfig_Get(), but get the value as a C int.

Return 0 on success.
Set an exception and return -1 on error.

Added in version 3.14.

PyObject *PyConfig_Names(void)¶

Get all configuration option names as a frozenset.

Return a new reference on success.
Set an exception and return NULL on error.

The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

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

Set the current runtime value of a configuration option.

Raise a ValueError if there is no option name.
Raise a ValueError if value is an invalid value.
Raise a ValueError if the option is read-only (cannot be set).
Raise a TypeError if value has not the proper type.

The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.

Raises an auditing event cpython.PyConfig_Set with arguments name, value.

Added in version 3.14.

PyConfig C API¶

Added in version 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)¶

Додайте елемент до списку.

Щоб викликати цю функцію, Python має бути попередньо ініціалізований.

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

Вставте елемент у список за індексом.

Якщо index більше або дорівнює довжині list, додайте item до list.

index must be greater than or equal to 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)¶: Викличте 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): використовуйте malloc() бібліотеки C.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): примусове використання malloc() з налагоджувальними хуками.
PYMEM_ALLOCATOR_PYMALLOC (5): Виділювач пам’яті Python pymalloc.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Розподіл пам’яті Python pymalloc з налагоджувальними хуками.
PYMEM_ALLOCATOR_MIMALLOC (6): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): use mimalloc, a fast malloc replacement with debug hooks.

PYMEM_ALLOCATOR_PYMALLOC і PYMEM_ALLOCATOR_PYMALLOC_DEBUG не підтримуються, якщо Python налаштовано за допомогою --without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC and PYMEM_ALLOCATOR_MIMALLOC_DEBUG are not supported if Python is configured using --without-mimalloc or if the underlying atomic support isn’t available.

Перегляньте Керування пам’яттю.

Типове значення: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale¶

Set the LC_CTYPE locale to the user preferred locale.

If equals to 0, set coerce_c_locale and coerce_c_locale_warn members to 0.

Перегляньте locale encoding.

За замовчуванням: 1 у конфігурації Python, 0 в ізольованій конфігурації.

int coerce_c_locale¶

If equals to 2, coerce the C locale.

If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.

Перегляньте locale encoding.

За замовчуванням: -1 у конфігурації Python, 0 в ізольованій конфігурації.

int coerce_c_locale_warn¶

Якщо значення відмінне від нуля, видати попередження, якщо локаль C виведена примусово.

За замовчуванням: -1 у конфігурації Python, 0 в ізольованій конфігурації.

int dev_mode¶

Python Development Mode: see PyConfig.dev_mode.

Типове значення: -1 в режимі Python, 0 в ізольованому режимі.

int isolated¶

Ізольований режим: див. PyConfig.isolated.

Типове значення: 0 в режимі Python, 1 в ізольованому режимі.

int legacy_windows_fs_encoding¶

Якщо відмінне від нуля:

Установіть PyPreConfig.utf8_mode на 0,
Установіть PyConfig.filesystem_encoding на "mbcs",
Установіть PyConfig.filesystem_errors на "replace".

Initialized from the PYTHONLEGACYWINDOWSFSENCODING environment variable value.

Доступно лише для Windows. Макрос #ifdef MS_WINDOWS можна використовувати для спеціального коду Windows.

Типове значення: 0.

int parse_argv¶

Якщо значення відмінне від нуля, Py_PreInitializeFromArgs() і Py_PreInitializeFromBytesArgs() аналізують свій аргумент argv так само, як звичайний Python аналізує аргументи командного рядка: див. Аргументи командного рядка.

За замовчуванням: 1 у конфігурації Python, 0 в ізольованій конфігурації.

int use_environment¶

Використовувати змінні середовища? Перегляньте PyConfig.use_environment.

За замовчуванням: 1 у конфігурації Python і 0 в ізольованій конфігурації.

int utf8_mode¶

Якщо не нуль, увімкніть Режим Python UTF-8.

Set to 0 or 1 by the -X utf8 command line option and the PYTHONUTF8 environment variable.

Also set to 1 if the LC_CTYPE locale is C or POSIX.

За замовчуванням: -1 у конфігурації Python і 0 в ізольованій конфігурації.

Попередня ініціалізація Python за допомогою PyPreConfig¶

Попередня ініціалізація Python:

Встановіть розподільники пам’яті Python (PyPreConfig.allocator)
Налаштувати локаль LC_CTYPE (locale encoding)
Установіть режим Python UTF-8 Mode (PyPreConfig.utf8_mode)

Поточна попередня конфігурація (тип PyPreConfig) зберігається в _PyRuntime.preconfig.

Функції для попередньої ініціалізації Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

preconfig не має бути NULL.

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

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

Проаналізуйте аргументи командного рядка argv (рядки байтів), якщо parse_argv preconfig не дорівнює нулю.

preconfig не має бути NULL.

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

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

Проаналізуйте аргументи командного рядка argv (широкі рядки), якщо parse_argv preconfig не дорівнює нулю.

preconfig не має бути NULL.

Виклик відповідає за обробку винятків (помилка або вихід) за допомогою PyStatus_Exception() і Py_ExitStatusException().

Для Конфігурації Python (PyPreConfig_InitPythonConfig()), якщо Python ініціалізовано аргументами командного рядка, аргументи командного рядка також потрібно передати для попередньої ініціалізації Python, оскільки вони впливають на попередні конфігурація, як кодування. Наприклад, параметр командного рядка -X utf8 вмикає Режим Python UTF-8.

PyMem_SetAllocator() можна викликати після Py_PreInitialize() і перед Py_InitializeFromConfig(), щоб встановити спеціальний розподільник пам’яті. Його можна викликати перед Py_PreInitialize(), якщо PyPreConfig.allocator має значення PYMEM_ALLOCATOR_NOT_SET.

Функції виділення пам’яті Python, такі як PyMem_RawMalloc(), не можна використовувати до попередньої ініціалізації Python, тоді як прямий виклик malloc() і free() завжди безпечний. Py_DecodeLocale() не можна викликати до попередньої ініціалізації Python.

Приклад використання попередньої ініціалізації для ввімкнення режиму Python UTF-8:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig¶

type PyConfig¶

Структура, що містить більшість параметрів для налаштування Python.

Після завершення необхідно використати функцію PyConfig_Clear(), щоб звільнити конфігураційну пам’ять.

Методи будови:

void PyConfig_InitPythonConfig(PyConfig *config)¶: Ініціалізуйте конфігурацію за допомогою Налаштування Python.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Ініціалізуйте конфігурацію за допомогою ізольованої конфігурації.

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

Скопіюйте широкий символьний рядок str у *config_str.

Попередньо ініціалізуйте Python, якщо потрібно.

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

Декодуйте str за допомогою Py_DecodeLocale() і встановіть результат у *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.

Поля, які вже ініціалізовані, залишаються без змін.

Fields for path configuration are no longer calculated or modified when calling this function, as of Python 3.11.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Попередньо ініціалізуйте Python, якщо потрібно.

Змінено в версії 3.10: Аргументи PyConfig.argv тепер аналізуються лише один раз, PyConfig.parse_argv встановлюється на 2 після аналізу аргументів, і аргументи аналізуються, лише якщо PyConfig.parse_argv дорівнює 1.

Змінено в версії 3.11: PyConfig_Read() no longer calculates all paths, and so fields listed under Python Path Configuration may no longer be updated until Py_InitializeFromConfig() is called.

void PyConfig_Clear(PyConfig *config)¶: Звільніть конфігураційну пам’ять.

Більшість методів PyConfig за необхідності попередньо ініціалізують Python. У цьому випадку конфігурація попередньої ініціалізації Python (PyPreConfig) базується на PyConfig. Якщо поля конфігурації, які є спільними з PyPreConfig, налаштовано, їх потрібно встановити перед викликом методу PyConfig:

PyConfig.dev_mode
PyConfig.isolated
PyConfig.parse_argv
PyConfig.use_environment

Moreover, if PyConfig_SetArgv() or PyConfig_SetBytesArgv() is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if parse_argv is non-zero).

Виклик цих методів відповідає за обробку винятків (помилка або вихід) за допомогою PyStatus_Exception() і Py_ExitStatusException().

Поля структури:

PyWideStringList argv¶

Set sys.argv command line arguments based on argv. These parameters are similar to those passed to the program’s main() function with the difference that the first entry should refer to the script file to be executed rather than the executable hosting the Python interpreter. If there isn’t a script that will be run, the first entry in argv can be an empty string.

Установіть для parse_argv значення 1, щоб аналізувати argv так само, як звичайний Python аналізує аргументи командного рядка Python, а потім видаляти аргументи Python з argv.

Якщо argv порожній, додається порожній рядок, щоб гарантувати, що sys.argv завжди існує і ніколи не буде порожнім.

Типове значення: NULL.

Дивіться також елемент orig_argv.

int safe_path¶

If equals to zero, Py_RunMain() prepends a potentially unsafe path to sys.path at startup:

If argv[0] is equal to L"-m" (python -m module), prepend the current working directory.
If running a script (python script.py), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.
Otherwise (python -c code and python), prepend an empty string, which means the current working directory.

Set to 1 by the -P command line option and the PYTHONSAFEPATH environment variable.

Default: 0 in Python config, 1 in isolated config.

Added in version 3.11.

wchar_t *base_exec_prefix¶

sys.base_exec_prefix.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

Ініціалізація за допомогою PyConfig¶

Initializing the interpreter from a populated configuration struct is handled by calling Py_InitializeFromConfig().

Виклик відповідає за обробку винятків (помилка або вихід) за допомогою 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);
}

More complete example modifying the default configuration, read the configuration, and then override some parameters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:

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 залишаються без змін. Обробники сигналів не встановлені.

Configuration files are still used with this configuration to determine paths that are unspecified. Ensure PyConfig.home is specified to avoid computing the default path configuration.

Конфігурація Python¶

Функції PyPreConfig_InitPythonConfig() і PyConfig_InitPythonConfig() створюють конфігурацію для створення налаштованого Python, який веде себе як звичайний Python.

Для налаштування Python використовуються змінні середовища та аргументи командного рядка, тоді як глобальні змінні конфігурації ігноруються.

Ця функція вмикає примусове налаштування локалі C (PEP 538) і Python UTF-8 Mode (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) Шляхи програм у реєстрі в розділі «SoftwarePythonPythonCoreX.YPythonPath» HKEY_CURRENT_USER і HKEY_LOCAL_MACHINE (де X.Y — версія Python).
Поля виведення конфігурації шляху:

If at least one «output field» is not set, Python calculates the path configuration to fill unset fields. If module_search_paths_set is equal to 0, module_search_paths is overridden and module_search_paths_set is set to 1.

It is possible to completely ignore the function calculating the default path configuration by setting explicitly all path configuration output fields listed above. A string is considered as set even if it is non-empty. module_search_paths is considered as set if module_search_paths_set is set to 1. In this case, module_search_paths will be used without modification.

Set pathconfig_warnings to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).

Якщо поля 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 file (ex: python._pth)
pybuilddir.txt (лише Unix)

If a ._pth file is present:

Set isolated to 1.
Set use_environment to 0.
Set site_import to 0.
Set safe_path to 1.

If home is not set and a pyvenv.cfg file is present in the same directory as executable, or its parent, prefix and exec_prefix are set that location. When this happens, base_prefix and base_exec_prefix still keep their value, pointing to the base installation. See Virtual Environments for more information.

The __PYVENV_LAUNCHER__ environment variable is used to set PyConfig.base_executable.

Змінено в версії 3.14: prefix, and exec_prefix, are now set to the pyvenv.cfg directory. This was previously done by site, therefore affected by -S.

Py_GetArgcArgv()¶

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

Отримайте оригінальні аргументи командного рядка до того, як Python їх змінив.

Дивіться також член PyConfig.orig_argv.

Delaying main module execution¶

In some embedding use cases, it may be desirable to separate interpreter initialization from the execution of the main module.

This separation can be achieved by setting PyConfig.run_command to the empty string during initialization (to prevent the interpreter from dropping into the interactive prompt), and then subsequently executing the desired main module code using __main__.__dict__ as the global namespace.

Конфігурація ініціалізації Python¶

PyInitConfig C API¶

приклад¶

Create Config¶

Error Handling¶

Get Options¶

Set Options¶

Module¶

Initialize Python¶

Configuration Options¶

Runtime Python configuration API¶

PyConfig C API¶

приклад¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

Попередня ініціалізація Python за допомогою PyPreConfig¶

PyConfig¶

Ініціалізація за допомогою PyConfig¶

Ізольована конфігурація¶

Конфігурація Python¶

Конфігурація шляху Python¶

Py_GetArgcArgv()¶

Delaying main module execution¶

Table of Contents

Попередній розділ

Наступна тема

This page