Инициализация, завершение и потоки

Перед инициализацией Python

В приложении, подключающем Python, функция Py_Initialize() должна быть вызвана перед использованием любых других функций Python/C API; за исключением нескольких функций и глобальных переменных конфигурации.

Следующие функции можно безопасно вызывать до инициализации Python:

• Функции конфигурации:

  • PyImport_AppendInittab()
  • PyImport_ExtendInittab()
  • PyInitFrozenExtensions()
  • PyMem_SetAllocator()
  • PyMem_SetupDebugHooks()
  • PyObject_SetArenaAllocator()
  • Py_SetPath()
  • Py_SetProgramName()
  • Py_SetPythonHome()
  • Py_SetStandardStreamEncoding()
  • PySys_AddWarnOption()
  • PySys_AddXOption()
  • PySys_ResetWarnOptions()

• Информационные функции:

  • Py_IsInitialized()
  • PyMem_GetAllocator()
  • PyObject_GetArenaAllocator()
  • Py_GetBuildInfo()
  • Py_GetCompiler()
  • Py_GetCopyright()
  • Py_GetPlatform()
  • Py_GetVersion()

• Утилиты:

  • Py_DecodeLocale()

• Менеджеры памяти:

  • PyMem_RawMalloc()
  • PyMem_RawRealloc()
  • PyMem_RawCalloc()
  • PyMem_RawFree()

Глобальные переменные конфигурации

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

Когда флаг устанавливается с помощью опции, значение флага равно числу раз, когда эта опция была установлена. Например, -b устанавливает Py_BytesWarningFlag в 1, а -bb устанавливает Py_BytesWarningFlag в 2.

int Py_BytesWarningFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.bytes_warning, см. Конфигурация инициализации Python.

Выдать предупреждение при сравнении bytes или bytearray с str или bytes с int. Выдать ошибку, если значение больше или равно 2.

Устанавливается опцией -b.

Устарело начиная с версии 3.12.

int Py_DebugFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.parser_debug, см. Конфигурация инициализации Python.

Включить вывод отладки парсера (только для специалистов, зависит от параметров компиляции).

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

Устарело начиная с версии 3.12.

int Py_DontWriteBytecodeFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.write_bytecode, см. Конфигурация инициализации Python.

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

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

Устарело начиная с версии 3.12.

int Py_FrozenFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.pathconfig_warnings, см. Конфигурация инициализации Python.

Отключить сообщения об ошибках при вычислении пути поиска модулей в Py_GetPath().

Приватный флаг, используемый программами _freeze_module и frozenmain.

Устарело начиная с версии 3.12.

int Py_HashRandomizationFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.hash_seed и PyConfig.use_hash_seed, см. Конфигурация инициализации Python.

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

Если флаг ненулевой, используйте переменную окружения PYTHONHASHSEED для инициализации секредного семени хеширования.

Устарело начиная с версии 3.12.

int Py_IgnoreEnvironmentFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.use_environment, см. Конфигурация инициализации Python.

Игнорировать все переменные окружения PYTHON*, например, PYTHONPATH и PYTHONHOME, которые могут быть установлены.

Устанавливается опциями -E и -I.

Устарело начиная с версии 3.12.

int Py_InspectFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.inspect, см. Конфигурация инициализации Python.

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

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

Устарело начиная с версии 3.12.

int Py_InteractiveFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.interactive, см. Конфигурация инициализации Python.

Устанавливается опцией -i.

Устарело начиная с версии 3.12.

int Py_IsolatedFlag

Этот API сохраняется для обратной совместимости: вместо этого следует использовать установку PyConfig.isolated, см. Конфигурация инициализации Python.

Запустить Python в изолированном режиме. В изолированном режиме sys.path не содержит ни директорию скрипта, ни директорию site-packages пользователя.

Устанавливается опцией -I.

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

Устарело начиная с версии 3.12.

int Py_LegacyWindowsFSEncodingFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyPreConfig.legacy_windows_fs_encoding, см. Настройка инициализации Python.

Если флаг отличен от нуля, для кодировки и обработчика ошибок файловой системы используйте кодировку mbcs с обработчиком ошибок replace, вместо кодировки UTF-8 с обработчиком ошибок surrogatepass.

Устанавливается в 1, если переменная среды PYTHONLEGACYWINDOWSFSENCODING имеет ненулевое значение.

См. PEP 529 для получения более подробной информации.

Доступность: Windows.

Устарело начиная с версии 3.12.

int Py_LegacyWindowsStdioFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.legacy_windows_stdio, см. Настройка инициализации Python.

Если флаг отличен от нуля, используйте io.FileIO вместо io._WindowsConsoleIO для стандартных потоков sys.

