Содержание страницы

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

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

Python может быть инициализирован с помощью Py_InitializeFromConfig() и структуры PyConfig. Он может быть предварительно инициализирован с помощью Py_PreInitialize() и структуры PyPreConfig.

Существует два вида конфигурации:

Конфигурация Python может использоваться для создания настраиваемого Python, который ведёт себя как обычный Python. Например, переменные окружения и аргументы командной строки используются для настройки Python.
Изолированная конфигурация может использоваться для встраивания Python в приложение. Она изолирует Python от системы. Например, переменные окружения игнорируются, локаль LC_CTYPE остаётся неизменной и не регистрируется ни один обработчик сигналов.

Функция Py_RunMain() может использоваться для написания настраиваемой программы на Python.

См. также Инициализация, финализация и потоки.

См. также

PEP 587 “Конфигурация инициализации Python”.

Пример¶Example

Пример настройки Python для постоянной работы в изолированном режиме:

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

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

    /* Декодировать аргументы командной строки.
       Неявно предварительно инициализировать Python (в изолированном режиме). */
    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;
    }
    /* Вывести сообщение об ошибке и завершить процесс с
       ненулевым кодом выхода */
    Py_ExitStatusException(status);
}

PyWideStringList¶

type PyWideStringList¶

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

Если length не равно нулю, items должен быть не NULL, а все строки должны быть\nне 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 в\nlist.

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

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

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

Py_ssize_t length¶: Длина списка.

wchar_t **items¶: Элементы списка.

PyStatus¶

type PyStatus¶

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

В случае ошибки может хранить имя 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) не равен нулю.

Примечание

Внутренне Python использует макросы, которые устанавливают PyStatus.func, тогда как функции создания статуса устанавливают func в NULL.

Пример:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig¶

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): распределитель памяти pymalloc из Python.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): распределитель памяти pymalloc из Python с отладочными перехватчиками.

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¶Preinitialize Python with 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);
}

/* на этом этапе Python использует кодировку UTF-8 */

Py_Initialize();
/* ... использовать Python API здесь ... */
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.12.

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 использует свою кодировку по умолчанию. Подробнее см. Opt-in EncodingWarning.

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

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

int code_debug_ranges¶

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

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

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

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

wchar_t *check_hash_pycs_mode¶

Управляет поведением проверки hash-based .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 равен нулю, начальное значение (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, включить inspect: когда скрипт передан первым аргументом или используется опция -c, войти в интерактивный режим после выполнения скрипта или команды, даже если sys.stdin не выглядит как терминал.

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

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

int install_signal_handlers¶

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

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

int interactive¶

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

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

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

int int_max_str_digits¶

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

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

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

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

int isolated¶

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

Установить safe_path в 1: не добавлять потенциально небезопасный путь к sys.path при запуске Python, например, текущий каталог, каталог скрипта или пустую строку.
Установить use_environment в 0: игнорировать переменные окружения PYTHON.
Установить user_site_directory в 0: не добавлять каталог пользовательских сайт-пакетов в sys.path.
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.

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

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

int parser_debug¶

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

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

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

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

int pathconfig_warnings¶

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

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

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

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

wchar_t *prefix¶

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

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

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

wchar_t *program_name¶

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

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

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

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

wchar_t *pycache_prefix¶

Каталог, в который записываются кэшированные файлы .pyc: sys.pycache_prefix.

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

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

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

int quiet¶

Тихий режим. Если больше 0, не отображать авторские права и версию при запуске Python в интерактивном режиме.

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

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

wchar_t *run_command¶

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

Используется Py_RunMain().

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

wchar_t *run_filename¶

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

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

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

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

wchar_t *run_module¶

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

Используется Py_RunMain().

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

int show_ref_count¶

Показывать общее количество ссылок при завершении (без учёта бессмертных объектов)?

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

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

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

int site_import¶

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

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

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

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

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

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

int skip_source_first_line¶

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

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

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

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

wchar_t *stdio_encoding¶

wchar_t *stdio_errors¶

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

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

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

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

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

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

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

int tracemalloc¶

Включить tracemalloc?

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

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

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

int perf_profiling¶

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

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

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

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

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

int use_environment¶

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

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

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

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

int user_site_directory¶

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

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

Изменено в версии 3.9: Поле show_alloc_count было удалено.

Инициализация с PyConfig¶Initialization with 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);

    /* Установить имя программы. Неявно предварительно инициализировать 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);

    /* Установить имя программы перед чтением конфигурации
       (декодировать байтовую строку из кодировки локали).

       Неявно предварительно инициализировать Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Прочитать всю конфигурацию сразу */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Указать sys.path явно */
    /* Если требуется изменить стандартный набор путей, завершите
       сначала инициализация, а затем использование 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;
    }

    /* Переопределить исполняемый файл, вычисленный 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;
}

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

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

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

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

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

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

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

Эта функция включает принудительное использование локали C (PEP 538) и Режим Python UTF-8 (PEP 540) в зависимости от локали LC_CTYPE, переменных окружения PYTHONUTF8 и PYTHONCOERCECLOCALE.

Конфигурация путей Python¶Python Path Configuration

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).
Выходные поля конфигурации путей:

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

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

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

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

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

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

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

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

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

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

Устанавливает isolated в 1.
Устанавливает use_environment в 0.
Устанавливает site_import в 0.
Устанавливает safe_path в 1.

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

Py_RunMain()¶

int Py_RunMain(void)¶

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

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

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

См. Python Configuration для примера настройки Python для постоянной работы в изолированном режиме с помощью Py_RunMain().

Py_GetArgcArgv()¶

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

Возвращает исходные аргументы командной строки до того, как Python их изменил.

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

Многофазная инициализация (частный временный API)¶Multi-Phase Initialization Private Provisional 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() останавливается на этапе инициализации «Core».

PyStatus _Py_InitializeMain(void)¶: Переход к фазе инициализации «Main», завершение инициализации Python.

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

Возможно, станет возможным вычислять Path Configuration в Python после фазы Core и перед фазой Main, что является одной из PEP 432 мотиваций.

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

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

void init_python(void)
{
    PyStatus status;

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

    /* настроить конфигурацию 'config' */

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

    /* ... разместить здесь дополнительный код конфигурации ...
       вызывается _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... добавьте сюда дополнительный код конфигурации ... */

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