Инициализация, финализация и потоки

До инициализации Python

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

До инициализации 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.

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

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

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

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

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

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

Примечание

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

void Py_InitializeEx(int initsigs)

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

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

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

int Py_IsInitialized()

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

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

int Py_FinalizeEx()

Часть Стабильного ABI начиная с версии 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()

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

Это обратно совместимая версия 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_t*.

См. также элементы 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_t*.

См. также элементы 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_t*.

Устарело с версии 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

Это значение определяет работу ГИЛ субинтерпретатора. Оно может принимать одно из следующих значений:

PyInterpreterConfig_DEFAULT_GIL

Использовать значение по умолчанию (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL

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

PyInterpreterConfig_OWN_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; исключение не устанавливается, поскольку состояние исключения хранится в текущем состоянии потока, а текущего состояния потока может не быть.

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

Добавлено в версии 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 = NULL;
PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

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

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

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

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

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

PyThreadState *Py_NewInterpreter(void)

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

Создаёт новый субинтерпретатор. По сути, это просто обёртка над Py_NewInterpreterFromConfig() с конфигурацией, сохраняющей прежнее поведение. В результате создаётся неизолированный субинтерпретатор, который использует общий с основным интерпретатором ГИЛ, разрешает fork/exec, разрешает потоки-демоны и модули с однофазной инициализацией.

void Py_EndInterpreter(PyThreadState *tstate)

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

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

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 не прерывается для рекурсивного выполнения другого асинхронного уведомления, но может прерываться для переключения потоков, если глобальная блокировка интерпретатора освобождена.

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

Чтобы вызвать эту функцию в субинтерпретаторе, вызывающий код должен удерживать ГИЛ. В противном случае функция 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 (но не функций профилирования), когда собираются выполнить новую инструкцию. По умолчанию это событие не генерируется: его необходимо явно запросить, установив для кадра значение 1 в f_trace_opcodes.

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), обёртывающую базовую реализацию TLS платформы для поддержки API локального хранилища потоков уровня Python (threading.local). API уровня C в CPython похожи на API pthreads и Windows: используйте ключ потока и функции для связывания значения void* с каждым потоком.

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

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