Конфигурация инициализации Python

Пример

Пример настраиваемого Python, всегда работающего в изолированном режиме:

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}

PyWideStringList

type PyWideStringList

Список wchar_t* строк.

Если length не равно нулю, items не должны быть NULL, и все строки не должны быть NULL.

Методы:

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

Добавить item в список list.

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

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

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

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

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

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

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

Py_ssize_t length

Длина списка.

wchar_t **items

Элементы списка.

PyStatus

type PyStatus

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

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

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

int exitcode

Код выхода. Аргумент, переданный в exit().

const char *err_msg

Сообщение об ошибке.

const char *func

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

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

PyStatus PyStatus_Ok(void)

Успех.

PyStatus PyStatus_Error(const char *err_msg)

Ошибка инициализации с сообщением.

err_msg не должен быть NULL.

PyStatus PyStatus_NoMemory(void)

Ошибка выделения памяти (нет памяти).

PyStatus PyStatus_Exit(int exitcode)

Выход из Python с указанным кодом выхода.

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

int PyStatus_Exception(PyStatus status)

Является ли статус ошибкой или выходом? Если да, необходимо обработать исключение; например, вызвав Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)

Результат является ошибкой?

int PyStatus_IsExit(PyStatus status)

Результат является выходом?

void Py_ExitStatusException(PyStatus status)

Вызвать exit(exitcode) если status является выходом. Вывести сообщение об ошибке и выйти с ненулевым кодом выхода, если status является ошибкой. Должен вызываться только если PyStatus_Exception(status) не равно нулю.

Пример:

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_PYMALLOC и PYMEM_ALLOCATOR_PYMALLOC_DEBUG не поддерживаются, если Python configured using --without-pymalloc.

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

Значение по умолчанию: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale

Установить локаль LC_CTYPE на локаль пользователя.

Если равно 0, установить значения coerce_c_locale и coerce_c_locale_warn на 0.

См. кодировку локали.

Значение по умолчанию: 1 в конфигурации Python, 0 в изолированной конфигурации.

int coerce_c_locale

Если равно 2, принудительно использовать C локаль.

Если равно 1, считать локаль LC_CTYPE для принятия решения о принудительном использовании.

См. кодировку локали.

Значение по умолчанию: -1 в конфигурации Python, 0 в изолированной конфигурации.

int coerce_c_locale_warn

Если не равно нулю, вывести предупреждение, если C локаль принудительно изменена.

Значение по умолчанию: -1 в конфигурации Python, 0 в изолированной конфигурации.

int dev_mode

Режим разработки Python: см. 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".

Инициализируется из значения переменной среды PYTHONLEGACYWINDOWSFSENCODING.

Доступно только в 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

Если не равно нулю, включить Режим UTF-8 в Python.

Устанавливается на 0 или 1 опцией командной строки -X utf8 и переменной среды PYTHONUTF8.

Также устанавливается на 1 если локаль LC_CTYPE равна C или POSIX.

Значение по умолчанию: -1 в конфигурации Python и 0 в изолированной конфигурации.

Предварительная инициализация Python с помощью PyPreConfig

Предварительная инициализация Python:

