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

Если длина отлична от нуля, элементы должны быть не``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)

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

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

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

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

Структурные поля:

Py_ssize_t length

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

wchar_t **items

Перечислите элементы.

ПиСтатус

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, укажите язык Си.

Если равно 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

Изолированный режим: смотрите : c:member:PyConfig.isolated.

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

int legacy_windows_fs_encoding

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

  • Установите для c:member:PyPreConfig.utf8_mode значение 0,

  • Установите для c:member:PyConfig.filesystem_encoding значение "mbcs",

  • Установите для c:member: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:

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

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

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

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

предварительная настройка не должна быть NULL.

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

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

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

предварительная настройка не должна быть NULL.

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

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

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

предварительная настройка не должна быть NULL.

Вызывающий объект отвечает за обработку исключений (ошибка или выход), используя: c:func: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)

Задайте аргументы командной строки (argv элемент config) из списка широких символьных строк 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.

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

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

Функция 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_SetArgv() или PyConfig_SetBytesArgv(), этот метод должен вызываться перед другими методами, поскольку конфигурация предварительной инициализации зависит от аргументов командной строки (если parse_argv не равно нулю).

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

Структурные поля:

PyWideStringList argv

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

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

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

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

Смотрите также элемент orig_argv.

int safe_path

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

  • Если argv[0] равно L"-m" (python -m module),, добавьте в начало текущий рабочий каталог.

  • При запуске скрипта (python script.py), укажите в начале каталог скрипта. Если это символическая ссылка, разрешите символические ссылки.

  • В противном случае (python -c code и python) добавьте пустую строку, которая означает текущий рабочий каталог.

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

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

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

wchar_t *base_exec_prefix

sys.base_exec_prefix.

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

Часть вывода Python 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 не равно нулю, отключите буферизацию в потоках C stdout и stderr.

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

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

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

int bytes_warning

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

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

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

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

int warn_default_encoding

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

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

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

int code_debug_ranges

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

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

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

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

wchar_t *check_hash_pycs_mode

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

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

  • L"always": Хэширует исходный файл для признания его недействительным независимо от значения флага „check_source“.

  • L"never": Предположим, что фотографии, основанные на хэше, всегда действительны.

  • 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 не равно нулю, включите буферизацию потока в стандартном вводе и стандартном выводе (только стандартный вывод в 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.

wchar_t *executable

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

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

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

int 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, включите интерактивный режим (ОТВЕТИТЬ).

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

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

int isolated

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

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

  • Установите для c:member:~PyConfig.use_environment значение 0.

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

  • Python REPL не импортирует 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 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.

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

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

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

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

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

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

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

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

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

wchar_t *prefix

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

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

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

wchar_t *program_name

Имя программы, используемое для инициализации : c:member:~PyConfig.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. Используется функцией Py_RunMain().

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

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

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

wchar_t *run_module

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

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

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

int show_ref_count

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

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

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

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

int site_import

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

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

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

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

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

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

int skip_source_first_line

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

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

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

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

wchar_t *stdio_encoding
wchar_t *stdio_errors

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

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

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

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

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

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

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

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

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

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

Если хотя бы одно «поле вывода» не задано, 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.

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

  • pyvenv.cfg

  • ._pth файл (например: python._pth)

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

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

  • Установите для c:member:~PyConfig.isolated значение 1.

  • Установите для c:member:~PyConfig.use_environment значение 0.

  • Установите для c:member:~PyConfig.site_import значение 0.

  • Установите для c:member:~PyConfig.safe_path значение 1.

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

Py_Run Main()

int Py_RunMain(void)

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

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

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

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

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

PyStatus _Py_InitializeMain(void)

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

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

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

«Основная» фаза не определена должным образом: что должно быть доступно, а что нет на этом этапе, пока не указано. 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);
    }
}
Инициализация, завершение и потоки
Управление памятью
Вернуться на верх