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

Added in version 3.8.

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

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

С помощью Python Configuration можно создать собственный Python, который ведет себя как обычный Python. Например, для настройки Python используются переменные окружения и аргументы командной строки.
Isolated Configuration можно использовать для встраивания Python в приложение. Он изолирует Python от системы. Например, игнорируются переменные окружения, локаль LC_CTYPE остается неизменной и не регистрируется обработчик сигналов.

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

См. также Initialization, Finalization, and Threads.

См.также

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

Добавьте элемент в список.

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

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶

Вставьте элемент в список по адресу индекс.

Если index больше или равен длине списка, добавьте item в список.

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) ненулевое.

Примечание

Внутри 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 Configuration.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: Инициализируйте предварительную конфигурацию с помощью Isolated Configuration.

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

int allocator¶

Имя распределителей памяти Python:

PYMEM_ALLOCATOR_NOT_SET (0): не изменяйте аллокаторы памяти (используйте значения по умолчанию).
PYMEM_ALLOCATOR_DEFAULT (1): default memory allocators.
PYMEM_ALLOCATOR_DEBUG (2): default memory allocators с debug hooks.
PYMEM_ALLOCATOR_MALLOC (3): использование malloc() библиотеки C.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): принудительное использование malloc() с debug hooks.
PYMEM_ALLOCATOR_PYMALLOC (5): Python pymalloc memory allocator.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python pymalloc memory allocator с debug hooks.
PYMEM_ALLOCATOR_MIMALLOC (6): используйте mimalloc, быструю замену malloc.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): используйте mimalloc, быструю замену malloc на debug hooks.

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

PYMEM_ALLOCATOR_MIMALLOC и PYMEM_ALLOCATOR_MIMALLOC_DEBUG не поддерживаются, если Python имеет значение configured using --without-mimalloc или если базовая атомарная поддержка недоступна.

См. Memory Management.

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

int configure_locale¶

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

Если равно 0, установите члены coerce_c_locale и coerce_c_locale_warn в значение 0.

Смотрите locale encoding.

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

int coerce_c_locale¶

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

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

Смотрите locale encoding.

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

int coerce_c_locale_warn¶

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

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

int dev_mode¶

Python Development Mode: см. 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".

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

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

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

int parse_argv¶

Если значение ненулевое, то Py_PreInitializeFromArgs() и Py_PreInitializeFromBytesArgs() разбирают свой аргумент argv так же, как обычный Python разбирает аргументы командной строки: см. Command Line Arguments.

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

int use_environment¶

Использовать environment variables? Смотрите PyConfig.use_environment.

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

int utf8_mode¶

Если значение ненулевое, включите Python UTF-8 Mode.

Установите значение 0 или 1 с помощью опции командной строки -X utf8 и переменной окружения PYTHONUTF8.

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

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

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

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

Установите распределители памяти Python (PyPreConfig.allocator)
Настройте локаль LC_CTYPE (locale encoding)
Установите 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 Configuration (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 Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Инициализируйте конфигурацию с помощью Isolated Configuration.

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

Скопируйте широкую символьную строку str в *config_str.

Preinitialize Python, если это необходимо.

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

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

Preinitialize Python, если это необходимо.

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

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

Preinitialize Python, если это необходимо.

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

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

Preinitialize Python, если это необходимо.

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

Установите в список широких строк list значения length и items.

Preinitialize Python, если это необходимо.

PyStatus PyConfig_Read(PyConfig *config)¶

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

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

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

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

Preinitialize Python, если это необходимо.

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

Изменено в версии 3.11: PyConfig_Read() больше не вычисляет все пути, и поэтому поля, перечисленные в Python Path Configuration, могут не обновляться до вызова Py_InitializeFromConfig().

void PyConfig_Clear(PyConfig *config)¶: Освободите память конфигурации.

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

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

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

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

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

PyWideStringList argv¶

Установите sys.argv аргументов командной строки на основе argv. Эти параметры аналогичны тем, которые передаются в функцию main() программы, с той разницей, что первая запись должна ссылаться на файл сценария, который будет выполняться, а не на исполняемый файл, в котором находится интерпретатор Python. Если скрипт не будет выполняться, то первым параметром в argv может быть пустая строка.

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

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

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

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

int safe_path¶

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

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

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

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

Added in version 3.11.

wchar_t *base_exec_prefix¶

sys.base_exec_prefix.

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

Часть выхода Python Path Configuration.

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

wchar_t *base_executable¶

Исполняемый файл базы Python: sys._base_executable.

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

Установите значение от PyConfig.executable до NULL.

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

Часть выхода Python Path Configuration.

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

wchar_t *base_prefix¶

sys.base_prefix.

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

Часть выхода Python Path Configuration.

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

int buffered_stdio¶

Если значение 0 равно configure_c_stdio и 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 использует кодировку по умолчанию. Подробности см. в разделе ОптКодированиеПредупреждение.

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

Added in version 3.10.

int code_debug_ranges¶

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

Установите значение 0 с помощью переменной окружения PYTHONNODEBUGRANGES и опции командной строки -X no_debug_ranges.

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

Added in version 3.11.

wchar_t *check_hash_pycs_mode¶

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

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

L"always": Хеширование исходного файла на предмет недействительности независимо от значения флага „check_source“.
L"never": Предполагается, что хэш-пики всегда действительны.
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 Development Mode.

Установите значение 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 Path Configuration.

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

wchar_t *executable¶

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

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

Часть выхода Python Path Configuration.

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

int faulthandler¶

Включить faulthandler?

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

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

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

wchar_t *filesystem_encoding¶

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) возвращает пустую строку.
В противном случае используйте результат locale encoding: nl_langinfo(CODESET).

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

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