• Установка выделения памяти Python (PyPreConfig.allocator)
• Настройка локали LC_CTYPE (кодировка локали)
• Установка режима Python UTF-8 (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.

Поля, которые уже инициализированы, остаются неизменными.

Поля для конфигурации путей больше не вычисляются и не изменяются при вызове этой функции, начиная с Python 3.11.

Функция PyConfig_Read() анализирует аргументы PyConfig.argv только один раз: PyConfig.parse_argv устанавливается в 2 после анализа аргументов. Поскольку аргументы Python удаляются из PyConfig.argv, повторный анализ аргументов приведёт к анализу опций приложения как опций Python.

Если необходимо, Предварительная инициализация Python.

Изменено в версии 3.10: Аргументы PyConfig.argv теперь анализируются только один раз, PyConfig.parse_argv устанавливается в 2 после анализа аргументов, а аргументы анализируются только в том случае, если PyConfig.parse_argv равно 1.

Изменено в версии 3.11: PyConfig_Read() больше не вычисляет все пути, и поэтому поля, указанные в Конфигурации путей Python, могут больше не обновляться до тех пор, пока не будет вызван Py_InitializeFromConfig().

void PyConfig_Clear(PyConfig *config)

Освобождение памяти конфигурации.

Большинство методов PyConfig предварительно инициализируют Python, если это необходимо. В этом случае конфигурация предварительной инициализации Python (PyPreConfig) основана на PyConfig. Если поля конфигурации, которые общие с PyPreConfig, настроены, они должны быть установлены до вызова метода PyConfig:

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

Кроме того, если используется PyConfig_SetArgv() или PyConfig_SetBytesArgv(), этот метод должен быть вызван до других методов, так как конфигурация предварительной инициализации зависит от аргументов командной строки (если parse_argv не равно нулю).

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

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

PyWideStringList argv

Аргументы командной строки: sys.argv.

Установите parse_argv в 1 для анализа argv так же, как это делает обычный Python для анализа аргументов командной строки Python, и затем для удаления аргументов Python из argv.

Если argv пусто, добавляется пустая строка, чтобы гарантировать, что sys.argv всегда существует и никогда не пуст.

По умолчанию: NULL.

См. также член orig_argv.

int safe_path

Если равно нулю, Py_RunMain() добавляет потенциально небезопасный путь к sys.path при запуске:

• Если argv[0] равно L"-m" (python -m module), добавляется текущая рабочая директория.
• Если запускается скрипт (python script.py), добавляется директория скрипта. Если это символическая ссылка, разрешаются символические ссылки.
• В противном случае (python -c code и python), добавляется пустая строка, что означает текущую рабочую директорию.

Устанавливается в 1 опцией командной строки -P и переменной окружения PYTHONSAFEPATH.

По умолчанию: 0 в конфигурации Python, 1 в изолированной конфигурации.

Добавлена в версии 3.11.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

По умолчанию: NULL.

Часть выходных данных Конфигурации путей Python.

wchar_t *base_executable

Базовая исполняемая программа Python: sys._base_executable.

Устанавливается переменной окружения __PYVENV_LAUNCHER__.

Устанавливается из PyConfig.executable, если NULL.

По умолчанию: NULL.

Часть выходных данных Конфигурации путей Python.

wchar_t *base_prefix

sys.base_prefix.

По умолчанию: NULL.

Часть вывода конфигурации пути Python Конфигурация пути Python.

int buffered_stdio

Если равно 0, и configure_c_stdio не равно нулю, отключение буферизации для потоков C stdout и stderr.

Устанавливается в 0 опцией командной строки -u и переменной окружения PYTHONUNBUFFERED.

stdin всегда открывается в режиме с буферизацией.

По умолчанию: 1.

int bytes_warning

Если равно 1, выводит предупреждение при сравнении bytes или bytearray с str, или сравнении bytes с int.

Если равно или больше 2, поднимает исключение BytesWarning в этих случаях.

Увеличивается опцией командной строки -b.

По умолчанию: 0.

int warn_default_encoding

Если не равно нулю, выводит предупреждение EncodingWarning когда io.TextIOWrapper использует кодировку по умолчанию. Подробности в Включение предупреждений EncodingWarning.

По умолчанию: 0.

Добавлена в версии 3.10.

int code_debug_ranges

Если равно 0, отключает включение последних строк и столбцов в объектах кода. Также отключает печать указателей traceback на конкретные места ошибок.

Устанавливается в 0 переменной окружения PYTHONNODEBUGRANGES и опцией командной строки -X no_debug_ranges.

По умолчанию: 1.

Добавлена в версии 3.11.

wchar_t *check_hash_pycs_mode

Управление поведением проверки файлов .pyc на основе хэшей: значение опции командной строки --check-hash-based-pycs.

Допустимые значения:

• L"always": Хэшировать исходный файл для проверки независимо от флага ‘check_source’.
• L"never": Предполагать, что файлы pycs на основе хэшей всегда валидны.
• L"default": Флаг ‘check_source’ в pycs на основе хэшей определяет проверку.

По умолчанию: L"default".

См. также PEP 552 «Определённые pycs».

int configure_c_stdio

Если не равно нулю, настройка потоков C стандартного ввода/вывода:

• В Windows, устанавливает бинарный режим (O_BINARY) для stdin, stdout и stderr.
• Если buffered_stdio равно нулю, отключает буферизацию для stdin, stdout и stderr.
• Если interactive не равно нулю, включает буферизацию для stdin и stdout (только для stdout в Windows).

По умолчанию: 1 в конфигурации Python, 0 в изолированной конфигурации.

int dev_mode

Если не равно нулю, включает Режим разработки Python.

Устанавливается в 1 опцией -X dev и переменной окружения PYTHONDEVMODE.

По умолчанию: -1 в режиме Python, 0 в изолированном режиме.

int dump_refs

Выводить ссылки Python?

Если не равно нулю, выводит все объекты, которые всё ещё существуют при выходе.

Устанавливается в 1 переменной окружения PYTHONDUMPREFS.

Требуется специальная сборка Python с определённым макросом Py_TRACE_REFS: см. configure --with-trace-refs option.

По умолчанию: 0.

wchar_t *exec_prefix

Префикс каталога, специфичный для сайта, где установлены платформозависимые файлы Python: sys.exec_prefix.

По умолчанию: NULL.

Часть вывода конфигурации пути Python Конфигурация пути Python.

wchar_t *executable

Абсолютный путь к исполняемому файлу интерпретатора Python: sys.executable.

По умолчанию: NULL.

Часть вывода конфигурации пути Python Конфигурация пути Python.

int faulthandler

Включить faulthandler?

Если не равно нулю, вызывает faulthandler.enable() при запуске.

Устанавливается в 1 опцией -X faulthandler и переменной окружения PYTHONFAULTHANDLER.

По умолчанию: -1 в режиме Python, 0 в изолированном режиме.

wchar_t *filesystem_encoding

Кодировка файловой системы: sys.getfilesystemencoding().

В macOS, Android и VxWorks: используется "utf-8" по умолчанию.

В Windows: используется "utf-8" по умолчанию, или "mbcs" если legacy_windows_fs_encoding объекта PyPreConfig не равно нулю.

Кодировка по умолчанию на других платформах:

• "utf-8" если PyPreConfig.utf8_mode не равно нулю.
• "ascii" если Python обнаруживает, что nl_langinfo(CODESET) объявляет кодировку ASCII, в то время как функция mbstowcs() декодирует из другой кодировки (обычно Latin1).
• "utf-8" если nl_langinfo(CODESET) возвращает пустую строку.
• В противном случае, используется кодировка локали: результат nl_langinfo(CODESET).

При запуске Python имя кодировки нормализуется в имя кодека Python. Например, "ANSI_X3.4-1968" заменяется на "ascii".

См. также член filesystem_errors.

wchar_t *filesystem_errors

Обработчик ошибок файловой системы: sys.getfilesystemencodeerrors().

В Windows: по умолчанию используется "surrogatepass", или "replace", если legacy_windows_fs_encoding для PyPreConfig не равно нулю.

На других платформах: по умолчанию используется "surrogateescape".

Поддерживаемые обработчики ошибок:

• "strict"
• "surrogateescape"
• "surrogatepass" (поддерживается только с кодировкой UTF-8)

См. также член filesystem_encoding.

unsigned long hash_seed

int use_hash_seed

Семена случайной функции хеширования.

Если use_hash_seed равно нулю, семя выбирается случайным образом при запуске Python, и hash_seed игнорируется.

Устанавливается переменной окружения PYTHONHASHSEED.

Значение по умолчанию для use_hash_seed: -1 в режиме Python, 0 в изолированном режиме.

wchar_t *home

Директория Python home.

Если Py_SetPythonHome() был вызван, используется его аргумент, если он не NULL.

Устанавливается переменной окружения PYTHONHOME.

По умолчанию: NULL.

Часть ввода Настройка пути Python.

int import_time

Если не равно нулю, профилировать время импорта.

Устанавливается 1 опцией -X importtime и переменной окружения PYTHONPROFILEIMPORTTIME.

По умолчанию: 0.

int inspect

Перейти в интерактивный режим после выполнения скрипта или команды.

Если больше 0, включить инспектор: при передаче скрипта в качестве первого аргумента или использовании опции -c, перейти в интерактивный режим после выполнения скрипта или команды, даже если sys.stdin не является терминалом.

Увеличивается опцией командной строки -i. Устанавливается в 1, если переменная окружения PYTHONINSPECT не пустая.

По умолчанию: 0.

int install_signal_handlers

Установить обработчики сигналов Python?

По умолчанию: 1 в режиме Python, 0 в изолированном режиме.

int interactive

Если больше 0, включить интерактивный режим (REPL).

Увеличивается опцией командной строки -i.

По умолчанию: 0.

int int_max_str_digits

Настраивает ограничение длины целых строк. Начальное значение -1 означает, что значение будет взято из командной строки или среды, или по умолчанию будет равно 4300 (sys.int_info.default_max_str_digits). Значение 0 отключает ограничение. Значения, больше нуля, но меньше 640 (sys.int_info.str_digits_check_threshold) не поддерживаются и приведут к ошибке.

Настраивается флагом командной строки -X int_max_str_digits или переменной окружения PYTHONINTMAXSTRDIGITS.

По умолчанию: -1 в режиме Python. 4300 (sys.int_info.default_max_str_digits) в изолированном режиме.

Добавлен в версии 3.12.

int isolated

Если больше 0, включить изолированный режим:

• Установить safe_path в 1: не добавлять потенциально небезопасный путь к sys.path при запуске Python, например, текущую директорию, директорию скрипта или пустую строку.
• Установить use_environment в 0: игнорировать переменные окружения PYTHON.
• Установить user_site_directory в 0: не добавлять директорию сайта пользователя в sys.path.
• Python REPL не импортирует readline, и не включает настройку readline по умолчанию в интерактивных приглашениях.

Устанавливается опцией командной строки -I.

По умолчанию: 0 в режиме Python, 1 в изолированном режиме.

См. также Настройка в изолированном режиме и PyPreConfig.isolated.

int legacy_windows_stdio

Если не равно нулю, использовать io.FileIO вместо io._WindowsConsoleIO для sys.stdin, sys.stdout и sys.stderr.

Устанавливается в 1, если переменная окружения PYTHONLEGACYWINDOWSSTDIO установлена в строку, отличную от пустой.

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

По умолчанию: 0.

См. также PEP 528 (Изменение кодировки консоли Windows на UTF-8).

int malloc_stats

Если не равно нулю, вывести статистику о аллокаторе памяти Python pymalloc при выходе.

Устанавливается в 1 переменной окружения PYTHONMALLOCSTATS.

Опция игнорируется, если Python используется без configured using the --without-pymalloc option.

По умолчанию: 0.

wchar_t *platlibdir

Имя каталога библиотеки платформы: sys.platlibdir.

Устанавливается переменной среды PYTHONPLATLIBDIR.

Значение по умолчанию: значение макроса PLATLIBDIR, который устанавливается параметром configure --with-platlibdir option (по умолчанию: "lib", или "DLLs" в Windows).

Часть ввода Настройка пути Python.

Добавлена в версии 3.9.

Изменено в версии 3.11: Теперь этот макрос используется в Windows для поиска модулей расширения стандартной библиотеки, обычно в DLLs. Однако для совместимости обратите внимание, что это значение игнорируется для любых нестандартных расположений, включая встраиваемые сборки и виртуальные среды.

wchar_t *pythonpath_env

Пути поиска модулей (sys.path) как строка, разделённая DELIM (os.pathsep).

Устанавливается переменной среды PYTHONPATH.

Значение по умолчанию: NULL.

Часть ввода Настройка пути Python.

PyWideStringList module_search_paths

int module_search_paths_set

Пути поиска модулей: sys.path.

Если module_search_paths_set равно 0, Py_InitializeFromConfig() заменит module_search_paths и установит module_search_paths_set в 1.

Значение по умолчанию: пустой список (module_search_paths) и 0 (module_search_paths_set).

Часть вывода Настройка пути Python.

int optimization_level

Уровень оптимизации компиляции:

• 0: Оптимизатор "peephole", установить __debug__ в True.
• 1: Уровень 0, удалить утверждения, установить __debug__ в False.
• 2: Уровень 1, удалить строковые описания.

Увеличивается опцией командной строки -O. Устанавливается значением переменной среды PYTHONOPTIMIZE.

Значение по умолчанию: 0.

PyWideStringList orig_argv

Список исходных аргументов командной строки, переданных исполняемому файлу Python: sys.orig_argv.

Если список orig_argv пуст, а argv не является списком, содержащим только пустую строку, PyConfig_Read() копирует argv в orig_argv перед модификацией argv (если parse_argv не равно нулю).

См. также член argv и функцию Py_GetArgcArgv().

Значение по умолчанию: пустой список.

Добавлена в версии 3.10.

int parse_argv

Парсить аргументы командной строки?

Если равно 1, проанализировать argv так же, как обычный Python анализирует аргументы командной строки, и удалить аргументы Python из argv.

Функция PyConfig_Read() анализирует аргументы PyConfig.argv только один раз: PyConfig.parse_argv устанавливается в 2 после анализа аргументов. Поскольку аргументы Python удаляются из PyConfig.argv, повторный анализ аргументов приведёт к обработке параметров приложения как параметров Python.

Значение по умолчанию: 1 в режиме Python, 0 в изолированном режиме.

Изменено в версии 3.10: Аргументы PyConfig.argv теперь анализируются только если PyConfig.parse_argv равно 1.

int parser_debug

Режим отладки парсера. Если больше 0, включить вывод отладки парсера (только для специалистов, в зависимости от параметров компиляции).

Увеличивается опцией командной строки -d. Устанавливается значением переменной среды PYTHONDEBUG.

Требуется сборка Python с отладкой (макрос Py_DEBUG должен быть определён).

Значение по умолчанию: 0.

int pathconfig_warnings

Если не равно нулю, вычисление конфигурации пути разрешает регистрировать предупреждения в stderr. Если равно 0, эти предупреждения подавляются.

Значение по умолчанию: 1 в режиме Python, 0 в изолированном режиме.

Часть ввода Настройка пути Python.

Изменено в версии 3.11: Теперь также применяется в Windows.

wchar_t *prefix

Префикс каталога, специфичного для сайта, где установлены независимые от платформы файлы Python: sys.prefix.

Значение по умолчанию: NULL.

Часть вывода Настройка пути Python.

wchar_t *program_name

Имя программы, используемое для инициализации executable и в ранних сообщениях об ошибках во время инициализации Python.

• Если была вызвана функция Py_SetProgramName(), используется её аргумент.
• В macOS используется переменная среды PYTHONEXECUTABLE, если она установлена.
• Если определён макрос WITH_NEXT_FRAMEWORK, используется переменная среды __PYVENV_LAUNCHER__ при её наличии.
• Используется значение argv[0] из argv, если оно доступно и не пусто.
• В противном случае используется L"python" в Windows или L"python3" на других платформах.

Значение по умолчанию: NULL.

Часть ввода Настройка пути Python.

wchar_t *pycache_prefix

Директория, в которой хранятся кэшированные файлы .pyc: sys.pycache_prefix.

Устанавливается опцией командной строки -X pycache_prefix=PATH и переменной окружения PYTHONPYCACHEPREFIX.

Если NULL, sys.pycache_prefix устанавливается в None.

По умолчанию: NULL.

int quiet

Режим без вывода сообщений. Если значение больше 0, то при запуске Python в интерактивном режиме не отображается информация об авторских правах и версии.

Увеличивается опцией командной строки -q.

По умолчанию: 0.

wchar_t *run_command

Значение опции командной строки -c.

Используется функцией Py_RunMain().

По умолчанию: NULL.

wchar_t *run_filename

Имя файла, переданное в командной строке: последний аргумент командной строки без -c или -m. Оно используется функцией Py_RunMain().

Например, оно устанавливается в script.py при запуске с помощью python3 script.py arg.

См. также опцию PyConfig.skip_source_first_line.

По умолчанию: NULL.

wchar_t *run_module

Значение опции командной строки -m.

Используется функцией Py_RunMain().

По умолчанию: NULL.

int show_ref_count

Отображать полное значение счётчика ссылок при выходе (исключая бессмертные объекты)?

Устанавливается в 1 опцией командной строки -X showrefcount.

Требуется отладочная сборка Python (макрос Py_REF_DEBUG должен быть определён).

По умолчанию: 0.

int site_import

Импортировать модуль site при запуске?

Если равно нулю, отключить импорт модуля site и зависящие от него манипуляции с sys.path.

Также отключить эти манипуляции, если модуль site был импортирован позднее (вызовите site.main(), если хотите, чтобы они были выполнены).

Устанавливается в 0 опцией командной строки -S.

sys.flags.no_site устанавливается в инвертированное значение site_import.

По умолчанию: 1.

int skip_source_first_line

Если не равно нулю, пропустить первую строку файла исходного кода PyConfig.run_filename.

Это позволяет использовать не-Unix формы #!cmd. Предназначено только для совместимости с DOS.

Устанавливается в 1 опцией командной строки -x.

По умолчанию: 0.

wchar_t *stdio_encoding

wchar_t *stdio_errors

Кодировка и обработка ошибок для sys.stdin, sys.stdout и sys.stderr (но sys.stderr всегда использует обработчик ошибок "backslashreplace").

Если была вызвана Py_SetStandardStreamEncoding(), использовать её аргументы error и errors, если они не NULL.

Использовать переменную окружения PYTHONIOENCODING, если она не пустая.

Кодировка по умолчанию:

• "UTF-8" если PyPreConfig.utf8_mode не равно нулю.
• В противном случае, использовать кодировку локали.

Обработчик ошибок по умолчанию:

• В Windows: использовать "surrogateescape".
• "surrogateescape" если PyPreConfig.utf8_mode не равно нулю или если локали LC_CTYPE равна “C” или “POSIX”.
• "strict" в противном случае.

int tracemalloc

Включить трассировку tracemalloc?

Если не равно нулю, вызывать tracemalloc.start() при запуске.

Устанавливается опцией командной строки -X tracemalloc=N и переменной окружения PYTHONTRACEMALLOC.

По умолчанию: -1 в режиме Python, 0 в изолированном режиме.

int perf_profiling

Включить режим совместимости с профилировщиком perf?

Если не равно нулю, инициализировать perf trampoline. Подробнее см. Поддержка Python профилировщика perf для Linux.

Устанавливается опцией командной строки -X perf и переменной окружения PYTHONPERFSUPPORT.

По умолчанию: -1.

Добавлена в версии 3.12.

int use_environment

Использовать переменные окружения?

Если равно нулю, игнорировать переменные окружения.

Устанавливается переменной окружения 0 опцией -E.

По умолчанию: 1 в конфигурации Python и 0 в изолированной конфигурации.

int user_site_directory

Если не равно нулю, добавить директорию пользовательских модулей в sys.path.

Устанавливается опциями командной строки -s и -I.

Устанавливается переменной окружения PYTHONNOUSERSITE.

По умолчанию: 1 в режиме Python, 0 в изолированном режиме.

int verbose

Режим подробной информации. Если значение больше 0, будет выводиться сообщение каждый раз при импорте модуля, показывающее место (имя файла или встроенный модуль), откуда он загружается.

Если значение больше или равно 2, будет выводиться сообщение для каждого файла, проверяемого при поиске модуля. Также предоставляется информация о очистке модулей при выходе.

Увеличивается опцией командной строки -v.

Устанавливается значением переменной окружения PYTHONVERBOSE.

По умолчанию: 0.

PyWideStringList warnoptions

Опции модуля warnings для построения фильтров предупреждений, от низшего к высшему приоритету: sys.warnoptions.

Модуль warnings добавляет sys.warnoptions в обратном порядке: последний элемент PyConfig.warnoptions становится первым элементом warnings.filters, который проверяется в первую очередь (высший приоритет).

Опции командной строки -W добавляют своё значение в warnoptions, их можно использовать несколько раз.

Переменная окружения PYTHONWARNINGS также может использоваться для добавления опций предупреждений. Можно указать несколько опций, разделенных запятыми (,).

По умолчанию: пустой список.

int write_bytecode

Если равно 0, Python не будет пытаться записать файлы .pyc при импорте исходных модулей.

Устанавливается в 0 опцией командной строки -B и переменной окружения PYTHONDONTWRITEBYTECODE.

sys.dont_write_bytecode инициализируется с инвертированным значением write_bytecode.

По умолчанию: 1.

PyWideStringList xoptions

Значения опций командной строки -X: sys._xoptions.

По умолчанию: пустой список.

Если parse_argv не равно нулю, аргументы argv анализируются так же, как обычный Python анализирует аргументы командной строки, и аргументы Python удаляются из argv.

Опции xoptions анализируются для установки других опций: см. опцию командной строки -X.

Инициализация с PyConfig

Функция для инициализации Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Инициализация Python из конфигурации config.

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

Если используются PyImport_FrozenModules(), PyImport_AppendInittab() или PyImport_ExtendInittab(), они должны быть установлены или вызваны после предварительной инициализации Python и перед инициализацией Python. Если Python инициализируется несколько раз, PyImport_AppendInittab() или PyImport_ExtendInittab() должны быть вызваны перед каждой инициализацией Python.

Текущая конфигурация (тип PyConfig ) сохраняется в PyInterpreterState.config.

Пример установки имени программы:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);
    return;

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
}

