Конфигурация инициализации 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 (кодировку локали)
• Включает режим 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 на основе 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": считать, что файлы pyc на основе хеша всегда актуальны.
• L"default": актуальность файлов pyc на основе хеша определяется флагом ‘check_source’.

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

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

wchar_t *executable

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

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

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

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

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

Значение 1 задаётся параметром командной строки -I.

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

См. также Изолированная конфигурация и PyPreConfig.isolated.

int legacy_windows_stdio

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

Значение 1 задаётся, если переменная окружения PYTHONLEGACYWINDOWSSTDIO задана непустой строкой.

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

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

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

int malloc_stats

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

Значение 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.

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

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

См. также параметр PyConfig.skip_source_first_line.

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

wchar_t *run_module

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

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

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

wchar_t *run_presite

Путь к модулю package.module, который необходимо импортировать до запуска 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. Дополнительные сведения см. в разделе Поддержка профилировщика Linux perf в Python.

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

Значение по умолчанию: -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

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

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:

• Этап инициализации «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);
    }
}