Настройка инициализации 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 больше или равен длине list, добавить item в list.

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_MIMALLOC (6): использовать mimalloc, быструю замену malloc.
• PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): использовать mimalloc, быструю замену malloc с отладкой.

PYMEM_ALLOCATOR_PYMALLOC и PYMEM_ALLOCATOR_PYMALLOC_DEBUG не поддерживаются, если Python использует configured using --without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC и PYMEM_ALLOCATOR_MIMALLOC_DEBUG не поддерживаются, если Python использует configured using --without-mimalloc или если поддержка атомных операций недоступна.

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

По умолчанию: 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 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 Mode.

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 Mode:

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 member of config) из списка argv широких символьных строк.

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

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

Установка аргументов командной строки (argv member of 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 аргументов командной строки на основе argv. Эти параметры аналогичны тем, которые передаются функции main() программы, с той лишь разницей, что первый элемент должен ссылаться на файл скрипта, который должен быть выполнен, а не на исполняемый файл, размещающий интерпретатор Python. Если нет скрипта, который будет запущен, первый элемент в 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.

См. также PyConfig.exec_prefix.

wchar_t *base_executable

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

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

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

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

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

См. также PyConfig.executable.

wchar_t *base_prefix

sys.base_prefix.

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

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

См. также PyConfig.prefix.

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, отключает включение отображения конечных строк и столбцов в объектах кода. Также отключает вывод указателей стрелок в отладочных сообщениях до конкретных позиций ошибки.

Устанавливается в 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.

См. также PyConfig.base_exec_prefix.

wchar_t *executable

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

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

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

См. также PyConfig.base_executable.

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

Установите по умолчанию каталог «home» Python, то есть местоположение стандартных библиотек Python (см. PYTHONHOME).

Устанавливается переменной среды 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 cpu_count

Если значение cpu_count не -1, оно переопределит возвращаемые значения os.cpu_count(), os.process_cpu_count() и multiprocessing.cpu_count().

Настраивается флагом командной строки -X cpu_count=n|default или переменной среды PYTHON_CPU_COUNT.

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

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

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: Оптимизатор простых выражений, установить __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.

См. также PyConfig.base_prefix.

wchar_t *program_name

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

• В 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.

wchar_t *run_presite

Путь к модулю, который должен быть импортирован перед выполнением site.py.

Устанавливается опцией командной строки -X presite=package.module и переменной окружения PYTHON_PRESITE. Опция командной строки имеет приоритет.

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

По умолчанию: 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").

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

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

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

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

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

См. также PyConfig.legacy_windows_stdio.

int tracemalloc

Включить tracemalloc?

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

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

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

int perf_profiling

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

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

Устанавливается опцией командной строки -X perf и переменной окружения PYTHON_PERF_JIT_SUPPORT для поддержки perf с указателями стека и опцией командной строки -X perf_jit и переменной окружения PYTHON_PERF_JIT_SUPPORT для поддержки perf с информацией DWARF JIT.

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

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

int use_environment

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

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

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

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

int user_site_directory

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

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

Устанавливается в 0 переменной окружения 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

Инициализация интерпретатора из заполненной структуры конфигурации выполняется вызовом Py_InitializeFromConfig().

Вызывающая сторона отвечает за обработку исключений (ошибки или выход) с помощью 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, многие параметры рассчитываются только при инициализации, и поэтому значения не могут быть прочитаны из структуры конфигурации. Любые значения, установленные до вызова initialize, останутся неизменными после инициализации:

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) Пути приложений в реестре по адресу “SoftwarePythonPythonCoreX.YPythonPath” в 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_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 на переопределение или настройку Конфигурации пути, возможно, установить пользовательский импортер 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);
    }
}