Устанавливается в 1, если переменная среды PYTHONLEGACYWINDOWSSTDIO имеет ненулевое значение.

См. PEP 528 для получения более подробной информации.

Доступность: Windows.

Устарело начиная с версии 3.12.

int Py_NoSiteFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.site_import, см. Настройка инициализации Python.

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

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

Устарело начиная с версии 3.12.

int Py_NoUserSiteDirectory

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.user_site_directory, см. Настройка инициализации Python.

Не добавлять user site-packages directory в sys.path.

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

Устарело начиная с версии 3.12.

int Py_OptimizeFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.optimization_level, см. Настройка инициализации Python.

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

Устарело начиная с версии 3.12.

int Py_QuietFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.quiet, см. Настройка инициализации Python.

Не отображать сообщения об авторских правах и версии, даже в интерактивном режиме.

Устанавливается параметром -q.

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

Устарело начиная с версии 3.12.

int Py_UnbufferedStdioFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.buffered_stdio, см. Настройка инициализации Python.

Принудительно сделать потоки stdout и stderr небуферизованными.

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

Устарело начиная с версии 3.12.

int Py_VerboseFlag

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.verbose, см. Настройка инициализации Python.

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

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

Устарело начиная с версии 3.12.

Инициализация и завершение работы интерпретатора

void Py_Initialize()

Часть Стабильного API.

Инициализирует Python-интерпретатор. В приложениях, которые импортируют Python, это следует вызывать перед использованием любых других функций Python/C API; см. Перед инициализацией Python для некоторых исключений.

Инициализирует таблицу загруженных модулей (sys.modules), и создает базовые модули builtins, __main__ и sys. Также инициализирует путь поиска модулей (sys.path). Не устанавливает sys.argv; используйте PySys_SetArgvEx() для этого. При повторном вызове (без предварительного вызова Py_FinalizeEx()) является пустой операцией. Отсутствие возвращаемого значения; ошибка, если инициализация завершилась неудачно.

Для настройки Py_InitializeFromConfig() используйте функцию Конфигурация инициализации Python.

Примечание

В Windows, изменяет режим консоли с O_TEXT на O_BINARY, что также повлияет на не-Python-использование консоли с помощью C Runtime.

void Py_InitializeEx(int initsigs)

Часть Стабильного API.

Эта функция работает как Py_Initialize(), если initsigs равно 1. Если initsigs равно 0, пропускает регистрацию обработки сигналов при инициализации, что может быть полезно при импортировании Python.

Для настройки Py_InitializeFromConfig() используйте функцию Конфигурация инициализации Python.

int Py_IsInitialized()

Часть Стабильного API.

Возвращает true (ненулевое значение), если интерпретатор Python был инициализирован, и false (нуль), если нет. После вызова Py_FinalizeEx(), возвращает false, пока не будет вызван Py_Initialize() снова.

int Py_FinalizeEx()

Часть Стабильного API с версии 3.6.

Отменяет все инициализации, выполненные функцией Py_Initialize() и последующим использованием функций Python/C API, и уничтожает все дочерние интерпретаторы (см. Py_NewInterpreter() ниже), которые были созданы и еще не уничтожены с момента последнего вызова Py_Initialize(). В идеале освобождает всю память, выделенную Python-интерпретатором. Это пустая операция при повторном вызове (без повторного вызова Py_Initialize()).

Поскольку это обратная функция Py_Initialize(), ее следует вызывать в том же потоке с тем же интерпретатором. Это означает основной поток и основной интерпретатор. Никогда не следует вызывать её, когда выполняется Py_RunMain().

В обычном случае возвращаемое значение равно 0. Если при завершении возникли ошибки (очистка буферизированных данных), возвращается -1.

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

Ошибки и замечания: Уничтожение модулей и объектов в модулях выполняется в случайном порядке; это может привести к сбою деструкторов (__del__() методы), если они зависят от других объектов (даже функций) или модулей. Динамически загруженные расширения модулей, загруженные Python, не разгружаются. Небольшое количество памяти, выделенное Python-интерпретатором, может не быть освобождено (если вы обнаружили утечку, сообщите о ней). Память, связанная циклическими ссылками между объектами, не освобождается. Некоторая память, выделенная расширениями модулей, может не быть освобождена. Некоторые расширения могут работать некорректно, если их функция инициализации вызывается более одного раза; это может произойти, если приложение вызовет Py_Initialize() и Py_FinalizeEx() более одного раза.

Вызывает событие аудита cpython._PySys_ClearAuditHooks без аргументов.

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

void Py_Finalize()

Часть Стабильного API.

Это обратная совместимая версия Py_FinalizeEx(), которая игнорирует возвращаемое значение.

Параметры, относящиеся ко всему процессу

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

