Документация Python неофициальный перевод
Содержание страницы

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

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

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

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

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

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

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

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

См. также

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

ПримерExample

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

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

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

    /* Декодировать аргументы командной строки.
       Неявно предварительно инициализировать Python (в изолированном режиме). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

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

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Вывести сообщение об ошибке и завершить процесс с
       ненулевым кодом выхода */
    Py_ExitStatusException(status);
}

PyWideStringList

type PyWideStringList

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

Если length не равно нулю, items должен быть не NULL, а все строки должны быть\nне NULL.

Методы:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)

Добавляет item в list.

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

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

Вставляет item в list по индексу index.

Если index больше или равен длине list, добавляет item в\nlist.

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

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

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

Py_ssize_t length

Длина списка.

wchar_t **items

Элементы списка.

PyStatus

type PyStatus

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

В случае ошибки может хранить имя C-функции, вызвавшей ошибку.

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

int exitcode

Код выхода. Аргумент, передаваемый в exit().

const char *err_msg

Сообщение об ошибке.

const char *func

Имя функции, создавшей ошибку, может быть NULL.

Функции создания статуса:

PyStatus PyStatus_Ok(void)

Успех.

PyStatus PyStatus_Error(const char *err_msg)

Ошибка инициализации с сообщением.

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

PyStatus PyStatus_NoMemory(void)

Сбой выделения памяти (не хватает памяти).

PyStatus PyStatus_Exit(int exitcode)

Завершить Python с указанным кодом выхода.

Функции обработки статуса:

int PyStatus_Exception(PyStatus status)

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

int PyStatus_IsError(PyStatus status)

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

int PyStatus_IsExit(PyStatus status)

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

void Py_ExitStatusException(PyStatus status)

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

Примечание

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

Пример:

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

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

PyPreConfig

type PyPreConfig

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

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

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

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

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

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

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

int allocator

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

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

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

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

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

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

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

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

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

int parse_argv

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

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

int use_environment

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

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

int utf8_mode

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

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

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

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

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

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

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

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

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

preconfig.utf8_mode = 1;

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

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

Py_Initialize();
/* ... использовать Python API здесь ... */
Py_Finalize();

PyConfig

type PyConfig

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

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

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

void PyConfig_InitPythonConfig(PyConfig *config)

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

void PyConfig_InitIsolatedConfig(PyConfig *config)

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

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

Копировать широкую строку str в *config_str.

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

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

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

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

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

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

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

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

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

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

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

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

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

PyStatus PyConfig_Read(PyConfig *config)

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

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

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

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

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

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

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

void PyConfig_Clear(PyConfig *config)

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

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

Более того, если используется PyConfig_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 в изолированной конфигурации.

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

wchar_t *base_exec_prefix

sys.base_exec_prefix.

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

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

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

wchar_t *base_executable

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

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

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

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

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

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

wchar_t *base_prefix

sys.base_prefix.

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

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

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

int buffered_stdio

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

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

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

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

int bytes_warning

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

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

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

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

int warn_default_encoding

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

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

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

int code_debug_ranges

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

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

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

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

wchar_t *check_hash_pycs_mode

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

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

  • L"always": Хешировать исходный файл для инвалидации независимо от значения флага ‘check_source’.

  • L"never": Считать, что хеш-основанные pyc всегда корректны.

  • L"default": Флаг ‘check_source’ в хеш-основанных pyc определяет недействительность.

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

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

int configure_c_stdio

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

  • В Windows устанавливается двоичный режим (O_BINARY) для stdin, stdout и stderr.

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

  • Если interactive не равно нулю, буферизация потоков stdin и stdout включается (только stdout в Windows).

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

int dev_mode

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

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

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

int dump_refs

Сбрасывать ссылки Python?

Если не равно нулю, сбрасывать все объекты, которые все еще существуют при завершении.

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

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

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

wchar_t *exec_prefix

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

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

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

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

wchar_t *executable

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

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

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

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

int faulthandler

Включить faulthandler?

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

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

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

wchar_t *filesystem_encoding

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

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

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

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

  • "utf-8", если PyPreConfig.utf8_mode не равно нулю.

  • "ascii", если Python определяет, что nl_langinfo(CODESET) объявляет кодировку ASCII, в то время как функция mbstowcs() декодирует из другой кодировки (обычно Latin1).

  • "utf-8", если nl_langinfo(CODESET) возвращает пустую строку.

  • В противном случае используется кодировка локали: результат nl_langinfo(CODESET).

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

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

wchar_t *filesystem_errors

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

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

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

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

  • "strict"

  • "surrogateescape"

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

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

unsigned long hash_seed
int use_hash_seed

Случайное зерно хеш-функции.

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

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

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

wchar_t *home

Задаёт каталог Python «home» по умолчанию, то есть расположение стандартных библиотек Python (см. PYTHONHOME).

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

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

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

int import_time

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

