Настройка инициализации Python

Новое в версии 3.8.

Структуры:

PyConfig
PyPreConfig
PyStatus
PyWideStringList

Функции:

Предконфигурация (типа PyPreConfig ) хранится в _PyRuntime.preconfig, а конфигурация (типа PyConfig ) хранится в PyInterpreterState.config.

См. также Инициализация, завершение и потоки.

См. также

PEP 587 «Настройка инициализации Python».

PyWideStringList

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)

Вставить item в список list по индексу index.

Если index больше или равен длине list, добавить item в list.

index должен быть больше или равен 0.

Python должен быть предварительно инициализирован для вызова этой функции.

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

Py_ssize_t length: Длина списка.

wchar_t** items: Элементы списка.

PyStatus

PyStatus

Структура для хранения состояния функции инициализации: успех, ошибка или выход.

В случае ошибки она может хранить имя C-функции, которая создала ошибку.

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

int exitcode: Код завершения. Аргумент, переданный в exit().

const char *err_msg: Сообщение об ошибке.

const char *func: Имя функции, которая создала ошибку, может быть NULL.

Функции для создания состояния:

PyStatus PyStatus_Ok(void): Успех.

PyStatus PyStatus_Error(const char *err_msg): Ошибка инициализации с сообщением.

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 является выходом. Вывести сообщение об ошибке и выйти с ненулевым кодом выхода, если 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

PyPreConfig

Структура, используемая для предварительной инициализации Python:

Устанавливает аллокатор памяти Python
Настраивает локаль LC_CTYPE
Устанавливает режим UTF-8

Функция для инициализации предварительной конфигурации:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig): Инициализирует предварительную конфигурацию с помощью Конфигурации Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig): Инициализирует предварительную конфигурацию с помощью Изолированной конфигурации.

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

int allocator

Имя аллокатора памяти:

PYMEM_ALLOCATOR_NOT_SET (0): не менять аллокатор памяти (использовать значения по умолчанию)
PYMEM_ALLOCATOR_DEFAULT (1): аллокаторы памяти по умолчанию
PYMEM_ALLOCATOR_DEBUG (2): аллокаторы памяти по умолчанию с отладкой
PYMEM_ALLOCATOR_MALLOC (3): принудительно использовать malloc()
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): принудительно использовать malloc() с отладкой
PYMEM_ALLOCATOR_PYMALLOC (5): Аллокатор памяти Python pymalloc
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Аллокатор памяти Python pymalloc с отладкой

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

См. Управление памятью.

int configure_locale: Установить локаль LC_CTYPE на предпочтительную локаль пользователя? Если равно 0, установить coerce_c_locale и coerce_c_locale_warn в 0.

int coerce_c_locale: Если равно 2, принудительно использовать C локаль; если равно 1, прочитать локаль LC_CTYPE, чтобы решить, следует ли ее принудительно использовать.

int coerce_c_locale_warn: Если отлична от нуля, вывести предупреждение, если C локаль принудительно используется.

int dev_mode: См. PyConfig.dev_mode.

int isolated: См. PyConfig.isolated.

int legacy_windows_fs_encoding(Windows only)

Если отлична от нуля, отключить режим UTF-8, установить кодировку файловой системы Python в mbcs, установить обработчик ошибок файловой системы в replace.

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

int parse_argv: Если отлична от нуля, Py_PreInitializeFromArgs() и Py_PreInitializeFromBytesArgs() анализируют аргумент argv так же, как обычный Python анализирует аргументы командной строки: см. Аргументы командной строки.

int use_environment: См. PyConfig.use_environment.

int utf8_mode: Если отлична от нуля, включить режим UTF-8.

Предварительная инициализация с PyPreConfig

Функции для предварительной инициализации Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig): Предварительно инициализировать Python из предварительной конфигурации preconfig.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv): Предварительно инициализировать Python из предварительной конфигурации preconfig и аргументов командной строки (строки байтов).

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv): Предварительно инициализировать Python из предварительной конфигурации preconfig и аргументов командной строки (широкие строки).

Вызывающая сторона отвечает за обработку исключений (ошибки или выход) с помощью PyStatus_Exception() и Py_ExitStatusException().

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

PyMem_SetAllocator() может быть вызван после Py_PreInitialize() и перед Py_InitializeFromConfig() для установки пользовательского аллокатора памяти. Он может быть вызван перед Py_PreInitialize(), если PyPreConfig.allocator установлено в PYMEM_ALLOCATOR_NOT_SET.

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

Пример использования предварительной инициализации для включения режима 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 will speak UTF-8 */

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

END_OF_DOCUMENT_MARKER

PyConfig

PyConfig

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

Методы структуры:

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.