Этот API сохранён для обратной совместимости: следует использовать установку PyConfig.stdio_encoding и PyConfig.stdio_errors, см. Настройка инициализации Python.

Эта функция должна вызываться до Py_Initialize(), если она вообще вызывается. Она задаёт кодировку и обработку ошибок для стандартного ввода/вывода, с тем же значением, что и в str.encode().

Она переопределяет значения PYTHONIOENCODING, и позволяет коду встраивания контролировать кодировку ввода/вывода, когда переменная окружения не работает.

encoding и/или errors могут быть NULL для использования PYTHONIOENCODING и/или значения по умолчанию (в зависимости от других настроек).

Обратите внимание, что sys.stderr всегда использует обработчик ошибок “backslashreplace”, независимо от этого (или любого другого) параметра.

Если вызывается Py_FinalizeEx(), эта функция должна быть вызвана повторно, чтобы повлиять на последующие вызовы Py_Initialize().

Возвращает 0 при успехе, ненулевое значение при ошибке (например, при вызове после того, как интерпретатор уже был инициализирован).

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

Устарела начиная с версии 3.11.

void Py_SetProgramName(const wchar_t *name)

Часть Стабильной ABI.

Этот API сохранён для обратной совместимости: следует использовать установку PyConfig.program_name, см. Настройка инициализации Python.

Эта функция должна вызываться до Py_Initialize() в первый раз, если она вообще вызывается. Она сообщает интерпретатору значение аргумента argv[0] для функции main() программы (преобразованного в широкие символы). Это используется Py_GetPath() и некоторыми другими функциями ниже для поиска библиотек Python во время выполнения относительно исполняемого файла интерпретатора. Значение по умолчанию 'python'. Аргумент должен указывать на строку с нулевым завершением из широких символов в статическом хранилище, содержимое которой не будет изменено в течение выполнения программы. Никакой код в интерпретаторе Python не изменит содержимое этого хранилища.

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить строку wchar_t*.

Устарела начиная с версии 3.11.

wchar_t *Py_GetProgramName()

Часть Стабильной ABI.

Возвращает имя программы, заданное с помощью Py_SetProgramName(), или значение по умолчанию. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

wchar_t *Py_GetPrefix()

Часть Стабильной ABI.

Возвращает префикс для установленных платформенно-независимых файлов. Он выводится по множеству сложных правил из имени программы, заданного с помощью Py_SetProgramName() и некоторых переменных окружения; например, если имя программы '/usr/local/bin/python', префикс '/usr/local'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Это соответствует переменной prefix в верхнем уровне Makefile и аргументу --prefix скрипта configure во время компиляции. Значение доступно коду Python как sys.prefix. Полезно только на Unix. Также см. следующую функцию.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

wchar_t *Py_GetExecPrefix()

Часть Стабильной ABI.

Возвращает exec-префикс для установленных платформенно-зависимых файлов. Он выводится по множеству сложных правил из имени программы, заданного с помощью Py_SetProgramName() и некоторых переменных окружения; например, если имя программы '/usr/local/bin/python', exec-префикс '/usr/local'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Это соответствует переменной exec_prefix в верхнем уровне Makefile и аргументу --exec-prefix скрипта configure во время компиляции. Значение доступно коду Python как sys.exec_prefix. Полезно только на Unix.

Предыстория: exec-префикс отличается от префикса, когда платформенно-зависимые файлы (например, исполняемые файлы и общие библиотеки) устанавливаются в разных каталогах. В типичной установке платформенно-зависимые файлы могут быть установлены в подкаталоге /usr/local/plat, а платформенно-независимые в /usr/local.

В общем случае платформа - это комбинация семейств аппаратного и программного обеспечения, например, машины Sparc, работающие под ОС Solaris 2.x, считаются одной платформой, но машины Intel, работающие под Solaris 2.x - другой, а машины Intel, работающие под Linux - ещё другой. Разные главные версии одной и той же операционной системы, как правило, также образуют разные платформы. Не-Unix операционные системы - это другая история; стратегии установки на них настолько разные, что префикс и exec-префикс не имеют значения и установлены в пустую строку. Обратите внимание, что скомпилированные файлы байткода Python платформенно-независимы (но не независимы от версии Python, с помощью которой они были скомпилированы!).

Администраторы систем знают, как настроить программы mount или automount для совместного использования /usr/local между платформами, при этом /usr/local/plat является различной файловой системой для каждой платформы.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

wchar_t *Py_GetProgramFullPath()

Часть Стабильной ABI.

Возвращает полное имя программы-интерпретатора Python; это вычисляется как побочный эффект вывода пути поиска модулей из имени программы (заданного Py_SetProgramName() выше). Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как sys.executable.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