Более полный пример модификации значения по умолчанию, чтения конфигурации и затем переопределения некоторых параметров. Обратите внимание, что с версии 3.11 многие параметры не рассчитываются до момента инициализации, и поэтому значения не могут быть прочитаны из структуры конфигурации. Любые значения, заданные до вызова инициализации, будут оставлены неизменными инициализацией:

PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Specify sys.path explicitly */
    /* If you want to modify the default set of paths, finish
       initialization first and then use PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) {
        goto done;
    }
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

Изолированная конфигурация

Функции PyPreConfig_InitIsolatedConfig() и PyConfig_InitIsolatedConfig() создают конфигурацию для изоляции Python от системы. Например, для встраивания Python в приложение.

Эта конфигурация игнорирует глобальные переменные конфигурации, переменные окружения, аргументы командной строки (PyConfig.argv не анализируется) и пользовательский сайт-каталог. Стандартные потоки C (например, stdout) и локаль LC_CTYPE остаются неизменными. Обработчики сигналов не устанавливаются.

Конфигурационные файлы все еще используются с этой конфигурацией для определения путей, которые не указаны. Убедитесь, что PyConfig.home указан, чтобы избежать вычисления конфигурации пути по умолчанию.

Конфигурация Python

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

Переменные окружения и аргументы командной строки используются для настройки Python, в то время как глобальные переменные конфигурации игнорируются.

Эта функция включает принудительное использование C локали (PEP 538) и Режим UTF-8 Python (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) Пути приложений в реестре по пути “Software\Python\PythonCoreX.Y\PythonPath” в HKEY_CURRENT_USER и HKEY_LOCAL_MACHINE (где X.Y — версия Python).

• Поля вывода данных для настройки пути:

  • PyConfig.base_exec_prefix
  • PyConfig.base_executable
  • PyConfig.base_prefix
  • PyConfig.exec_prefix
  • PyConfig.executable
  • PyConfig.module_search_paths_set, PyConfig.module_search_paths
  • PyConfig.prefix

Если хотя бы одно «поле вывода» не задано, Python вычисляет настройку пути для заполнения незаданных полей. Если module_search_paths_set равно 0, module_search_paths переопределяется, а module_search_paths_set устанавливается в значение 1.

Можно полностью игнорировать функцию, вычисляющую конфигурацию пути по умолчанию, явно задав все поля настроек пути, перечисленные выше. Строка считается заданной, даже если она не пустая. module_search_paths считается заданным, если module_search_paths_set установлено в 1. В этом случае module_search_paths будет использовано без изменений.

Установите pathconfig_warnings в 0 для подавления предупреждений при расчете конфигурации пути (только для Unix, Windows не регистрирует никаких предупреждений).

Если поля base_prefix или base_exec_prefix не заданы, они наследуют свое значение из prefix и exec_prefix соответственно.

Py_RunMain() и Py_Main() изменяют sys.path:

• Если run_filename задано и является директорией, содержащей скрипт __main__.py, добавьте run_filename в начало sys.path.

• Если isolated равно нулю:

  • Если run_module задано, добавьте текущую директорию в начало sys.path. Ничего не делайте, если текущую директорию нельзя прочитать.
  • Если run_filename задано, добавьте директорию файла в начало sys.path.
  • В противном случае, добавьте пустую строку в начало sys.path.

Если site_import отлично от нуля, sys.path может быть изменён модулем site. Если user_site_directory отлично от нуля и директория пользовательских пакетов пользователя существует, модуль site добавляет директорию пользовательских пакетов пользователя в конец sys.path.

Следующие файлы конфигурации используются для настройки пути:

• pyvenv.cfg
• ._pth файл (например, python._pth)
• pybuilddir.txt (только для Unix)

Если файл ._pth существует:

• Установить isolated в 1.
• Установить use_environment в 0.
• Установить site_import в 0.
• Установить safe_path в 1.

Переменная окружения __PYVENV_LAUNCHER__ используется для установки PyConfig.base_executable

Py_RunMain()

int Py_RunMain(void)

Выполняет команду (PyConfig.run_command), скрипт (PyConfig.run_filename) или модуль (PyConfig.run_module), указанные в командной строке или в конфигурации.

По умолчанию, и если используется опция -i, запускает интерактивную оболочку (REPL).

Наконец, завершает работу Python и возвращает код завершения, который можно передать функции exit().

См. Конфигурация Python для примера настраиваемого Python, всегда запускаемого в изолированном режиме с помощью Py_RunMain().

Py_GetArgcArgv()

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

Получает исходные аргументы командной строки, до того, как Python их модифицировал.

См. также член PyConfig.orig_argv.

Инициализация в несколько этапов. Частная предварительная версия API

Этот раздел содержит частную предварительную версию API, вводящую инициализацию в несколько этапов, основную функцию PEP 432:

• Этап инициализации «ядро», «минимальный Python»:

  • Встроенные типы;
  • Встроенные исключения;
  • Встроенные и замороженные модули;
  • Модуль sys только частично инициализирован (например, sys.path ещё не существует).

• Этап инициализации «основной», Python полностью инициализирован:

  • Установка и настройка importlib;
  • Применение Конфигурации пути;
  • Установка обработчиков сигналов;
  • Завершение инициализации модуля sys (например, создание sys.stdout и sys.path);
  • Включение дополнительных функций, таких как faulthandler и tracemalloc;
  • Импорт модуля site;
  • и т.д.

Частная предварительная версия API:

• PyConfig._init_main: если установлено значение 0, Py_InitializeFromConfig() останавливается на этапе инициализации «ядро».

PyStatus _Py_InitializeMain(void)

Переход к этапу инициализации «основной», завершение инициализации Python.

Во время этапа «ядро» не импортируются никакие модули, и модуль importlib не настроен: Конфигурация пути применяется только на этапе «основной». Это может позволить настраивать Python внутри Python, чтобы переопределять или настраивать Конфигурацию пути, возможно, установить пользовательский импортер sys.meta_path или обработчик импорта и т. д.

Возможно, станет возможным рассчитать Конфигурацию пути в Python после этапа «ядро» и перед этапом «основной», что является одной из мотиваций PEP 432.

Этап «ядро» не определён надлежащим образом: то, что должно быть и чего не должно быть доступно на этом этапе, ещё не определено. API помечен как частный и предварительный: API может быть изменён или даже удалён в любое время до разработки надлежащего публичного API.

Пример работы Python-кода между этапами инициализации «ядро» и «основной»:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}