Настройка инициализации 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) не равно нулю.

Примечание

Внутренне 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): аллокатор памяти 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 locale.

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

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

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

int coerce_c_locale_warn

Если отлично от нуля, вывести предупреждение, если C locale принудительно устанавливается.

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

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

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

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

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

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

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

• Установить выделения памяти Python (PyPreConfig.allocator)
• Настроить локаль LC_CTYPE (кодировка локали)
• Установить режим Python UTF-8 Mode (PyPreConfig.utf8_mode)

Текущая предварительная настройка (PyPreConfig тип) хранится в _PyRuntime.preconfig.

Функции для предварительной инициализации Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

Предварительная инициализация Python из предварительной настройки preconfig.

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

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)

Предварительная инициализация Python из предварительной настройки preconfig.

Распарсить аргументы командной строки argv (строки байтов), если parse_argv preconfig не равно нулю.

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

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)

Предварительная инициализация Python из предварительной настройки preconfig.

Распарсить аргументы командной строки argv (широкие строки), если parse_argv preconfig не равно нулю.

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

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

Для Конфигурации Python (PyPreConfig_InitPythonConfig()), если Python инициализируется с аргументами командной строки, аргументы командной строки также должны быть переданы для предварительной инициализации Python, поскольку они влияют на предварительную настройку, например, на кодировки. Например, опция командной строки -X utf8 включает режим Python UTF-8 Mode.

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

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

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

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig

type PyConfig

Структура, содержащая большинство параметров для настройки Python.

По завершении необходимо использовать функцию PyConfig_Clear() для освобождения памяти конфигурации.

Методы структуры:

void PyConfig_InitPythonConfig(PyConfig *config)

Инициализация конфигурации с помощью Конфигурации Python.

void PyConfig_InitIsolatedConfig(PyConfig *config)

Инициализация конфигурации с помощью Изолированной конфигурации.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)

Копирует строку широких символов str в *config_str.

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

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)

Декодирует str с использованием Py_DecodeLocale() и устанавливает результат в *config_str.

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

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)

Устанавливает аргументы командной строки (argv член config) из списка строк широких символов argv.

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

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

Устанавливает аргументы командной строки (argv член config) из списка байтовых строк argv. Декодирование байтов происходит с использованием Py_DecodeLocale().

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

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)

Устанавливает список широких строк list длиной length и элементами items.

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

PyStatus PyConfig_Read(PyConfig *config)

Считывает всю конфигурацию Python.

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

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

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

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

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

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

void PyConfig_Clear(PyConfig *config)

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

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

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

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

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

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

PyWideStringList argv

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

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

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

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

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

int safe_path

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

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

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

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

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

wchar_t *base_exec_prefix

sys.base_exec_prefix.

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

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

wchar_t *base_executable

Базовый исполняемый файл Python: sys._base_executable.

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

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

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

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

wchar_t *base_prefix

sys.base_prefix.

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

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

int buffered_stdio

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

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

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

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

int bytes_warning

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

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

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

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

int warn_default_encoding

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

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

Введено в версии 3.10.

int code_debug_ranges

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

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

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

Введено в версии 3.11.

wchar_t *check_hash_pycs_mode

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

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

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

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

См. также PEP 552 «Детерминированные pycs».

int configure_c_stdio

Если отлично от нуля, настраивает потоки C стандартного ввода-вывода:

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

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

int dev_mode

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

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

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

int dump_refs

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

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

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

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

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

wchar_t *exec_prefix

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

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

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

wchar_t *executable

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

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

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

int faulthandler

Включить faulthandler?

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

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

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

wchar_t *filesystem_encoding

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

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

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

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

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

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

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

wchar_t *filesystem_errors

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

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

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

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

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

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

unsigned long hash_seed

int use_hash_seed

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

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

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

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

wchar_t *home

Каталог Python.

Если 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 isolated

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

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

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

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

См. также PyPreConfig.isolated.

int legacy_windows_stdio

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

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

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

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

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

int malloc_stats

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

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

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

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

wchar_t *platlibdir

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

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

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

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

New in version 3.9.

Changed in version 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.

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

int pathconfig_warnings

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

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

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

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

wchar_t *prefix

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

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

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

wchar_t *program_name

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

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

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

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

wchar_t *pycache_prefix

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

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

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

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

int quiet

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

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

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

wchar_t *run_command

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

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

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

wchar_t *run_filename

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

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

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

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

wchar_t *run_module

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

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

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

int show_ref_count

Показывать общую счётчик ссылок при выходе?

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

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

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

int site_import

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

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

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

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

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

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

int skip_source_first_line

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

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

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

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

wchar_t *stdio_encoding

wchar_t *stdio_errors

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

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

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

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

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

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

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

int tracemalloc

Включить tracemalloc?

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

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

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

int use_environment

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

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

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

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

int user_site_directory

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

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

Устанавливается опцией командной строки -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 инициализируется несколько раз, PyImport_AppendInittab() или PyImport_ExtendInittab() необходимо вызывать перед каждой инициализацией Python.

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

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

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

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

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

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

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

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

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

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

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

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

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

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

    status = Py_InitializeFromConfig(&config);

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

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

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

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

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

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

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

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

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

Настройка пути Python

PyConfig содержит несколько полей для настройки пути:

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

  • PyConfig.home
  • PyConfig.platlibdir
  • PyConfig.pathconfig_warnings
  • PyConfig.program_name
  • PyConfig.pythonpath_env
  • текущая рабочая директория: для получения абсолютных путей
  • PATH переменная окружения для получения полного пути к программе (из PyConfig.program_name)
  • __PYVENV_LAUNCHER__ переменная окружения
  • (Только для Windows) Пути приложений в реестре по ключу “SoftwarePythonPythonCoreX.YPythonPath” в HKEY_CURRENT_USER и HKEY_LOCAL_MACHINE (где X.Y — версия Python).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Py_RunMain()

int Py_RunMain(void)

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

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

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

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

Py_GetArgcArgv()

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

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

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

API предварительной версии для многофазного инициализации

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

• Фаза инициализации «ядра», «минимальный Python»:

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

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

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

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

• PyConfig._init_main: если установлено 0, Py_InitializeFromConfig() останавливается на фазе инициализации «ядра».
• PyConfig._isolated_interpreter: если ненулевое, запрещает потоки, подпроцессы и fork.

PyStatus _Py_InitializeMain(void)

Переход к фазе инициализации «основная», завершение инициализации Python.

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

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

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

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

void init_python(void)
{
    PyStatus status;

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

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

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

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

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

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