wchar_t *Py_GetPath()

Часть Стабильной ABI.

Возвращает стандартный путь поиска модулей; он вычисляется из имени программы (установленного с помощью Py_SetProgramName() выше) и некоторых переменных окружения. Возвращаемая строка состоит из ряда имён каталогов, разделённых символом разделителя, зависящим от платформы. Символ разделителя — ':' на Unix и macOS, ';' на Windows. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять его значение. Список sys.path инициализируется этим значением при запуске интерпретатора; его можно (и обычно это делается) изменять позже, чтобы изменить путь поиска для загрузки модулей.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

void Py_SetPath(const wchar_t*)

Часть Стабильной ABI с версии 3.7.

Этот API сохраняется для обратной совместимости: вместо него следует использовать установку PyConfig.module_search_paths и PyConfig.module_search_paths_set, см. Конфигурация инициализации Python.

Устанавливает стандартный путь поиска модулей. Если эта функция вызвана до Py_Initialize(), тогда Py_GetPath() не будет пытаться вычислить стандартный путь поиска, а вместо этого использует предоставленный. Это полезно, если Python встроен приложением, которое полностью знает расположение всех модулей. Компоненты пути должны быть разделены символом разделителя, зависящим от платформы, который равен ':' на Unix и macOS, ';' на Windows.

Это также приводит к установке sys.executable в полный путь программы (см. Py_GetProgramFullPath()) и к тому, что sys.prefix и sys.exec_prefix будут пустыми. Вызывающему коду нужно самостоятельно изменить их при необходимости после вызова Py_Initialize().

Используйте Py_DecodeLocale() для декодирования строки байтов в строку wchar_*.

Аргумент path копируется внутри, поэтому вызывающий код может освободить его после завершения вызова.

Изменено в версии 3.8: Теперь для sys.executable используется полный путь программы вместо имени программы.

Устарело начиная с версии 3.11.

const char *Py_GetVersion()

Часть Стабильной ABI.

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

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

Первое слово (до первого пробела) — текущая версия Python; первые символы — большая и малая версия, разделённые точкой. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как sys.version.

См. также константу Py_Version.

const char *Py_GetPlatform()

Часть Стабильной ABI.

Возвращает идентификатор платформы для текущей платформы. В Unix он формируется из «официального» названия операционной системы, преобразованного в нижний регистр, и номера основной ревизии; например, для Solaris 2.x, который также известен как SunOS 5.x, значение равно 'sunos5'. На macOS значение 'darwin'. На Windows значение 'win'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как sys.platform.

const char *Py_GetCopyright()

Часть Стабильной ABI.

Возвращает официальную строку авторских прав для текущей версии Python, например

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как sys.copyright.

const char *Py_GetCompiler()

Часть Стабильной ABI.

Возвращает указание компилятора, используемого для построения текущей версии Python, в квадратных скобках, например:

"[GCC 2.7.2.2]"

Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как часть переменной sys.version.

const char *Py_GetBuildInfo()

Часть Стабильной ABI.

Возвращает информацию о номере последовательности и дате и времени создания текущего экземпляра интерпретатора Python, например

"#67, Aug  1 1997, 22:34:28"

Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять её значение. Значение доступно коду Python как часть переменной sys.version.

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)

Часть Стабильного ABI.

Этот API поддерживается для обратной совместимости: для установки PyConfig.argv, PyConfig.parse_argv и PyConfig.safe_path следует использовать вместо него, см. Конфигурация инициализации Python.

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

Если updatepath равно нулю, функция выполняет только это. Если updatepath отлично от нуля, функция также изменяет sys.path согласно следующему алгоритму:

• Если имя существующего скрипта передаётся в argv[0], абсолютный путь к каталогу, где находится скрипт, добавляется в начало sys.path.
• В противном случае (то есть, если argc равно 0 или argv[0] не указывает на существующее имя файла), пустая строка добавляется в начало sys.path, что эквивалентно добавлению текущей рабочей директории (".") в начало.

Используйте Py_DecodeLocale() для декодирования строки байтов в строку wchar_*.

См. также члены PyConfig.orig_argv и PyConfig.argv конфигурации инициализации Python.

Примечание

Рекомендуется, чтобы приложения, которые встраивают интерпретатор Python для целей, отличных от выполнения одного скрипта, передавали 0 в качестве updatepath и сами обновляли sys.path, если это необходимо. См. CVE-2008-5983.

В версиях до 3.1.3 вы можете достичь того же результата, вручную удалив первый элемент sys.path после вызова PySys_SetArgv(), например, используя:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

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

Устарел начиная с версии 3.11.

void PySys_SetArgv(int argc, wchar_t **argv)

Часть Стабильного ABI.