wchar_t *filesystem_errors¶

Filesystem error handler: 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 по умолчанию, то есть местоположение стандартных библиотек Python (см. PYTHONHOME).

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

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

Часть входа Python Path Configuration.

int import_time¶

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

Установите значение 1 с помощью опции -X importtime и переменной окружения PYTHONPROFILEIMPORTTIME.

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

int inspect¶

Переход в интерактивный режим после выполнения сценария или команды.

Если больше 0, включите проверку: если в качестве первого аргумента передан скрипт или используется опция -c, перейдите в интерактивный режим после выполнения скрипта или команды, даже если sys.stdin не является терминалом.

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

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

int install_signal_handlers¶

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

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

int interactive¶

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

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

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

int int_max_str_digits¶

Настраивает значение integer string conversion length limitation. Начальное значение -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) в изолированном режиме.

Added in version 3.12.

int cpu_count¶

Если значение cpu_count не равно -1, то оно отменяет возвращаемые значения os.cpu_count(), os.process_cpu_count() и multiprocessing.cpu_count().

Настраивается с помощью флага командной строки -X cpu_count=n|default или переменной окружения PYTHON_CPU_COUNT.

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

Added in version 3.13.

int isolated¶

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

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

Установите значение 1 с помощью опции командной строки -I.

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

См. также Isolated Configuration и 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 memory allocator.

Установите значение 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 Path Configuration.

Added in version 3.9.

Изменено в версии 3.11: Этот макрос теперь используется в Windows для размещения модулей расширения стандартной библиотеки, обычно под DLLs. Однако для совместимости обратите внимание, что это значение игнорируется для любых нестандартных компоновок, включая сборки in-tree и виртуальные окружения.

wchar_t *pythonpath_env¶

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

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

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

Часть входа Python Path Configuration.

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 Path Configuration.

int optimization_level¶

Уровень оптимизации компиляции:

0: Оптимизатор глазок, установите __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().

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

Added in version 3.10.

int parse_argv¶

Разбор аргументов командной строки?

Если равно 1, разберите argv так же, как обычный Python разбирает command line arguments, и удалите аргументы 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.

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

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

int pathconfig_warnings¶

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

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

Часть входа Python Path Configuration.

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

wchar_t *prefix¶

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

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

Часть выхода Python Path Configuration.

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

wchar_t *program_name¶

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

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

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

Часть входа Python Path Configuration.

wchar_t *pycache_prefix¶

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

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

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

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

int quiet¶

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

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

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

wchar_t *run_command¶

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

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

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

wchar_t *run_filename¶

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

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

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

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

wchar_t *run_module¶

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

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

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

wchar_t *run_presite¶

package.module путь к модулю, который должен быть импортирован перед запуском site.py.

Задается параметром командной строки -X presite=package.module и переменной окружения PYTHON_PRESITE. Опция командной строки имеет приоритет.

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

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

int show_ref_count¶

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

Установите значение 1 с помощью опции командной строки -X showrefcount.

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

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

int site_import¶

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

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

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

Установите значение 0 с помощью опции командной строки -S.

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

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

int skip_source_first_line¶

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

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

Установите значение 1 с помощью опции командной строки -x.

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

wchar_t *stdio_encoding¶

wchar_t *stdio_errors¶

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

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

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

"UTF-8", если PyPreConfig.utf8_mode ненулевое.
В противном случае используйте locale encoding.

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

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

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

int tracemalloc¶

Включить tracemalloc?

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

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

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

int perf_profiling¶

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

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

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

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

Added in version 3.12.

int use_environment¶

Использовать environment variables?

Если значение равно нулю, игнорируйте environment variables.

Установите значение 0 с помощью переменной окружения -E.

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

int user_site_directory¶

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

Установите значение 0 с помощью опций командной строки -s и -I.

Установите значение 0 с помощью переменной окружения PYTHONNOUSERSITE.

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

int verbose¶

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

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

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

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

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

PyWideStringList warnoptions¶

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

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

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

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

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

int write_bytecode¶

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

Установите значение 0 с помощью опции командной строки -B и переменной окружения PYTHONDONTWRITEBYTECODE.

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

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

PyWideStringList xoptions¶

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

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

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

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

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

Инициализация с помощью PyConfig¶

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

PyStatus Py_InitializeFromConfig(const PyConfig *config)¶: Инициализация Python из конфигурации config.

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

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

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

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

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

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

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

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

Более полный пример изменения конфигурации по умолчанию, чтения конфигурации и переопределения некоторых параметров. Обратите внимание, что начиная с версии 3.11 многие параметры не вычисляются до инициализации, и поэтому значения не могут быть считаны из структуры конфигурации. Любые значения, установленные до вызова 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) и Python UTF-8 Mode (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).
Поля вывода конфигурации пути:

Если хотя бы одно «поле вывода» не задано, 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 Configuration для примера того, как настроить 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;
- Примените Path Configuration;
- Установите обработчики сигналов;
- Завершите инициализацию модуля 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 импортер или крючок импорта и т. д.

Возможно, в Python станет возможным вычислять Path Configuration после фазы 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;

    /* ... 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);
    }
}

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

Пример¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

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

PyConfig¶

Инициализация с помощью PyConfig¶

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

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

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

Py_RunMain()¶

Py_GetArgcArgv()¶

Многофазная инициализация Частный временный API¶

Оглавление

Предыдущий раздел

Следующий раздел