Значение 1 задаётся опцией -X importtime и переменной окружения PYTHONPROFILEIMPORTTIME.

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

int inspect

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

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

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

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

int install_signal_handlers

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

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

int interactive

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

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

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

int int_max_str_digits

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

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

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

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

int cpu_count

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

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

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

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

int isolated

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

  • Установить safe_path в 1: не добавлять потенциально небезопасный путь к sys.path при запуске Python, например, текущий каталог, каталог скрипта или пустую строку.

  • Установить use_environment в 0: игнорировать переменные окружения PYTHON.

  • Установить user_site_directory в 0: не добавлять каталог пользовательских сайт-пакетов в sys.path.

  • REPL Python не импортирует readline и не включает стандартную конфигурацию readline в интерактивных приглашениях.

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

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

См. также Изолированная конфигурация и PyPreConfig.isolated.

int legacy_windows_stdio

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

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

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

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

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

int malloc_stats

Если не ноль, вывести статистику по аллокатору памяти Python pymalloc при завершении.

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

Параметр игнорируется, если Python configured using the --without-pymalloc option.

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

wchar_t *platlibdir

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

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

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

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

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

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

wchar_t *pythonpath_env

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

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

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

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

PyWideStringList module_search_paths
int module_search_paths_set

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

Если module_search_paths_set равно 0, Py_InitializeFromConfig() заменит module_search_paths и установит module_search_paths_set в 1.

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

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

int optimization_level

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

  • 0: Оптимизатор Peephole, устанавливает __debug__ в True.

  • 1: Уровень 0, удаляет утверждения, устанавливает __debug__ в False.

  • 2: Уровень 1, удаляет строки документации.

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

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

PyWideStringList orig_argv

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

Если список orig_argv пуст, а argv не является списком, содержащим только пустую строку, то PyConfig_Read() копирует argv в orig_argv перед изменением argv (если parse_argv не равно нулю).

См. также элемент argv и функцию Py_GetArgcArgv().

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

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

int parse_argv

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

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

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

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

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

int pathconfig_warnings

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

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

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

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

wchar_t *prefix

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

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

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

См. также 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.

wchar_t *pycache_prefix

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

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

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

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

int quiet

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

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

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

wchar_t *run_command

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

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

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

wchar_t *run_filename

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

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

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

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

wchar_t *run_module

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

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

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

wchar_t *run_presite

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

Устанавливается параметром командной строки -X presite=package.module и переменной окружения PYTHON_PRESITE. Параметр командной строки имеет приоритет.

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

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

int show_ref_count

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

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

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

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

int site_import

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

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

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

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

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

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

int skip_source_first_line

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

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

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

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

wchar_t *stdio_encoding
wchar_t *stdio_errors

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

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

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

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

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

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

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

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

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

int use_environment

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

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

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

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

int user_site_directory

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

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

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

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

int verbose

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

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

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

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

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

PyWideStringList warnoptions

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

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

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

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

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

int write_bytecode

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

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

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

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

PyWideStringList xoptions

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

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

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

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

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

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

Инициализация интерпретатора из заполненной структуры конфигурации выполняется вызовом Py_InitializeFromConfig().

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

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

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

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

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Установить имя программы. Неявно предварительно инициализировать Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto exception;
    }

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

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

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

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

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

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

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

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

    /* Указать sys.path явно */
    /* Если требуется изменить стандартный набор путей, завершите
       сначала инициализация, а затем использование PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) {
        goto done;
    }
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Переопределить исполняемый файл, вычисленный PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • Если run_module задан, добавьте текущий каталог в начало sys.path. Ничего не делайте, если текущий каталог не может быть прочитан.

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

    • В противном случае пустая строка добавляется в начало sys.path.

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

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

  • pyvenv.cfg

  • Файл ._pth (например, python._pth)

  • pybuilddir.txt (только Unix)

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

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

Py_GetArgcArgv()

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

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

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

Многофазная инициализация (частный временный API)Multi-Phase Initialization Private Provisional API

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

  • Фаза «базовой» инициализации, «минимальный Python»:

    • Встроенные типы;

    • Встроенные исключения;

    • Встроенные и замороженные модули;

    • Модуль sys инициализирован лишь частично (например, sys.path ещё не существует).

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

    • Устанавливает и настраивает importlib;

    • Применяет конфигурацию путей;

    • Устанавливает обработчики сигналов;

    • Завершает инициализацию модуля sys (например, создаёт sys.stdout и sys.path);

    • Включает опциональные возможности, такие как faulthandler и tracemalloc;

    • Импортировать модуль site;

    • и т. д.

Частный временный API:

  • PyConfig._init_main: если установлено в 0, Py_InitializeFromConfig() останавливается на этапе инициализации «Core».

PyStatus _Py_InitializeMain(void)

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

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

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

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

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

void init_python(void)
{
    PyStatus status;

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

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

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

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

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

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