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

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

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

Следующие функции могут быть безопасно вызваны до инициализации 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 есть переменные для глобальной конфигурации, которые управляют различными функциями и опциями. По умолчанию эти флаги управляются значением command line options.

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

int Py_BytesWarningFlag¶

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

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

int Py_DebugFlag¶

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

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

int Py_DontWriteBytecodeFlag¶

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

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

int Py_FrozenFlag¶

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

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

int Py_HashRandomizationFlag¶

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

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

int Py_IgnoreEnvironmentFlag¶

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

Устанавливается с помощью параметров -E и -I.

int Py_InspectFlag¶

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

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

int Py_InteractiveFlag¶

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

int Py_IsolatedFlag¶

Запустите Python в изолированном режиме. В изолированном режиме sys.path не содержит ни каталога скрипта, ни каталога пользовательских пакетов сайта.

Устанавливается с помощью параметра -I.

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

int Py_LegacyWindowsFSEncodingFlag¶

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

Присваивается значение 1, если переменной окружения PYTHONLEGACYWINDOWSFSENCODING присвоено значение непустой строки.

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

Availability: Окна.

int Py_LegacyWindowsStdioFlag¶

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

Присваивается значение 1, если переменной окружения PYTHONLEGACYWINDOWSSTDIO присвоено значение непустой строки.

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

Availability: Окна.

int Py_NoSiteFlag¶

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

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

int Py_NoUserSiteDirectory¶

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

Устанавливается с помощью параметров -s и -I, а также переменной окружения PYTHONNOUSERSITE.

int Py_OptimizeFlag¶

Устанавливается с помощью параметра -O и переменной окружения PYTHONOPTIMIZE.

int Py_QuietFlag¶

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

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

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

int Py_UnbufferedStdioFlag¶

Принудительно отключите буферизацию потоков stdout и stderr.

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

int Py_VerboseFlag¶

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

Устанавливается с помощью параметра -v и переменной окружения PYTHONVERBOSE.

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

void Py_Initialize()¶

Part of the Стабильный ABI.

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

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

Примечание

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

void Py_InitializeEx(int initsigs)¶

Part of the Стабильный ABI.

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

int Py_IsInitialized()¶

Part of the Стабильный ABI.

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

int Py_FinalizeEx()¶

Part of the Стабильный ABI since version 3.6.

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

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

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

Выдает auditing event cpython._PySys_ClearAuditHooks без каких-либо аргументов.

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

void Py_Finalize()¶

Part of the Стабильный ABI.

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

Параметры всего процесса¶

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

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

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

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

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

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

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

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

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

Не рекомендуется, начиная с версии 3.11.

void Py_SetProgramName(const wchar_t *name)¶

Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметр PyConfig.program_name, см. Python Initialization Configuration.

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

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

Не рекомендуется, начиная с версии 3.11.

wchar_t *Py_GetProgramName()¶

Part of the Стабильный ABI.

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

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

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

wchar_t *Py_GetPrefix()¶

Part of the Стабильный 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()¶

Part of the Стабильный ABI.

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

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

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

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

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

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

wchar_t *Py_GetProgramFullPath()¶

Part of the Стабильный ABI.

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

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

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

wchar_t *Py_GetPath()¶

Part of the Стабильный ABI.

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

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

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

void Py_SetPath(const wchar_t*)¶

Part of the Стабильный ABI since version 3.7.

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

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

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

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

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

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

Не рекомендуется, начиная с версии 3.11.

const char *Py_GetVersion()¶

Part of the Стабильный 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()¶

Part of the Стабильный ABI.

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

const char *Py_GetCopyright()¶

Part of the Стабильный ABI.

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

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

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

const char *Py_GetCompiler()¶

Part of the Стабильный ABI.

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

"[GCC 2.7.2.2]"

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

const char *Py_GetBuildInfo()¶

Part of the Стабильный ABI.

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

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

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

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

Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметры PyConfig.argv, PyConfig.parse_argv и PyConfig.safe_path, см. Python Initialization Configuration.

Установите 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 Initialization Configuration.

Примечание

Рекомендуется, чтобы приложения, использующие интерпретатор 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)¶

Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать настройки PyConfig.argv и PyConfig.parse_argv, см. Python Initialization Configuration.

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

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

Смотрите также PyConfig.orig_argv и PyConfig.argv члены группы Python Initialization Configuration.

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

Не рекомендуется, начиная с версии 3.11.

void Py_SetPythonHome(const wchar_t *home)¶

Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметр PyConfig.home, см. Python Initialization Configuration.

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

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

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

Не рекомендуется, начиная с версии 3.11.

wchar_t *Py_GetPythonHome()¶

Part of the Стабильный ABI.

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

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

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

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

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

Следовательно, существует правило, согласно которому только тот поток, который получил GIL, может работать с объектами Python или вызывать функции API Python/C. Чтобы имитировать параллельность выполнения, интерпретатор регулярно пытается переключать потоки (см. 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(). Вы можете создавать и уничтожать их, используя следующие функции:

PyThreadState *Py_NewInterpreter()¶

Part of the Стабильный ABI.

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

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

Дополнительные модули распределяются между (вспомогательными) переводчиками следующим образом:

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

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

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

void Py_EndInterpreter(PyThreadState *tstate)¶

Part of the Стабильный ABI.

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

Также обратите внимание, что объединение этой функциональности с API-интерфейсами является сложной задачей, поскольку эти API-интерфейсы предполагают биекцию между состояниями потоков Python и потоками на уровне операционной системы, что противоречит предположению о наличии вспомогательных интерпретаторов. Настоятельно рекомендуется не переключать вспомогательные интерпретаторы между парой совпадающих вызовов :c и :c . Кроме того, расширения (такие как ), использующие эти API для вызова кода Python из потоков, созданных не на Python, вероятно, будут нарушены при использовании вспомогательных интерпретаторов.¶

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

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

Part of the Стабильный ABI.

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

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

• на границе bytecode;

• с основным потоком, содержащим global interpreter lock (таким образом, func может использовать полный C API).

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

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

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

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

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

Добавлено в версии 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
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 для функции a Py_tracefunc, когда сообщается о новом вызове функции или метода или о новой записи в генераторе. Обратите внимание, что о создании итератора для функции-генератора не сообщается, поскольку в соответствующем фрейме нет передачи управления байт-коду Python.

int PyTrace_EXCEPTION¶

Значение параметра what для функции a Py_tracefunc при возникновении исключения. Функция обратного вызова вызывается с этим значением для what when после обработки любого байт-кода, после чего исключение устанавливается в пределах выполняемого фрейма. Результатом этого является то, что, поскольку распространение исключения приводит к раскручиванию стека 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. Если функции profile необходимо поддерживать состояние, использование другого значения для obj для каждого потока обеспечивает удобное и потокобезопасное место для его хранения. Функция профиля вызывается для всех отслеживаемых событий, за исключением PyTrace_LINE PyTrace_OPCODE и PyTrace_EXCEPTION.

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

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

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.

Расширенная поддержка отладчика¶

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

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

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

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