Конфигурация инициализации 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): Является ли статус ошибкой или выходом? Если true, исключение должно быть обработано; например, вызывая 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();

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.