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

Добавлено в версии 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 больше или равен длине списка, добавьте элемент в список.

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_PYMALLOC и PYMEM_ALLOCATOR_PYMALLOC_DEBUG не поддерживаются, если Python имеет значение configured using --without-pymalloc.

См. 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

Если ненулевая:

Инициализировано значение переменной окружения 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.

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

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

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

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

Текущая предварительная конфигурация (тип 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)

Установите аргументы командной строки (член configargv) из списка 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.

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

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

void PyConfig_Clear(PyConfig *config)

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

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

Более того, если используется 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 Path Configuration.

wchar_t *base_executable

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

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

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

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

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

wchar_t *base_prefix

sys.base_prefix.

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

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

int buffered_stdio

Если равно 0 и configure_c_stdio ненулевое значение, отключите буферизацию на потоках Си 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.

Добавлено в версии 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 Development Mode.

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

wchar_t *executable

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

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

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

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.

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

Устанавливается переменной окружения 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 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 memory allocator.

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

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

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

wchar_t *platlibdir

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

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

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

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

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

wchar_t *pythonpath_env

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

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

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

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

PyWideStringList module_search_paths
int module_search_paths_set

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

Если module_search_paths_set равно 0, функция, вычисляющая Python Path Configuration, переопределяет module_search_paths и устанавливает module_search_paths_set в 1.

По умолчанию: пустой список (module_search_paths) и 0 (module_search_paths_set).

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

int optimization_level

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

  • 0: Peephole optimizer, установите __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 разбирает 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.

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

int pathconfig_warnings

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

Это не влияет на Windows.

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

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

wchar_t *prefix

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

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

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

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

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

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

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

wchar_t *run_module

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

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

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

int show_ref_count

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

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

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

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

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

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

  • В 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

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

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

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

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

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 Path Configuration («поля вывода»), чтобы игнорировать эти файлы конфигурации и избежать вычисления функцией конфигурации пути по умолчанию.

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

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

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

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

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

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

Если хотя бы одно «поле вывода» не установлено, 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-пакета пользователя существует, модуль site добавляет каталог 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), указанные в командной строке или в конфигурации.

По умолчанию и при использовании опции if -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».

  • PyConfig._isolated_interpreter: если ненулевое значение, запретить потоки, подпроцессы и развилки.

PyStatus _Py_InitializeMain(void)

Перейдите к фазе инициализации «Main», завершите инициализацию Python.

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

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

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

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

void init_python(void)
{
    PyStatus status;

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

    /* ... 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);
    }
}
Инициализация, финализация и потоки
Управление памятью
Вернуться на верх