Конфигурация инициализации 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_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 (кодировка локали)
• Устанавливает режим UTF-8 Python (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 включает режим UTF-8 Python.

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

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

Пример предварительной инициализации для включения режима UTF-8 Python:

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.

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": считать файлы pyc на основе хеша всегда действительными.
• L"default": флаг «check_source» в файлах pyc на основе хеша определяет необходимость инвалидации.

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

См. также PEP 552 «Детерминированные файлы pyc».

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.

wchar_t *executable

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

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

Часть результата конфигурации путей 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.

Если был вызван 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: при запуске Python не добавляет в начало sys.path потенциально небезопасный путь, например текущий каталог, каталог скрипта или пустую строку.
• Задаёт для use_environment значение 0: игнорирует переменные среды PYTHON.
• Задаёт для user_site_directory значение 0: не добавляет каталог пользовательского сайта в sys.path.
• REPL Python не импортирует readline и не включает конфигурацию readline по умолчанию в интерактивных приглашениях.

Получает значение 1 при использовании параметра командной строки -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.
• В противном случае в Windows используется L"python", а на других платформах — 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().

Например, при запуске из командной строки python3 script.py arg ему присваивается значение script.py.

См. также параметр 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.

Это позволяет использовать формы #!cmd, отличные от Unix. Предназначено только для специфичного для 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. Подробнее см. в разделе Поддержка профилировщика Linux perf в Python.

Задаётся параметром командной строки -X perf и переменной среды PYTHONPERFSUPPORT.

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

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

int use_environment

Использовать переменные среды?

Если значение равно нулю, переменные среды игнорируются.

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

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

int user_site_directory

Если значение отлично от нуля, добавляет пользовательский каталог site в 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

Функция для инициализации 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 не анализируется) и пользовательский каталог site. Стандартные потоки 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 не равно нулю, модуль site может изменять sys.path. Если user_site_directory не равно нулю и каталог site-packages пользователя существует, модуль site добавляет каталог site-packages пользователя в 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, которая всегда запускается в изолированном режиме с использованием Py_RunMain(), см. в разделе Конфигурация Python.

Py_GetArgcArgv()

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

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

См. также поле PyConfig.orig_argv.

Частный предварительный API многоэтапной инициализации

В этом разделе описан частный предварительный API, реализующий многоэтапную инициализацию — ключевую возможность PEP 432:

• Этап «Core», «минимально необходимый Python»:

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

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

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

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

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

PyStatus _Py_InitializeMain(void)

Перейти к этапу инициализации «Main» и завершить инициализацию Python.

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

Возможно, станет доступно вычисление конфигурации путей на Python после этапа Core и до этапа Main — это одна из целей PEP 432.

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

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

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);
    }
}