Этот API поддерживается для обратной совместимости: для установки PyConfig.argv и PyConfig.parse_argv следует использовать вместо него, см. Конфигурация инициализации Python.

Эта функция работает как PySys_SetArgvEx() с updatepath, установленным в 1, за исключением случаев, когда интерпретатор python был запущен с -I.

Используйте Py_DecodeLocale() для декодирования строки байтов в строку wchar_*.

См. также члены PyConfig.orig_argv и PyConfig.argv конфигурации инициализации Python.

Изменено в версии 3.4: Значение updatepath зависит от -I.

Устарел начиная с версии 3.11.

void Py_SetPythonHome(const wchar_t *home)

Часть Стабильного ABI.

Этот API поддерживается для обратной совместимости: для установки PyConfig.home следует использовать вместо него, см. Конфигурация инициализации Python.

Устанавливает стандартную директорию «home», то есть расположение стандартных библиотек Python. См. PYTHONHOME для значения строкового аргумента.

Аргумент должен указывать на строку с нулевым завершением в статическом хранилище, содержимое которой не будет изменено в течение выполнения программы. Никакой код в интерпретаторе Python не изменит содержимое этого хранилища.

Используйте Py_DecodeLocale() для декодирования строки байтов в строку wchar_*.

Устарел начиная с версии 3.11.

wchar_t *Py_GetPythonHome()

Часть Стабильного ABI.

Возвращает значение по умолчанию «home», то есть значение, установленное предыдущим вызовом Py_SetPythonHome(), или значение переменной среды PYTHONHOME, если она установлена.

Эта функция не должна вызываться до Py_Initialize(), в противном случае она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL при вызове до Py_Initialize().

Состояние потока и глобальная блокировка интерпретатора

Интерпретатор Python не полностью потокобезопасен. Для поддержки многопоточных программ Python существует глобальная блокировка, называемая глобальной блокировкой интерпретатора или GIL, которую должен удерживать текущий поток, прежде чем он сможет безопасно получить доступ к объектам Python. Без блокировки даже простейшие операции могут вызвать проблемы в многопоточной программе: например, когда два потока одновременно увеличивают счетчик ссылок одного и того же объекта, счетчик ссылок может оказаться увеличенным только один раз вместо двух.

Поэтому существует правило, что только тот поток, который получил GIL, может оперировать объектами Python или вызывать функции Python/C API. Для эмуляции конкуретности выполнения интерпретатор регулярно пытается переключать потоки (см. sys.setswitchinterval()). Блокировка также снимается вокруг потенциально блокирующих операций ввода-вывода, таких как чтение или запись файла, чтобы другие потоки Python могли работать тем временем.

Интерпретатор Python хранит некоторые данные, специфичные для потока, в структуре данных, называемой PyThreadState. Также существует одна глобальная переменная, указывающая на текущее PyThreadState: её можно получить, используя PyThreadState_Get().

Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);

Поддержка под-интерпретаторов

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

«Главный» интерпретатор — это первый, созданный при инициализации среды выполнения. Обычно это единственный интерпретатор Python в процессе. В отличие от под-интерпретаторов, главный интерпретатор имеет уникальные обязанности, относящиеся ко всему процессу, такие как обработка сигналов. Он также отвечает за выполнение во время инициализации среды выполнения и обычно является активным интерпретатором во время завершения среды выполнения. Функция PyInterpreterState_Main() возвращает указатель на его состояние.

Вы можете переключаться между под-интерпретаторами, используя функцию PyThreadState_Swap(). Вы можете создавать и уничтожать их, используя следующие функции:

type PyInterpreterConfig

Структура, содержащая большинство параметров для настройки под-интерпретатора. Ее значения используются только в Py_NewInterpreterFromConfig() и никогда не изменяются средой выполнения.

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

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

int use_main_obmalloc

Если это 0, то под-интерпретатор будет использовать свое собственное состояние «объектного» аллокатора. В противном случае он будет использовать (совместно) аллокатор главного интерпретатора.

Если это 0, то check_multi_interp_extensions должно быть 1 (ненулевым). Если это 1, то gil не должно быть PyInterpreterConfig_OWN_GIL.

int allow_fork

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

Обратите внимание, что модуль subprocess по-прежнему работает, когда разветвление запрещено.

int allow_exec

Если это 0, то среда выполнения не будет поддерживать замену текущего процесса с помощью exec (например, os.execv()) ни в одном потоке, где в данный момент активен под-интерпретатор. В противном случае замена exec не ограничена.

Обратите внимание, что модуль subprocess по-прежнему работает, когда замена exec запрещена.

int allow_threads

Если это 0, то модуль threading под-интерпретатора не будет создавать потоки. В противном случае потоки разрешены.

