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

Перед инициализацией 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

Выводит предупреждение при сравнении 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 не содержит ни директорию скрипта, ни директорию site-packages пользователя.

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

Введено в версии 3.4.

int Py_LegacyWindowsFSEncodingFlag

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

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

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

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

int Py_LegacyWindowsStdioFlag

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

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

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

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

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

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

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

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

Примечание

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

void Py_InitializeEx(int initsigs)

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

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

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()). Обычно возвращает 0. Если во время завершения произошли ошибки (вывод буферизованных данных), возвращает -1.

Эта функция предоставляется по нескольким причинам. Приложение, встраивающее интерпретатор, может перезапустить 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_*.

Устарело начиная с версии 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-prefix для установленных файлов, зависящих от платформы. Он выводится по ряду сложных правил из имени программы, установленного с помощью Py_SetProgramName(), и некоторых переменных среды; например, если имя программы — '/usr/local/bin/python', exec-prefix — '/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()

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

PyThreadState *Py_NewInterpreter()

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

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

Значение возврата указывает на первый созданный поток состояния в новом дочернем интерпретаторе. Это состояние потока создается в текущем состоянии потока. Обратите внимание, что фактически поток не создается; см. обсуждение состояний потоков ниже. Если создание нового интерпретатора не удалось, возвращается NULL; исключение не устанавливается, так как состояние исключения хранится в текущем состоянии потока, и может не быть текущего состояния потока. (Как и все другие функции API Python/C, глобальная блокировка интерпретатора должна быть заблокирована перед вызовом этой функции и все еще заблокирована при ее возвращении; однако, в отличие от большинства других функций API Python/C, при входе не обязательно должно быть текущее состояние потока.)

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

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

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

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

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, таким образом, может использовать весь API C).

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

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

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

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

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

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

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

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

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

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

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