Конфигурация инициализации 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)

Является ли статус ошибкой или выходом? Если true, исключение должно быть обработано, например, вызвав Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)

Является ли результат ошибкой?

int PyStatus_IsExit(PyStatus status)

Является ли результат выходом?

void Py_ExitStatusException(PyStatus status)

Вызвать exit(exitcode) если status - выход. Вывести сообщение об ошибке и завершить с ненулевым кодом завершения, если status - ошибка. Должен вызываться только если PyStatus_Exception(status) не равно нулю.

Пример:

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

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

PyPreConfig

type PyPreConfig

Структура, используемая для предварительной инициализации Python.

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

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

Инициализировать предварительную конфигурацию с Конфигурацией Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

Инициализировать предварительную конфигурацию с Изолированной конфигурацией.

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

int allocator

Имя выделения памяти Python:

• PYMEM_ALLOCATOR_NOT_SET (0): не менять выделение памяти (использовать значения по умолчанию).
• PYMEM_ALLOCATOR_DEFAULT (1): стандартные выделения памяти.
• PYMEM_ALLOCATOR_DEBUG (2): стандартные выделения памяти с отладкой.
• PYMEM_ALLOCATOR_MALLOC (3): использовать malloc() библиотеки C.
• PYMEM_ALLOCATOR_MALLOC_DEBUG (4): принудительно использовать malloc() с отладкой.
• PYMEM_ALLOCATOR_PYMALLOC (5): распределитель памяти Python pymalloc.
• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): распределитель памяти Python pymalloc с отладкой.

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

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

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

int configure_locale

Установить локаль LC_CTYPE на предпочтительную локаль пользователя.

Если равно 0, установить coerce_c_locale и coerce_c_locale_warn в 0.

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

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

int coerce_c_locale

Если равно 2, принудительно установить локаль C.

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

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

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

int coerce_c_locale_warn

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

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

int dev_mode

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

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

int isolated

Режим изоляции: см. PyConfig.isolated.

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

int legacy_windows_fs_encoding

Если ненулевое:

• Установить PyPreConfig.utf8_mode в 0,
• Установить PyConfig.filesystem_encoding в "mbcs",
• Установить PyConfig.filesystem_errors в "replace".

Инициализируется из значения переменной окружения PYTHONLEGACYWINDOWSFSENCODING.

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

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

int parse_argv

Если ненулевое, Py_PreInitializeFromArgs() и Py_PreInitializeFromBytesArgs() парсят свой аргумент argv так же, как обычный Python парсит аргументы командной строки: см. Аргументы командной строки.

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

int use_environment

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

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

int utf8_mode

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

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

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

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

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

• Установить выделение памяти Python (PyPreConfig.allocator)
• Настроить локаль LC_CTYPE (кодировка локали)
• Установить режим Python UTF-8 (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 инициализируется с аргументами командной строки, эти аргументы также должны передаваться для предварительной инициализации, так как они влияют на предварительную конфигурацию, например, на кодировки. Например, опция командной строки -X utf8 включает режим Python UTF-8.

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:

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.

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

Функция 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.

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.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

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

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

wchar_t *base_executable

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

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

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

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

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

wchar_t *base_prefix

sys.base_prefix.

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

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

int buffered_stdio

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

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

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

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

int bytes_warning

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

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

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

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

int warn_default_encoding

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

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

Новое в версии 3.10.

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 в режиме Python, 0 в изолированном режиме.

int dump_refs

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

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

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

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

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

wchar_t *exec_prefix

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

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

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

wchar_t *executable

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

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

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

int faulthandler

Включить faulthandler?

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

Устанавливается значением 1 параметром -X faulthandler и переменной окружения PYTHONFAULTHANDLER.

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

wchar_t *filesystem_encoding

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

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

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

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

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

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

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

wchar_t *filesystem_errors

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

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

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

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

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

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

unsigned long hash_seed

int use_hash_seed

Семена генератора случайных чисел для хэш-функции.

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

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

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

wchar_t *home

Директория домашней папки Python.

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

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

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

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

int import_time

Если ненулевое значение, профилировать время импорта.

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

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

• sys.path не содержит ни директорию скрипта (вычисленную из argv[0] или текущую директорию), ни директорию site-packages пользователя.
• В Python REPL не импортируется readline и не настраивается стандартная конфигурация readline для интерактивных запросов.
• Установите use_environment и user_site_directory в 0.

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

Часть входных данных для Настройка пути Python.

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

wchar_t *pythonpath_env

Пути поиска модулей (sys.path) в виде строки, разделенной символом DELIM (os.path.pathsep).

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

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

Часть входных данных для Настройка пути Python.

PyWideStringList module_search_paths

int module_search_paths_set

Пути поиска модулей: sys.path.

Если module_search_paths_set равно 0, функция, вычисляющая Настройка пути Python, перезаписывает 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

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

Не оказывает влияния на Windows.

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

Часть входных данных для Настройка пути Python.

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.

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

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

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

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

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

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

int user_site_directory

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

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

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

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

int verbose

Режим подробных сообщений. Если больше 0, выводить сообщение каждый раз при импорте модуля, показывая место (имя файла или встроенный модуль), откуда он загружается.

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

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

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

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

PyWideStringList warnoptions

Параметры модуля warnings для построения фильтров предупреждений, от низшего к высшему приоритету: sys.warnoptions.

Модуль warnings добавляет sys.warnoptions в обратном порядке: последний элемент PyConfig.warnoptions становится первым элементом в warnings.filters, который проверяется первым (высший приоритет).

Командная строка опции -W добавляет своё значение в warnoptions, ее можно использовать несколько раз.

Переменная среды PYTHONWARNINGS также может быть использована для добавления параметров предупреждений. Можно указать несколько параметров, разделенных запятыми (,).

Значение по умолчанию: пустой список.

int write_bytecode

Если равно 0, Python не будет пытаться записать .pyc файлы при импорте исходных модулей.

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

sys.dont_write_bytecode инициализируется обратным значением write_bytecode.

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

PyWideStringList xoptions

Значения опций командной строки -X: sys._xoptions.

Значение по умолчанию: пустой список.

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

Опции xoptions анализируются для установки других опций: см. опцию командной строки -X.

Инициализация с PyConfig

Функция для инициализации Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Инициализация Python из конфигурации config.

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

Если используются PyImport_FrozenModules(), PyImport_AppendInittab() или PyImport_ExtendInittab(), их необходимо установить или вызвать после предварительной инициализации Python и перед инициализацией Python. Если Python инициализируется несколько раз, PyImport_AppendInittab() или PyImport_ExtendInittab() необходимо вызвать перед каждой инициализацией Python.

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

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

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

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

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

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

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

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

    /* Append our custom search path to sys.path */
    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 остаются неизменными. Обработчики сигналов не устанавливаются.

Конфигурационные файлы всё ещё используются с этой конфигурацией. Установите Конфигурацию пути Python (“выходные поля”) для игнорирования этих конфигурационных файлов и предотвращения вычисления функции конфигурации по умолчанию.

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

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

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

Эта функция включает принуждение локали C (PEP 538) и Режим Python UTF-8 (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. В этом случае входные поля настройки пути также игнорируются.

Установите 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
• python._pth (Только Windows)
• pybuilddir.txt (Только Unix)

Переменная среды __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);
    }
}