int allow_daemon_threads

Если это 0, то модуль threading под-интерпретатора не будет создавать демонические потоки. В противном случае демонические потоки разрешены (если allow_threads не равно нулю).

int check_multi_interp_extensions

Если это 0, то все модули расширения могут быть импортированы, включая устаревшие (инициализация в одной фазе) модули, в любом потоке, где в данный момент активен под-интерпретатор. В противном случае могут быть импортированы только модули расширения с инициализацией в многофазном режиме (см. PEP 489) (также см. Py_mod_multiple_interpreters).

Это должно быть 1 (ненулевым), если use_main_obmalloc равно 0.

int gil

Это определяет работу GIL для под-интерпретатора. Может быть одним из следующих:

PyInterpreterConfig_DEFAULT_GIL

Использование стандартного выбора (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL

Использование (совместное использование) GIL главного интерпретатора.

PyInterpreterConfig_OWN_GIL

Использование собственного GIL под-интерпретатора.

Если это PyInterpreterConfig_OWN_GIL, то PyInterpreterConfig.use_main_obmalloc должно быть 0.

PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)

Создать новый под-интерпретатор. Это (почти) полностью отделённая среда для выполнения кода Python. В частности, у нового интерпретатора есть отдельные, независимые версии всех импортированных модулей, включая фундаментальные модули builtins, __main__ и sys. Таблица загруженных модулей (sys.modules) и путь поиска модулей (sys.path) также отделены. Новая среда не имеет переменной sys.argv. Она имеет новые стандартные потоковые файлы ввода/вывода sys.stdin, sys.stdout и sys.stderr (хотя они ссылаются на те же базовые дескрипторы файлов).

Указанный config управляет опциями, с помощью которых инициализируется интерпретатор.

При успехе tstate_p будет установлен на первое состояние потока, созданное в новом под-интерпретаторе. Это состояние потока создаётся в текущем состоянии потока. Обратите внимание, что фактически ни один поток не создаётся; см. обсуждение состояний потоков ниже. Если создание нового интерпретатора не удалось, tstate_p устанавливается в NULL; исключение не устанавливается, так как состояние исключения хранится в текущем состоянии потока, и может быть нет текущего состояния потока.

Как и все другие функции API Python/C, перед вызовом этой функции должен быть захвачен глобальный замок интерпретатора, и он всё ещё захвачен, когда функция возвращает управление. Аналогично, текущее состояние потока должно быть установлено при входе. При успехе возвращённое состояние потока будет установлено как текущее. Если под-интерпретатор создаётся со своим собственным блокировкой GIL, то блокировка GIL вызывающего интерпретатора будет освобождена. Когда функция возвращает управление, блокировка GIL нового интерпретатора будет удерживаться текущим потоком, а блокировка GIL предыдущего интерпретатора останется освобождённой здесь.

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

Под-интерпретаторы наиболее эффективны, когда изолированы друг от друга, с ограничениями на определённые функции:

PyInterpreterConfig config = {
    .use_main_obmalloc = 0,
    .allow_fork = 0,
    .allow_exec = 0,
    .allow_threads = 1,
    .allow_daemon_threads = 0,
    .check_multi_interp_extensions = 1,
    .gil = PyInterpreterConfig_OWN_GIL,
};
PyThreadState *tstate = Py_NewInterpreterFromConfig(&config);

Обратите внимание, что конфигурация используется только кратковременно и не модифицируется. Во время инициализации значения конфигурации преобразуются в различные значения PyInterpreterState. Читать-только копия конфигурации может быть сохранена внутри PyInterpreterState.

Модули расширений совместно используются между (под-)интерпретаторами следующим образом:

• Для модулей, использующих многофазную инициализацию, например PyModule_FromDefAndSpec(), для каждого интерпретатора создаётся и инициализируется отдельный объект модуля. Только переменные уровня C и глобальные переменные совместно используются между этими объектами модулей.

• Для модулей, использующих однофазную инициализацию, например PyModule_Create(), в первый раз, когда определённое расширение импортируется, оно инициализируется обычно, и (поверхностная) копия словаря модуля скрывается. Когда то же самое расширение импортируется другим (под-)интерпретатором, инициализируется новый модуль и заполняется содержимым этой копии; функция расширения init не вызывается. Таким образом, объекты в словаре модуля в итоге разделяются между (под-)интерпретаторами, что может вызвать нежелательное поведение (см. Проблемы и замечания ниже).

  Обратите внимание, что это отличается от того, что происходит, когда расширение импортируется после того, как интерпретатор был полностью повторно инициализирован вызовом Py_FinalizeEx() и Py_Initialize(); в этом случае функция расширения initmodule вызывается снова. Как и при многофазной инициализации, это означает, что только переменные уровня C и глобальные переменные совместно используются между этими модулями.

PyThreadState *Py_NewInterpreter(void)

Часть Стабильной ABI.

Создать новый под-интерпретатор. Это по существу просто оболочка вокруг Py_NewInterpreterFromConfig() с конфигурацией, сохраняющей существующее поведение. Результатом является под-интерпретатор без изоляции, который разделяет GIL основного интерпретатора, допускает fork/exec, позволяет демоническим потокам и разрешает модули с однофазной инициализацией.

void Py_EndInterpreter(PyThreadState *tstate)

Часть Стабильной ABI.

Уничтожить (под-)интерпретатор, представленный данным состоянием потока. Данное состояние потока должно быть текущим состоянием потока. См. обсуждение состояний потоков ниже. После возврата вызова, текущее состояние потока NULL. Все состояния потоков, связанные с этим интерпретатором, уничтожаются. Глобальный замок интерпретатора, используемый целевым интерпретатором, должен быть захвачен перед вызовом этой функции. Никакая блокировка GIL не удерживается при возврате.

Py_FinalizeEx() уничтожит все под-интерпретаторы, которые не были явно уничтожены на этом этапе.

Асинхронные уведомления

Предоставляется механизм для асинхронных уведомлений в основной поток интерпретатора. Эти уведомления принимают вид указателя на функцию и аргумента типа указатель на void.

int Py_AddPendingCall(int (*func)(void*), void *arg)

Часть Стабильной ABI.

Расписание функции для вызова из основного потока интерпретатора. В случае успеха, возвращается 0, и func помещается в очередь для вызова в главном потоке. В случае неудачи возвращается -1, без установки каких-либо исключений.

После успешного добавления в очередь, func будет в конечном итоге вызвана из основного потока интерпретатора с аргументом arg. Она будет вызвана асинхронно по отношению к обычно выполняемому Python-коду, но при соблюдении следующих условий:

• на границе байт-кода;
• с основным потоком, удерживающим глобальную блокировку интерпретатора (func может, следовательно, использовать весь C API).

func должна возвращать 0 в случае успеха или -1 в случае неудачи с установленным исключением. func не будет прерываться для выполнения другого асинхронного уведомления рекурсивно, но она может быть прервана для переключения потоков, если глобальная блокировка интерпретатора освобождается.

Для выполнения этой функции не требуется текущее состояние потока, и не требуется глобальная блокировка интерпретатора.

Чтобы вызвать эту функцию в подинтерпретаторе, вызывающий поток должен удерживать GIL. В противном случае функция func может быть запланирована для вызова из неправильного интерпретатора.

Предупреждение

Это функция низкого уровня, полезная только в очень особых случаях. Нет гарантии, что func будет вызвана как можно быстрее. Если основной поток занят выполнением системного вызова, func не будет вызвана до возврата системного вызова. Эта функция, как правило, не подходит для вызова Python-кода из произвольных C-потоков. Вместо этого используйте API PyGILState.

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

Изменено в версии 3.9: Если эта функция вызывается в подинтерпретаторе, функция func теперь планируется для вызова из подинтерпретатора, а не из основного интерпретатора. Каждый подинтерпретатор теперь имеет свой собственный список запланированных вызовов.

Профилирование и отслеживание

Интерпретатор Python предоставляет некоторую низкоуровневую поддержку для подключения средств профилирования и отслеживания выполнения. Они используются для профилирования, отладки и анализа покрытия.

Этот C-интерфейс позволяет коду профилирования или отслеживания избежать накладных расходов при вызове через вызываемые объекты на уровне Python, вместо этого выполняя прямой вызов C-функции. Основные атрибуты средства не изменились; интерфейс позволяет устанавливать функции отслеживания на каждый поток, и основные события, сообщаемые функции отслеживания, такие же, как и те, что сообщались функциям отслеживания на уровне Python в предыдущих версиях.

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

Тип функции отслеживания, зарегистрированной с помощью PyEval_SetProfile() и PyEval_SetTrace(). Первый параметр — объект, переданный функции регистрации как obj, frame — объект фрейма, к которому относится событие, what — одна из констант PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN или PyTrace_OPCODE, а arg зависит от значения what:

Значение what	Значение arg
PyTrace_CALL	Всегда Py_None.
PyTrace_EXCEPTION	Информация об исключении, возвращаемая sys.exc_info().
PyTrace_LINE	Всегда Py_None.
PyTrace_RETURN	Возвращаемое значение вызывающей стороне, или NULL если произошла ошибка.
PyTrace_C_CALL	Объект функции, который вызывается.
PyTrace_C_EXCEPTION	Объект функции, который вызывается.
PyTrace_C_RETURN	Объект функции, который вызывается.
PyTrace_OPCODE	Всегда Py_None.

int PyTrace_CALL

Значение параметра what для функции Py_tracefunc при сообщении о новом вызове функции или метода, или новом входе в генератор. Обратите внимание, что создание итератора для функции генератора не сообщается, так как нет передачи управления в байт-код Python в соответствующем фрейме.

int PyTrace_EXCEPTION

Значение параметра what для функции Py_tracefunc при возникновении исключения. Функция обратного вызова вызывается с этим значением для what после обработки любого байт-кода, после чего исключение устанавливается в выполняемом фрейме. В результате, при разворачивании стека Python из-за распространения исключения, функция обратного вызова вызывается по возвращении в каждый фрейм по мере распространения исключения. Только функции отслеживания получают эти события; они не нужны профилеру.

int PyTrace_LINE

Значение, передаваемое в качестве параметра what функции Py_tracefunc (но не функции профилирования) при сообщении о событии номера строки. Он может быть отключен для фрейма путем установки f_trace_lines в 0 в этом фрейме.

int PyTrace_RETURN

Значение для параметра what функций Py_tracefunc при приближении к возвращению из вызова.

int PyTrace_C_CALL

Значение для параметра what функций Py_tracefunc при вызове C-функции.

int PyTrace_C_EXCEPTION

Значение для параметра what функций Py_tracefunc при возникновении исключения в C-функции.

int PyTrace_C_RETURN

Значение для параметра what функций Py_tracefunc при возвращении из C-функции.

int PyTrace_OPCODE

Значение для параметра what функций Py_tracefunc (но не функций профилирования) при выполнении нового кода операции. Это событие по умолчанию не генерируется: оно должно быть явно запрошено путем установки f_trace_opcodes в 1 в фрейме.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Установить функцию профилирования на func. Параметр obj передается функции как первый параметр и может быть любым объектом Python или NULL. Если функции профилирования нужно сохранять состояние, использование различных значений obj для каждого потока предоставляет удобное и безопасное место для его хранения. Функция профилирования вызывается для всех отслеживаемых событий, кроме PyTrace_LINE PyTrace_OPCODE и PyTrace_EXCEPTION.

См. также функцию sys.setprofile().

Вызывающая сторона должна удерживать GIL.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

Аналогично PyEval_SetProfile(), но устанавливает функцию профилирования во всех запущенных потоках, принадлежащих текущему интерпретатору, а не только в текущем потоке.

Вызывающая сторона должна удерживать GIL.

Как и в PyEval_SetProfile(), эта функция игнорирует любые исключения, возникающие при установке функций профилирования во всех потоках.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Установить функцию отслеживания на func. Это аналогично PyEval_SetProfile(), за исключением того, что функция отслеживания получает события номера строки и события на коде операции, но не получает событий, связанных с вызовом C-функций. Любая функция отслеживания, зарегистрированная с помощью PyEval_SetTrace(), не получит PyTrace_C_CALL, PyTrace_C_EXCEPTION или PyTrace_C_RETURN в качестве значения параметра what.

См. также функцию sys.settrace().

Вызывающая сторона должна удерживать GIL.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

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

Вызывающий код должен удерживать GIL.

Как и PyEval_SetTrace(), эта функция игнорирует любые исключения, возникающие при установке функций отслеживания во всех потоках.

Поддержка расширенных отладчиков

Эти функции предназначены только для использования расширенными инструментами отладки.

PyInterpreterState *PyInterpreterState_Head()

Возвращает объект состояния интерпретатора в начале списка всех таких объектов.

PyInterpreterState *PyInterpreterState_Main()

Возвращает основной объект состояния интерпретатора.

PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)

Возвращает объект состояния интерпретатора, следующий за interp в списке всех таких объектов.

PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)

Возвращает указатель на первый объект PyThreadState в списке потоков, связанных с интерпретатором interp.

PyThreadState *PyThreadState_Next(PyThreadState *tstate)

Возвращает объект состояния потока, следующий за tstate в списке всех таких объектов, принадлежащих одному и тому же объекту PyInterpreterState.

Поддержка локального хранения данных потоков

Интерпретатор Python предоставляет низкоуровневую поддержку локального хранения данных потоков (TLS), которая оборачивает базовую реализацию native TLS для поддержки API локального хранения данных на уровне Python (threading.local). API C-уровня CPython подобны тем, которые предлагаются pthreads и Windows: используются ключи потоков и функции для связывания значения void* с каждым потоком.

При вызове этих функций не требуется удерживать GIL; они обеспечивают собственную блокировку.

Обратите внимание, что Python.h не включает объявление API TLS, вам необходимо включить pythread.h для использования локального хранения данных потоков.