init.md

1> **Источник:** https://python-all.ru/3.13/c-api/init.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Инициализация, финализация и потоки89Подробнее о том, как настроить интерпретатор до инициализации, см. в [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).1011## Перед инициализацией Python1213В приложении, внедряющем Python, функция [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize) должна быть вызвана до использования любых других функций Python/C API; за исключением нескольких функций и [глобальных переменных конфигурации](https://python-all.ru/3.13/c-api/init.html#global-conf-vars).1415Следующие функции можно безопасно вызывать до инициализации Python:1617- Функции, инициализирующие интерпретатор:1819  - [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize)20  - [`Py_InitializeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeEx)21  - [`Py_InitializeFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeFromConfig)22  - [`Py_BytesMain()`](https://python-all.ru/3.13/c-api/init.html#c.Py_BytesMain)23  - [`Py_Main()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Main)24  - функции предварительной инициализации среды выполнения, описанные в [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config)25- Функции конфигурации:2627  - [`PyImport_AppendInittab()`](https://python-all.ru/3.13/c-api/import.html#c.PyImport_AppendInittab)28  - [`PyImport_ExtendInittab()`](https://python-all.ru/3.13/c-api/import.html#c.PyImport_ExtendInittab)29  - `PyInitFrozenExtensions()`30  - [`PyMem_SetAllocator()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_SetAllocator)31  - [`PyMem_SetupDebugHooks()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_SetupDebugHooks)32  - [`PyObject_SetArenaAllocator()`](https://python-all.ru/3.13/c-api/memory.html#c.PyObject_SetArenaAllocator)33  - [`Py_SetProgramName()`](https://python-all.ru/3.13/c-api/init.html#c.Py_SetProgramName)34  - [`Py_SetPythonHome()`](https://python-all.ru/3.13/c-api/init.html#c.Py_SetPythonHome)35  - [`PySys_ResetWarnOptions()`](https://python-all.ru/3.13/c-api/sys.html#c.PySys_ResetWarnOptions)36  - функции конфигурации, описанные в [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config)37- Информационные функции:3839  - [`Py_IsInitialized()`](https://python-all.ru/3.13/c-api/init.html#c.Py_IsInitialized)40  - [`PyMem_GetAllocator()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_GetAllocator)41  - [`PyObject_GetArenaAllocator()`](https://python-all.ru/3.13/c-api/memory.html#c.PyObject_GetArenaAllocator)42  - [`Py_GetBuildInfo()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetBuildInfo)43  - [`Py_GetCompiler()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetCompiler)44  - [`Py_GetCopyright()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetCopyright)45  - [`Py_GetPlatform()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPlatform)46  - [`Py_GetVersion()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetVersion)47  - [`Py_IsInitialized()`](https://python-all.ru/3.13/c-api/init.html#c.Py_IsInitialized)48- Утилиты:4950  - [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale)51  - функции сообщения о состоянии и утилиты, описанные в [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config)52- Распределители памяти:5354  - [`PyMem_RawMalloc()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_RawMalloc)55  - [`PyMem_RawRealloc()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_RawRealloc)56  - [`PyMem_RawCalloc()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_RawCalloc)57  - [`PyMem_RawFree()`](https://python-all.ru/3.13/c-api/memory.html#c.PyMem_RawFree)58- Синхронизация:5960  - [`PyMutex_Lock()`](https://python-all.ru/3.13/c-api/init.html#c.PyMutex_Lock)61  - [`PyMutex_Unlock()`](https://python-all.ru/3.13/c-api/init.html#c.PyMutex_Unlock)6263> **Примечание**64>65> Несмотря на внешнее сходство с некоторыми из перечисленных выше функций, следующие функции **не должны вызываться** до инициализации интерпретатора: [`Py_EncodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_EncodeLocale), [`Py_GetPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPath), [`Py_GetPrefix()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPrefix), [`Py_GetExecPrefix()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetExecPrefix), [`Py_GetProgramFullPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetProgramFullPath), [`Py_GetPythonHome()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPythonHome), [`Py_GetProgramName()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetProgramName), [`PyEval_InitThreads()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_InitThreads) и [`Py_RunMain()`](https://python-all.ru/3.13/c-api/init.html#c.Py_RunMain).6667## Глобальные переменные конфигурации6869В Python есть переменные глобальной конфигурации, управляющие различными возможностями и настройками. По умолчанию эти флаги задаются [параметрами командной строки](https://python-all.ru/3.13/using/cmdline.html#using-on-interface-options).7071Когда флаг устанавливается через параметр, значение флага равно количеству раз, которое этот параметр был указан. Например, `-b` устанавливает [`Py_BytesWarningFlag`](https://python-all.ru/3.13/c-api/init.html#c.Py_BytesWarningFlag) в 1, а `-bb` устанавливает `Py_BytesWarningFlag` в 2.7273#### `int Py_BytesWarningFlag`7475Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.bytes_warning`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.bytes_warning). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).7677Выдавать предупреждение при сравнении [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray) с [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) или `bytes` с [`int`](https://python-all.ru/3.13/library/functions.html#int). Если значение больше или равно `2`, выдавать ошибку.7879Устанавливается опцией [`-b`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-b).8081Устарело с версии 3.12, будет удалено в версии 3.14.8283#### `int Py_DebugFlag`8485Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.parser_debug`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.parser_debug). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).8687Включает отладочный вывод парсера (только для экспертов, зависит от опций компиляции).8889Устанавливается опцией [`-d`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-d) и переменной окружения [`PYTHONDEBUG`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONDEBUG).9091Устарело с версии 3.12, будет удалено в версии 3.14.9293#### `int Py_DontWriteBytecodeFlag`9495Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.write_bytecode`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.write_bytecode). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).9697Если установлено ненулевое значение, Python не будет пытаться записывать файлы `.pyc` при импорте исходных модулей.9899Устанавливается опцией [`-B`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-B) и переменной окружения [`PYTHONDONTWRITEBYTECODE`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONDONTWRITEBYTECODE).100101Устарело с версии 3.12, будет удалено в версии 3.14.102103#### `int Py_FrozenFlag`104105Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.pathconfig_warnings`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.pathconfig_warnings); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).106107Подавляет сообщения об ошибках при вычислении пути поиска модулей в [`Py_GetPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPath).108109Внутренний флаг, используемый программами `_freeze_module` и `frozenmain`.110111Устарело с версии 3.12, будет удалено в версии 3.14.112113#### `int Py_HashRandomizationFlag`114115Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.hash_seed`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.hash_seed) и [`PyConfig.use_hash_seed`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.use_hash_seed); см. [конфигурацию инициализации Python](https://python-all.ru/3.13/c-api/init_config.html#init-config).116117Устанавливается в `1`, если переменная окружения [`PYTHONHASHSEED`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHASHSEED) установлена в непустую строку.118119Если флаг ненулевой, читает переменную окружения [`PYTHONHASHSEED`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHASHSEED) для инициализации секретного начального значения хеша.120121Устарело с версии 3.12, будет удалено в версии 3.14.122123#### `int Py_IgnoreEnvironmentFlag`124125Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.use_environment`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.use_environment); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).126127Игнорировать все переменные окружения `PYTHON*`, например [`PYTHONPATH`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONPATH) и [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME), которые могли быть установлены.128129Устанавливается параметрами [`-E`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-E) и [`-I`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-I).130131Устарело с версии 3.12, будет удалено в версии 3.14.132133#### `int Py_InspectFlag`134135Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.inspect`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.inspect); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).136137Если скрипт передан первым аргументом или используется параметр [`-c`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-c), после выполнения скрипта или команды перейти в интерактивный режим, даже если [`sys.stdin`](https://python-all.ru/3.13/library/sys.html#sys.stdin) не является терминалом.138139Устанавливается опцией [`-i`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-i) и переменной окружения [`PYTHONINSPECT`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONINSPECT).140141Устарело с версии 3.12, будет удалено в версии 3.14.142143#### `int Py_InteractiveFlag`144145Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.interactive`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.interactive); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).146147Устанавливается опцией [`-i`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-i).148149Устарело с версии 3.12, будет удалено в версии 3.15.150151#### `int Py_IsolatedFlag`152153Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.isolated`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.isolated); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).154155Запуск Python в изолированном режиме. В изолированном режиме [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path) не содержит ни каталог скрипта, ни каталог site-packages пользователя.156157Устанавливается опцией [`-I`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-I).158159Добавлено в версии 3.4.160161Устарело с версии 3.12, будет удалено в версии 3.14.162163#### `int Py_LegacyWindowsFSEncodingFlag`164165Этот API сохранён для обратной совместимости: следует использовать настройку [`PyPreConfig.legacy_windows_fs_encoding`](https://python-all.ru/3.13/c-api/init_config.html#c.PyPreConfig.legacy_windows_fs_encoding); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).166167Если флаг ненулевой, используется кодировка `mbcs` с обработчиком ошибок `replace` вместо кодировки UTF-8 с обработчиком ошибок `surrogatepass` для [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.13/glossary.html#term-filesystem-encoding-and-error-handler).168169Устанавливается в `1`, если переменная окружения [`PYTHONLEGACYWINDOWSFSENCODING`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONLEGACYWINDOWSFSENCODING) установлена в непустую строку.170171См. [**PEP 529**](https://python-all.ru/3.13/c-api/init.html) для подробностей.172173[Доступность](https://python-all.ru/3.13/library/intro.html#availability): Windows.174175Устарело с версии 3.12, будет удалено в версии 3.14.176177#### `int Py_LegacyWindowsStdioFlag`178179Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.legacy_windows_stdio`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.legacy_windows_stdio); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).180181Если флаг ненулевой, используется [`io.FileIO`](https://python-all.ru/3.13/library/io.html#io.FileIO) вместо `io._WindowsConsoleIO` для [`sys`](https://python-all.ru/3.13/library/sys.html#module-sys) стандартных потоков.182183Устанавливается в `1`, если переменная окружения [`PYTHONLEGACYWINDOWSSTDIO`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONLEGACYWINDOWSSTDIO) установлена в непустую строку.184185См. [**PEP 528**](https://python-all.ru/3.13/c-api/init.html) для подробностей.186187[Доступность](https://python-all.ru/3.13/library/intro.html#availability): Windows.188189Устарело с версии 3.12, будет удалено в версии 3.14.190191#### `int Py_NoSiteFlag`192193Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.site_import`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.site_import); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).194195Отключает импорт модуля [`site`](https://python-all.ru/3.13/library/site.html#module-site) и связанные с ним site-зависимые манипуляции с [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path). Также отключает эти манипуляции, если `site` явно импортирован позже (для их выполнения следует вызвать [`site.main()`](https://python-all.ru/3.13/library/site.html#site.main)).196197Устанавливается опцией [`-S`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-S).198199Устарело с версии 3.12, будет удалено в версии 3.14.200201#### `int Py_NoUserSiteDirectory`202203Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.user_site_directory`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.user_site_directory); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).204205Не добавляет [`user site-packages directory`](https://python-all.ru/3.13/library/site.html#site.USER_SITE) в [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path).206207Устанавливается параметрами [`-s`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-s) и [`-I`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-I), а также переменной окружения [`PYTHONNOUSERSITE`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONNOUSERSITE).208209Устарело с версии 3.12, будет удалено в версии 3.14.210211#### `int Py_OptimizeFlag`212213Этот API сохранён для обратной совместимости: следует использовать настройку [`PyConfig.optimization_level`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.optimization_level); см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).214215Устанавливается опцией [`-O`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-O) и переменной окружения [`PYTHONOPTIMIZE`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONOPTIMIZE).216217Устарело с версии 3.12, будет удалено в версии 3.14.218219#### `int Py_QuietFlag`220221Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.quiet`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.quiet). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).222223Не выводить сообщения об авторских правах и версии, даже в интерактивном режиме.224225Устанавливается опцией [`-q`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-q).226227Добавлено в версии 3.2.228229Устарело с версии 3.12, будет удалено в версии 3.14.230231#### `int Py_UnbufferedStdioFlag`232233Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.buffered_stdio`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.buffered_stdio). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).234235Принудительно отключает буферизацию потоков stdout и stderr.236237Устанавливается опцией [`-u`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-u) и переменной окружения [`PYTHONUNBUFFERED`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONUNBUFFERED).238239Устарело с версии 3.12, будет удалено в версии 3.14.240241#### `int Py_VerboseFlag`242243Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.verbose`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.verbose). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).244245Выводит сообщение каждый раз при инициализации модуля, указывая, откуда он загружается (имя файла или встроенный модуль). Если значение больше или равно `2`, выводит сообщение для каждого файла, который проверяется при поиске модуля. Также предоставляет информацию об очистке модулей при завершении работы.246247Устанавливается опцией [`-v`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-v) и переменной окружения [`PYTHONVERBOSE`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONVERBOSE).248249Устарело с версии 3.12, будет удалено в версии 3.14.250251## Инициализация и завершение работы интерпретатора252253#### `void Py_Initialize()`254255*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*256257Инициализирует интерпретатор Python. В приложении, встраивающем Python, эту функцию следует вызывать до использования любых других функций Python/C API; за несколькими исключениями обращайтесь к [Before Python Initialization](https://python-all.ru/3.13/c-api/init.html#pre-init-safe).258259Эта функция инициализирует таблицу загруженных модулей (`sys.modules`) и создаёт фундаментальные модули [`builtins`](https://python-all.ru/3.13/library/builtins.html#module-builtins), [`__main__`](https://python-all.ru/3.13/library/__main__.html#module-__main__) и [`sys`](https://python-all.ru/3.13/library/sys.html#module-sys). Также она инициализирует путь поиска модулей (`sys.path`). Она не устанавливает `sys.argv`; для этого следует использовать API [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config). При повторном вызове (без предварительного вызова [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx)) функция ничего не делает. Возвращаемого значения нет; если инициализация завершается ошибкой, это фатальная ошибка.260261Используйте [`Py_InitializeFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeFromConfig) для настройки [конфигурации инициализации Python](https://python-all.ru/3.13/c-api/init_config.html#init-config).262263> **Примечание**264>265> В Windows изменяет режим консоли с `O_TEXT` на `O_BINARY`, что также влияет на использование консоли не из Python через среду выполнения C.266267#### `void Py_InitializeEx(int initsigs)`268269*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*270271Эта функция работает как [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), если *initsigs* равно `1`. Если *initsigs* равно `0`, она пропускает начальную регистрацию обработчиков сигналов, что может быть полезно, когда CPython встраивается в более крупное приложение.272273Используйте [`Py_InitializeFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeFromConfig) для настройки [конфигурации инициализации Python](https://python-all.ru/3.13/c-api/init_config.html#init-config).274275#### `PyStatus Py_InitializeFromConfig(const PyConfig *config)`276277Инициализирует Python из конфигурации *config*, как описано в [Initialization with PyConfig](https://python-all.ru/3.13/c-api/init_config.html#init-from-config).278279Подробнее о предварительной инициализации интерпретатора, заполнении структуры конфигурации времени выполнения и проверке возвращаемой структуры состояния см. в разделе [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).280281#### `int Py_IsInitialized()`282283*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*284285Возвращает true (ненулевое значение), если интерпретатор Python был инициализирован, и false (ноль), если нет. После вызова [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx) функция возвращает false до тех пор, пока не будет снова вызвана [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).286287#### `int Py_IsFinalizing()`288289*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*290291Возвращает истину (не ноль), если главный интерпретатор Python [завершает работу](https://python-all.ru/3.13/glossary.html#term-interpreter-shutdown). В противном случае возвращает ложь (ноль).292293Добавлено в версии 3.13.294295#### `int Py_FinalizeEx()`296297*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.6.*298299Отменяет всю инициализацию, выполненную с помощью [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), и последующее использование функций Python/C API, а также уничтожает все под-интерпретаторы (см. [`Py_NewInterpreter()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreter) ниже), которые были созданы и ещё не уничтожены после последнего вызова `Py_Initialize()`. В идеале это освобождает всю память, выделенную интерпретатором Python. При повторном вызове (без предварительного вызова `Py_Initialize()` сначала) эта функция ничего не делает.300301Поскольку эта функция является обратной по отношению к [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), её следует вызывать в том же потоке с тем же активным интерпретатором. Это означает главный поток и главный интерпретатор. Никогда не следует вызывать её во время работы [`Py_RunMain()`](https://python-all.ru/3.13/c-api/init.html#c.Py_RunMain).302303Обычно возвращаемое значение – `0`. Если во время завершения (сброса буферизованных данных) произошли ошибки, возвращается `-1`.304305Эта функция предусмотрена по ряду причин. Встраивающее приложение может захотеть перезапустить Python без перезапуска самого приложения. Приложение, загрузившее интерпретатор Python из динамически загружаемой библиотеки (или DLL), может захотеть освободить всю память, выделенную Python, перед выгрузкой DLL. В процессе поиска утечек памяти в приложении разработчик может захотеть освободить всю память, выделенную Python, перед выходом из приложения.306307**Ошибки и предостережения:** Уничтожение модулей и объектов в модулях происходит в случайном порядке; это может привести к сбою деструкторов (методов [`__del__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__del__)), когда они зависят от других объектов (даже функций) или модулей. Динамически загружаемые модули расширений, загруженные Python, не выгружаются. Небольшие объёмы памяти, выделенные интерпретатором Python, могут не освободиться (если вы обнаружили утечку, пожалуйста, сообщите о ней). Память, занятая циклическими ссылками между объектами, не освобождается. Некоторая память, выделенная модулями расширений, может не освободиться. Некоторые расширения могут работать некорректно, если их функция инициализации вызывается более одного раза; это может произойти, если приложение вызывает [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize) и [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx) более одного раза. `Py_FinalizeEx()` не должна вызываться рекурсивно из самой себя. Поэтому она не должна вызываться любым кодом, который может выполняться как часть процесса завершения работы интерпретатора, например обработчиками [`atexit`](https://python-all.ru/3.13/library/atexit.html#module-atexit), финализаторами объектов или любым кодом, который может выполняться при сбросе файлов stdout и stderr.308309Возбуждает [событие аудита](https://python-all.ru/3.13/library/sys.html#auditing) `cpython._PySys_ClearAuditHooks` без аргументов.310311Добавлено в версии 3.6.312313#### `void Py_Finalize()`314315*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*316317Это обратно совместимая версия [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx), которая игнорирует возвращаемое значение.318319#### `int Py_BytesMain(int argc, char **argv)`320321*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) с версии 3.8.*322323Аналогично [`Py_Main()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Main), но *argv* является массивом строк байтов, что позволяет вызывающему приложению делегировать этап декодирования текста среде выполнения CPython.324325Добавлено в версии 3.8.326327#### `int Py_Main(int argc, wchar_t **argv)`328329*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*330331Главная программа стандартного интерпретатора, инкапсулирующая полный цикл инициализации/завершения, а также дополнительное поведение для реализации чтения параметров конфигурации из окружения и командной строки, и затем выполнения `__main__` в соответствии с [командной строкой](https://python-all.ru/3.13/using/cmdline.html#using-on-cmdline).332333Эта функция доступна для программ, которые хотят поддерживать полный интерфейс командной строки CPython, а не просто встраивать среду выполнения Python в более крупное приложение.334335Параметры *argc* и *argv* аналогичны тем, которые передаются функции `main()` программы на C, за исключением того, что элементы *argv* сначала преобразуются в `wchar_t` с помощью [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale). Также важно отметить, что записи списка аргументов могут быть изменены так, чтобы указывать на строки, отличные от переданных (однако содержимое строк, на которые указывает список аргументов, не изменяется).336337Возвращаемое значение – `2`, если список аргументов не представляет собой допустимую командную строку Python, и в противном случае то же, что и [`Py_RunMain()`](https://python-all.ru/3.13/c-api/init.html#c.Py_RunMain).338339С точки зрения API конфигурации среды выполнения CPython, описанных в разделе [runtime configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config) (и без учёта обработки ошибок), `Py_Main` примерно эквивалентно:340341```c342PyConfig config;343PyConfig_InitPythonConfig(&config);344PyConfig_SetArgv(&config, argc, argv);345Py_InitializeFromConfig(&config);346PyConfig_Clear(&config);347348Py_RunMain();349```350351В обычном использовании встраивающее приложение будет вызывать эту функцию *вместо* прямого вызова [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), [`Py_InitializeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeEx) или [`Py_InitializeFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeFromConfig), и все настройки будут применены так, как описано в других разделах этой документации. Если эта функция вызывается *после* предыдущего вызова API инициализации среды выполнения, то то, какие именно настройки окружения и командной строки будут обновлены, зависит от версии (поскольку зависит от того, какие настройки корректно поддерживают изменение после того, как они были установлены один раз при первой инициализации среды выполнения).352353#### `int Py_RunMain(void)`354355Выполняет главный модуль в полностью сконфигурированной среде выполнения CPython.356357Выполняет команду ([`PyConfig.run_command`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.run_command)), скрипт ([`PyConfig.run_filename`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.run_filename)) или модуль ([`PyConfig.run_module`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.run_module)), указанные в командной строке или в конфигурации. Если ни одно из этих значений не задано, запускает интерактивный промпт Python (REPL) с использованием глобального пространства имён модуля `__main__`.358359Если [`PyConfig.inspect`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.inspect) не задан (по умолчанию), возвращаемое значение будет `0`, если интерпретатор завершается нормально (то есть без возбуждения исключения), кодом выхода необработанного [`SystemExit`](https://python-all.ru/3.13/library/exceptions.html#SystemExit), или `1` для любого другого необработанного исключения.360361Если [`PyConfig.inspect`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.inspect) задан (например, когда используется опция [`-i`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-i)), то вместо возврата при завершении интерпретатора выполнение продолжается в интерактивном промпте Python (REPL) с использованием глобального пространства имён модуля `__main__`. Если интерпретатор завершился с исключением, это исключение немедленно возбуждается в сессии REPL. Возвращаемое значение функции затем определяется способом завершения *сессии REPL*: `0`, `1` или статусом [`SystemExit`](https://python-all.ru/3.13/library/exceptions.html#SystemExit), как указано выше.362363Эта функция всегда завершает работу интерпретатора Python перед возвратом.364365См. [Конфигурация Python](https://python-all.ru/3.13/c-api/init_config.html#init-python-config) для примера пользовательской сборки Python, которая всегда работает в изолированном режиме с использованием [`Py_RunMain()`](https://python-all.ru/3.13/c-api/init.html#c.Py_RunMain).366367#### `int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)`368369> *Это [нестабильное API](https://python-all.ru/3.13/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*370371Регистрирует колбэк [`atexit`](https://python-all.ru/3.13/library/atexit.html#module-atexit) для целевого интерпретатора *interp*. Это аналогично [`Py_AtExit()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_AtExit), но принимает явный указатель на интерпретатор и данные для колбэка.372373[GIL](https://python-all.ru/3.13/glossary.html#term-GIL) должна удерживаться для *interp*.374375Добавлено в версии 3.13.376377## Общепроцессные параметры378379#### `void Py_SetProgramName(const wchar_t *name)`380381*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*382383Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).384385Эту функцию следует вызвать до первого вызова [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), если она вообще вызывается. Она сообщает интерпретатору значение аргумента `argv[0]` функции `main()` программы (преобразованное в широкие символы). Это используется [`Py_GetPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPath) и некоторыми другими функциями ниже для поиска библиотек времени выполнения Python относительно исполняемого файла интерпретатора. Значение по умолчанию – `'python'`. Аргумент должен указывать на строку широких символов, завершающуюся нулём, в статической памяти, содержимое которой не изменится за время выполнения программы. Никакой код в интерпретаторе Python не изменит содержимое этой памяти.386387Используйте [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale) для декодирования строки байтов, чтобы получить строку wchar\_t\*.388389Устарело с версии 3.11.390391#### `wchar_t *Py_GetProgramName()`392393*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*394395Возвращает имя программы, установленное с помощью [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name), или значение по умолчанию. Возвращаемая строка указывает на статическую память; вызывающий не должен изменять её значение.396397Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.398399Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).400401Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте [`sys.executable`](https://python-all.ru/3.13/library/sys.html#sys.executable).402403#### `wchar_t *Py_GetPrefix()`404405*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*406407Возвращает *префикс* для установленных платформонезависимых файлов. Он определяется по ряду сложных правил из имени программы, установленного с помощью [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name), и некоторых переменных окружения; например, если имя программы – `'/usr/local/bin/python'`, префикс – `'/usr/local'`. Возвращаемая строка указывает на статическую память; вызывающий не должен изменять её значение. Это соответствует переменной **prefix** в корневом `Makefile` и аргументу [`--prefix`](https://python-all.ru/3.13/using/configure.html#cmdoption-prefix) сценария **configure** во время сборки. Значение доступно в коде Python как `sys.base_prefix`. Полезен только в Unix. Смотрите также следующую функцию.408409Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.410411Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).412413Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте [`sys.base_prefix`](https://python-all.ru/3.13/library/sys.html#sys.base_prefix), или [`sys.prefix`](https://python-all.ru/3.13/library/sys.html#sys.prefix), если нужно обрабатывать [виртуальные окружения](https://python-all.ru/3.13/library/venv.html#venv-def).414415#### `wchar_t *Py_GetExecPrefix()`416417*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*418419Возвращает *exec-prefix* для установленных *зависящих от платформы* файлов. Значение вычисляется по ряду сложных правил на основе имени программы, заданного с помощью [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name), и некоторых переменных окружения; например, если имя программы – `'/usr/local/bin/python'`, то exec-prefix будет `'/usr/local'`. Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Это соответствует переменной **exec\_prefix** в `Makefile` и аргументу `--exec-prefix` скрипта **configure** на этапе сборки. Значение доступно в коде Python как `sys.base_exec_prefix`. Это имеет смысл только в Unix.420421Контекст: exec-prefix отличается от префикса (prefix), когда зависящие от платформы файлы (например, исполняемые файлы и динамические библиотеки) устанавливаются в другое дерево каталогов. В типичной установке платформенно-зависимые файлы могут быть установлены в поддерево `/usr/local/plat`, а платформенно-независимые – в `/usr/local`.422423Вообще говоря, платформа – это комбинация семейств аппаратного и программного обеспечения; например, машины Sparc под управлением ОС Solaris 2.x считаются одной платформой, машины Intel под Solaris 2.x – другой, а машины Intel под Linux – третьей. Разные основные версии одной и той же ОС обычно также образуют разные платформы. Операционные системы, отличные от Unix, – это отдельная история; стратегии установки на этих системах настолько различаются, что префикс и exec-prefix не имеют смысла и устанавливаются в пустую строку. Обратите внимание: скомпилированные файлы байт-кода Python не зависят от платформы (но не от версии Python, под которой они были скомпилированы!).424425Системные администраторы знают, как настроить программы **mount** или **automount** для совместного использования `/usr/local` между платформами, при этом `/usr/local/plat` будет отдельной файловой системой для каждой платформы.426427Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.428429Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).430431Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте [`sys.base_exec_prefix`](https://python-all.ru/3.13/library/sys.html#sys.base_exec_prefix), или [`sys.exec_prefix`](https://python-all.ru/3.13/library/sys.html#sys.exec_prefix), если нужно обрабатывать [виртуальные окружения](https://python-all.ru/3.13/library/venv.html#venv-def).432433#### `wchar_t *Py_GetProgramFullPath()`434435*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*436437Возвращает полное имя программы исполняемого файла Python; оно вычисляется как побочный эффект при получении пути поиска модулей по умолчанию из имени программы (заданного с помощью [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name)). Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Значение доступно в коде Python как `sys.executable`.438439Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.440441Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).442443Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте [`sys.executable`](https://python-all.ru/3.13/library/sys.html#sys.executable).444445#### `wchar_t *Py_GetPath()`446447*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*448449Возвращает путь поиска модулей по умолчанию; он вычисляется из имени программы (заданного с помощью [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name)) и некоторых переменных окружения. Возвращаемая строка состоит из последовательности имён каталогов, разделённых символом-разделителем, зависящим от платформы. Символ-разделитель – `':'` в Unix и macOS, `';'` в Windows. Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Список [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path) инициализируется этим значением при запуске интерпретатора; позже его можно (и обычно так и делается) изменить для настройки пути поиска модулей.450451Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.452453Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).454455Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path).456457#### `const char *Py_GetVersion()`458459*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*460461Возвращает версию данного интерпретатора Python. Это строка, которая выглядит примерно так:462463```c464"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"465```466467Первое слово (до первого пробела) – это текущая версия Python; первые символы – это мажорная и минорная версии, разделённые точкой. Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Это значение доступно в коде Python как [`sys.version`](https://python-all.ru/3.13/library/sys.html#sys.version).468469Смотрите также константу [`Py_Version`](https://python-all.ru/3.13/c-api/apiabiversion.html#c.Py_Version).470471#### `const char *Py_GetPlatform()`472473*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*474475Возвращает идентификатор платформы для текущей платформы. В Unix он формируется из «официального» имени операционной системы, преобразованного в нижний регистр, за которым следует номер основной ревизии; например, для Solaris 2.x, также известного как SunOS 5.x, значение – `'sunos5'`. В macOS – `'darwin'`. В Windows – `'win'`. Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Значение доступно в коде Python как `sys.platform`.476477#### `const char *Py_GetCopyright()`478479*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*480481Возвращает официальную строку авторских прав для текущей версии Python, например482483`'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'`484485Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Значение доступно в коде Python как `sys.copyright`.486487#### `const char *Py_GetCompiler()`488489*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*490491Возвращает указание компилятора, использованного для сборки текущей версии Python, в квадратных скобках, например:492493```c494"[GCC 2.7.2.2]"495```496497Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Значение доступно коду Python как часть переменной `sys.version`.498499#### `const char *Py_GetBuildInfo()`500501*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*502503Возвращает информацию о номере сборки, дате и времени сборки текущего экземпляра интерпретатора Python, например504505```c506"#67, Aug  1 1997, 22:34:28"507```508509Возвращаемая строка указывает на статическую память; вызывающий код не должен изменять её значение. Значение доступно коду Python как часть переменной `sys.version`.510511#### `void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)`512513*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*514515Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.argv), [`PyConfig.parse_argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.parse_argv) и [`PyConfig.safe_path`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.safe_path). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).516517Устанавливает [`sys.argv`](https://python-all.ru/3.13/library/sys.html#sys.argv) на основе *argc* и *argv*. Эти параметры похожи на передаваемые функции `main()` программы, с тем отличием, что первый элемент должен указывать на исполняемый файл сценария, а не на исполняемый файл, в котором работает интерпретатор Python. Если запускаемый сценарий отсутствует, первый элемент в *argv* может быть пустой строкой. Если этой функции не удаётся инициализировать `sys.argv`, фатальная ситуация сигнализируется с помощью [`Py_FatalError()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_FatalError).518519Если *updatepath* равен нулю, на этом работа функции заканчивается. Если *updatepath* не равен нулю, функция также изменяет [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path) по следующему алгоритму:520521- Если в `argv[0]` передано имя существующего сценария, то абсолютный путь к каталогу, в котором находится сценарий, добавляется в начало [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path).522- В противном случае (то есть если *argc* равен `0` или `argv[0]` не указывает на существующее имя файла), пустая строка добавляется в начало [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path), что эквивалентно добавлению текущего рабочего каталога (`"."`).523524Используйте [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale) для декодирования строки байтов, чтобы получить строку wchar\_t\*.525526См. также члены [`PyConfig.orig_argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.orig_argv) и [`PyConfig.argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.argv) структуры [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).527528> **Примечание**529>530> Приложениям, встраивающим интерпретатор Python не для выполнения одного сценария, рекомендуется передавать `0` в качестве *updatepath* и при желании обновлять [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path) самостоятельно. См. [**CVE 2008-5983**](https://python-all.ru/3.13/c-api/init.html).531>532> В версиях до 3.1.3 того же эффекта можно достичь, вручную удалив первый элемент [`sys.path`](https://python-all.ru/3.13/library/sys.html#sys.path) после вызова [`PySys_SetArgv()`](https://python-all.ru/3.13/c-api/init.html#c.PySys_SetArgv), например используя:533>534> ```c535> PyRun_SimpleString("import sys; sys.path.pop(0)\n");536> ```537538Добавлено в версии 3.1.3.539540Устарело с версии 3.11.541542#### `void PySys_SetArgv(int argc, wchar_t **argv)`543544*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*545546Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.argv) и [`PyConfig.parse_argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.parse_argv). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).547548Эта функция работает как [`PySys_SetArgvEx()`](https://python-all.ru/3.13/c-api/init.html#c.PySys_SetArgvEx) с *updatepath*, установленным в `1`, если только интерпретатор **python** не был запущен с [`-I`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-I).549550Используйте [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale) для декодирования строки байтов, чтобы получить строку wchar\_t\*.551552См. также члены [`PyConfig.orig_argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.orig_argv) и [`PyConfig.argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.argv) структуры [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).553554Изменено в версии 3.4: Значение *updatepath* зависит от [`-I`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-I).555556Устарело с версии 3.11.557558#### `void Py_SetPythonHome(const wchar_t *home)`559560*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*561562Этот API сохранён для обратной совместимости: вместо него следует использовать [`PyConfig.home`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.home). См. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).563564Устанавливает домашний каталог по умолчанию, то есть расположение стандартных библиотек Python. См. [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME) для пояснения значения строки аргумента.565566Аргумент должен указывать на строку символов, завершающуюся нулём, в статической памяти, содержимое которой не будет изменяться в течение всего времени выполнения программы. Никакой код в интерпретаторе Python не будет менять содержимое этой памяти.567568Используйте [`Py_DecodeLocale()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_DecodeLocale) для декодирования строки байтов, чтобы получить строку wchar\_t\*.569570Устарело с версии 3.11.571572#### `wchar_t *Py_GetPythonHome()`573574*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*575576Возвращает «домашний» каталог по умолчанию, то есть значение, установленное с помощью [`PyConfig.home`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.home), или значение переменной окружения [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME), если она задана.577578Эту функцию не следует вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), иначе она возвращает `NULL`.579580Изменено в версии 3.10: Теперь возвращает `NULL`, если вызвано до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).581582Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте переменную окружения [`PyConfig.home`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.home) или [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME).583584## Состояние потока и глобальная блокировка интерпретатора585586Интерпретатор Python не является полностью потокобезопасным. Для поддержки многопоточных программ на Python существует глобальная блокировка, называемая [глобальной блокировкой интерпретатора](https://python-all.ru/3.13/glossary.html#term-global-interpreter-lock) или [GIL](https://python-all.ru/3.13/glossary.html#term-GIL), которую текущий поток должен удерживать перед тем, как безопасно обращаться к объектам Python. Без этой блокировки даже простейшие операции могут вызывать проблемы в многопоточной программе: например, когда два потока одновременно увеличивают счётчик ссылок одного и того же объекта, счётчик может в итоге увеличиться только один раз вместо двух.587588Поэтому существует правило: только поток, захвативший [GIL](https://python-all.ru/3.13/glossary.html#term-GIL), может работать с объектами Python или вызывать функции Python/C API. Для эмуляции параллелизма выполнения интерпретатор регулярно пытается переключать потоки (см. [`sys.setswitchinterval()`](https://python-all.ru/3.13/library/sys.html#sys.setswitchinterval)). Блокировка также освобождается вокруг потенциально блокирующих операций ввода-вывода, таких как чтение или запись файла, чтобы тем временем могли работать другие потоки Python.589590Интерпретатор Python хранит некоторую служебную информацию, специфичную для потока, в структуре данных, называемой [`PyThreadState`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState). Существует также одна глобальная переменная, указывающая на текущий `PyThreadState`: её можно получить с помощью [`PyThreadState_Get()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Get).591592### Освобождение GIL из кода расширения593594Большая часть кода расширения, работающего с [GIL](https://python-all.ru/3.13/glossary.html#term-GIL), имеет следующую простую структуру:595596```c597Save the thread state in a local variable.598Release the global interpreter lock.599... Do some blocking I/O operation ...600Reacquire the global interpreter lock.601Restore the thread state from the local variable.602```603604Это настолько распространено, что существует пара макросов для упрощения:605606```c607Py_BEGIN_ALLOW_THREADS608... Do some blocking I/O operation ...609Py_END_ALLOW_THREADS610```611612Макрос [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS) открывает новый блок и объявляет скрытую локальную переменную; макрос [`Py_END_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS) закрывает блок.613614Приведённый выше блок раскрывается в следующий код:615616```c617PyThreadState *_save;618619_save = PyEval_SaveThread();620... Do some blocking I/O operation ...621PyEval_RestoreThread(_save);622```623624Вот как работают эти функции: глобальная блокировка интерпретатора используется для защиты указателя на текущее состояние потока. При освобождении блокировки и сохранении состояния потока указатель на текущее состояние потока должен быть получен до освобождения блокировки (поскольку другой поток может немедленно захватить блокировку и сохранить своё состояние потока в глобальной переменной). И наоборот, при захвате блокировки и восстановлении состояния потока блокировка должна быть захвачена до сохранения указателя на состояние потока.625626> **Примечание**627>628> Вызов системных функций ввода-вывода – это наиболее распространённый случай освобождения GIL, но он также может быть полезен перед вызовом длительных вычислений, не требующих доступа к объектам Python, таких как функции сжатия или шифрования, работающие с буферами памяти. Например, стандартные модули [`zlib`](https://python-all.ru/3.13/library/zlib.html#module-zlib) и [`hashlib`](https://python-all.ru/3.13/library/hashlib.html#module-hashlib) освобождают GIL при сжатии или хешировании данных.629630### Потоки, созданные не из Python631632Когда потоки создаются с помощью специализированных Python API (например, модуля [`threading`](https://python-all.ru/3.13/library/threading.html#module-threading)), с ними автоматически связывается состояние потока, и приведённый выше код корректен. Однако, когда потоки создаются из C (например, сторонней библиотекой с собственным управлением потоками), они не удерживают GIL и для них не существует структуры состояния потока.633634Если необходимо вызвать код Python из этих потоков (часто это будет частью API колбэков, предоставляемого упомянутой сторонней библиотекой), сначала нужно зарегистрировать эти потоки в интерпретаторе, создав структуру данных состояния потока, затем захватить GIL и, наконец, сохранить указатель на их состояние потока, прежде чем можно будет начать использовать Python/C API. После завершения следует сбросить указатель состояния потока, освободить GIL и освободить структуру данных состояния потока.635636Функции [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) и [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release) делают всё вышеописанное автоматически. Типичный способ вызова Python из потока C:637638```c639PyGILState_STATE gstate;640gstate = PyGILState_Ensure();641642/* Выполнить действия Python здесь. */643result = CallSomeFunction();644/* вычислить результат или обработать исключение */645646/* Освободить поток. После этой точки API Python не допускается. */647PyGILState_Release(gstate);648```649650Обратите внимание, что функции `PyGILState_*` предполагают наличие только одного глобального интерпретатора (создаваемого автоматически с помощью [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize)). Python поддерживает создание дополнительных интерпретаторов (с помощью [`Py_NewInterpreter()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreter)), но смешивание нескольких интерпретаторов и API `PyGILState_*` не поддерживается.651652### Предостережения относительно fork()653654Ещё одна важная особенность потоков – их поведение при вызове C `fork()`. На большинстве систем с `fork()` после fork процесса остаётся только тот поток, который вызвал fork. Это оказывает конкретное влияние как на обработку блокировок, так и на всё сохранённое состояние в среде выполнения CPython.655656Тот факт, что остаётся только «текущий» поток, означает, что любые блокировки, удерживаемые другими потоками, никогда не будут освобождены. Python решает эту проблему для [`os.fork()`](https://python-all.ru/3.13/library/os.html#os.fork), захватывая блокировки, которые он использует внутренне, перед fork и освобождая их после. Кроме того, он сбрасывает все [объекты блокировки](https://python-all.ru/3.13/library/threading.html#lock-objects) в дочернем процессе. При расширении или встраивании Python нет способа сообщить Python о дополнительных (не-Python) блокировках, которые необходимо захватить перед fork или сбросить после него. Для достижения того же эффекта потребуется использовать системные механизмы, такие как `pthread_atfork()`. Кроме того, при расширении или встраивании Python вызов `fork()` напрямую, а не через `os.fork()` (и возврат к вызову Python) может привести к взаимоблокировке из-за того, что одна из внутренних блокировок Python удерживается потоком, который становится недействительным после fork. [`PyOS_AfterFork_Child()`](https://python-all.ru/3.13/c-api/sys.html#c.PyOS_AfterFork_Child) пытается сбросить необходимые блокировки, но не всегда может это сделать.657658Тот факт, что все остальные потоки исчезают, также означает, что состояние среды выполнения CPython должно быть правильно очищено, что и делает [`os.fork()`](https://python-all.ru/3.13/library/os.html#os.fork). Это означает завершение всех остальных объектов [`PyThreadState`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState), принадлежащих текущему интерпретатору, и всех остальных объектов [`PyInterpreterState`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterState). Из-за этого и особой природы [«главного» интерпретатора](https://python-all.ru/3.13/c-api/init.html#sub-interpreter-support), `fork()` следует вызывать только в «главном» потоке этого интерпретатора, где изначально была инициализирована глобальная среда выполнения CPython. Единственное исключение – если `exec()` будет вызван сразу после.659660### Предостережения по поводу финализации среды выполнения661662На позднем этапе [завершения работы интерпретатора](https://python-all.ru/3.13/glossary.html#term-interpreter-shutdown), после попытки дождаться завершения нефоновых потоков (хотя это может быть прервано [`KeyboardInterrupt`](https://python-all.ru/3.13/library/exceptions.html#KeyboardInterrupt)) и выполнения функций [`atexit`](https://python-all.ru/3.13/library/atexit.html#module-atexit), среда выполнения помечается как *финализируемая*: [`Py_IsFinalizing()`](https://python-all.ru/3.13/c-api/init.html#c.Py_IsFinalizing) и [`sys.is_finalizing()`](https://python-all.ru/3.13/library/sys.html#sys.is_finalizing) возвращают true. На этот момент только *поток финализации*, который инициировал финализацию (обычно главный поток), может захватить [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).663664Если какой-либо поток, кроме потока финализации, пытается захватить GIL во время финализации, явно через [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure), [`Py_END_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS), [`PyEval_AcquireThread()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_AcquireThread) или `PyEval_AcquireLock()`, или неявно, когда интерпретатор пытается перезахватить его после того, как отдал, поток переходит в **состояние постоянной блокировки**, в котором остаётся до завершения программы. В большинстве случаев это безвредно, но может привести к взаимоблокировке, если более поздний этап финализации попытается захватить блокировку, принадлежащую заблокированному потоку, или иным образом ожидает заблокированный поток.665666Грубо? Да. Это предотвращает случайные крахи и/или неожиданный пропуск финализаций C++ выше по стеку вызовов, когда такие потоки принудительно завершались здесь в CPython 3.13.7 и более ранних версиях. C API среды выполнения CPython для захвата GIL никогда не имели ожиданий по сообщению об ошибках или их обработке во время захвата GIL, что позволило бы корректно выйти из этой ситуации. Изменение этого потребовало бы новых стабильных C API и переписывания большей части кода C в экосистеме CPython для их использования с обработкой ошибок.667668### API высокого уровня669670Это наиболее часто используемые типы и функции при написании кода C-расширения или при встраивании интерпретатора Python:671672#### `type PyInterpreterState`673674*Часть [Limited API](https://python-all.ru/3.13/c-api/stable.html#stable) (как непрозрачная структура).*675676Эта структура данных представляет состояние, совместно используемое несколькими взаимодействующими потоками. Потоки, принадлежащие одному интерпретатору, разделяют администрирование модулей и несколько других внутренних элементов. В этой структуре нет открытых членов.677678Потоки, принадлежащие разным интерпретаторам, изначально не разделяют ничего, кроме состояния процесса, такого как доступная память, открытые файловые дескрипторы и т.п. Глобальная блокировка интерпретатора также разделяется всеми потоками, независимо от того, какому интерпретатору они принадлежат.679680Изменено в версии 3.12: [**PEP 684**](https://python-all.ru/3.13/c-api/init.html) ввёл возможность [индивидуального GIL для каждого интерпретатора](https://python-all.ru/3.13/c-api/init.html#per-interpreter-gil). См. [`Py_NewInterpreterFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreterFromConfig).681682#### `type PyThreadState`683684*Часть [Limited API](https://python-all.ru/3.13/c-api/stable.html#stable) (как непрозрачная структура).*685686Эта структура данных представляет состояние одного потока. Единственный открытый элемент данных:687688#### `PyInterpreterState *interp`689690Состояние интерпретатора этого потока.691692#### `void PyEval_InitThreads()`693694*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*695696Устаревшая функция, которая ничего не делает.697698В Python 3.6 и старше эта функция создавала GIL, если его не существовало.699700Изменено в версии 3.9: Теперь функция ничего не делает.701702Изменено в версии 3.7: Теперь эта функция вызывается [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize), так что вам больше не нужно вызывать её самостоятельно.703704Изменено в версии 3.2: Эту функцию больше нельзя вызывать до [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).705706Устарело с версии 3.9.707708#### `PyThreadState *PyEval_SaveThread()`709710*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*711712Освобождает глобальную блокировку интерпретатора (если она была создана) и сбрасывает состояние потока на `NULL`, возвращая предыдущее состояние потока (которое не равно `NULL`). Если блокировка была создана, текущий поток должен был её захватить.713714#### `void PyEval_RestoreThread(PyThreadState *tstate)`715716*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*717718Захватывает глобальную блокировку интерпретатора (если она была создана) и устанавливает состояние потока в *tstate*, которое не должно быть `NULL`. Если блокировка была создана, текущий поток не должен был её захватить, иначе возникает взаимоблокировка.719720> **Примечание**721>722> Вызов этой функции из потока, когда среда выполнения завершается, приведёт к зависанию потока до выхода из программы, даже если поток не был создан Python. Подробнее см. в [Предостережения относительно завершения работы среды выполнения](https://python-all.ru/3.13/c-api/init.html#cautions-regarding-runtime-finalization).723724Изменено в версии 3.13.8: Приостанавливает текущий поток, а не завершает его, если вызвано во время финализации интерпретатора.725726#### `PyThreadState *PyThreadState_Get()`727728*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*729730Возвращает текущее состояние потока. Глобальная блокировка интерпретатора должна быть захвачена. Если текущее состояние потока равно `NULL`, вызывается фатальная ошибка (так что вызывающему коду не нужно проверять на `NULL`).731732См. также [`PyThreadState_GetUnchecked()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_GetUnchecked).733734#### `PyThreadState *PyThreadState_GetUnchecked()`735736Аналогично [`PyThreadState_Get()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Get), но не завершает процесс фатальной ошибкой, если значение равно NULL. Вызывающий код должен самостоятельно проверить, не является ли результат NULL.737738Добавлено в версии 3.13: В версиях Python с 3.5 по 3.12 эта функция была приватной и называлась `_PyThreadState_UncheckedGet()`.739740#### `PyThreadState *PyThreadState_Swap(PyThreadState *tstate)`741742*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*743744Заменяет текущее состояние потока на состояние потока, заданное аргументом *tstate*, который может быть `NULL`.745746Удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL) не требуется, но он будет удерживаться при возврате, если *tstate* не равен `NULL`.747748Следующие функции используют локальное хранилище потока и несовместимы с подынтерпретаторами:749750#### `type PyGILState_STATE`751752*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*753754Тип значения, возвращаемого [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) и передаваемого в [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release).755756#### `enumerator PyGILState_LOCKED`757758GIL уже был захвачен, когда была вызвана [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure).759760#### `enumerator PyGILState_UNLOCKED`761762GIL не был захвачен, когда была вызвана [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure).763764#### `PyGILState_STATE PyGILState_Ensure()`765766*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*767768Обеспечивает, что текущий поток готов к вызову Python C API независимо от текущего состояния Python или глобальной блокировки интерпретатора. Этот вызов может вызываться потоком сколько угодно раз, при условии, что каждый вызов завершается вызовом [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release). В общем случае другие API, связанные с потоками, могут использоваться между вызовами [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) и `PyGILState_Release()`, если состояние потока будет восстановлено в предыдущее состояние перед Release(). Например, обычное использование макросов [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS) и [`Py_END_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS) допустимо.769770Возвращаемое значение – это непрозрачный «дескриптор» состояния потока на момент вызова [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure), и его необходимо передать в [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release), чтобы гарантировать, что Python останется в том же состоянии. Хотя рекурсивные вызовы разрешены, эти дескрипторы *нельзя* совместно использовать – каждый уникальный вызов `PyGILState_Ensure()` должен сохранить свой дескриптор для вызова `PyGILState_Release()`.771772Когда функция возвращает управление, текущий поток будет удерживать GIL и сможет вызывать произвольный код Python. Сбой является фатальной ошибкой.773774> **Примечание**775>776> Вызов этой функции из потока, когда среда выполнения завершается, приведёт к зависанию потока до выхода из программы, даже если поток не был создан Python. Подробнее см. в [Предостережения относительно завершения работы среды выполнения](https://python-all.ru/3.13/c-api/init.html#cautions-regarding-runtime-finalization).777778Изменено в версии 3.13.8: Зависает текущий поток, а не завершает его, если вызывается во время финализации интерпретатора.779780#### `void PyGILState_Release(PyGILState_STATE)`781782*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*783784Освобождает любые ресурсы, полученные ранее. После этого вызова состояние Python будет таким же, как до соответствующего вызова [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) (но обычно это состояние неизвестно вызывающему, поэтому используется GILState API).785786Каждый вызов [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) должен сопровождаться вызовом [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release) в том же потоке.787788#### `PyThreadState *PyGILState_GetThisThreadState()`789790*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*791792Возвращает состояние текущего потока. Может вернуть `NULL`, если на текущем потоке не использовался GILState API. Обратите внимание, что главный поток всегда имеет такое состояние, даже если для него не вызывался auto-thread-state. Это вспомогательная/диагностическая функция.793794#### `int PyGILState_Check()`795796Возвращает `1`, если текущий поток удерживает GIL, и `0` в противном случае. Эту функцию можно вызывать из любого потока в любое время. Только если состояние потока Python инициализировано и он в данный момент удерживает GIL, она вернёт `1`. Это в основном вспомогательная/диагностическая функция. Она может быть полезна, например, в контекстах колбэков или функциях выделения памяти, когда знание того, что GIL заблокирован, позволяет вызывающей стороне выполнять чувствительные действия или вести себя иначе.797798Добавлено в версии 3.4.799800Следующие макросы обычно используются без точки с запятой в конце; примеры использования можно найти в дистрибутиве исходного кода Python.801802#### `Py_BEGIN_ALLOW_THREADS`803804*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*805806Этот макрос раскрывается в `{ PyThreadState *_save; _save = PyEval_SaveThread();`. Обратите внимание, что он содержит открывающую фигурную скобку; она должна быть сопоставлена с последующим макросом [`Py_END_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS). См. выше дополнительное обсуждение этого макроса.807808#### `Py_END_ALLOW_THREADS`809810*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*811812Этот макрос раскрывается в `PyEval_RestoreThread(_save); }`. Обратите внимание, что он содержит закрывающую фигурную скобку; она должна быть сопоставлена с предыдущим макросом [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS). См. выше дополнительное обсуждение этого макроса.813814#### `Py_BLOCK_THREADS`815816*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*817818Этот макрос разворачивается в `PyEval_RestoreThread(_save);`: он эквивалентен [`Py_END_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS) без закрывающей фигурной скобки.819820#### `Py_UNBLOCK_THREADS`821822*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*823824Этот макрос разворачивается в `_save = PyEval_SaveThread();`: он эквивалентен [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.13/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS) без открывающей фигурной скобки и объявления переменной.825826### Низкоуровневый API827828Все следующие функции должны вызываться после [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize).829830Изменено в версии 3.7: [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize) теперь инициализирует [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).831832#### `PyInterpreterState *PyInterpreterState_New()`833834*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*835836Создаёт новый объект состояния интерпретатора. Глобальная блокировка интерпретатора может не удерживаться, но может удерживаться, если необходимо сериализовать вызовы этой функции.837838Возбуждает [событие аудита](https://python-all.ru/3.13/library/sys.html#auditing) `cpython.PyInterpreterState_New` без аргументов.839840#### `void PyInterpreterState_Clear(PyInterpreterState *interp)`841842*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*843844Сбрасывает всю информацию в объекте состояния интерпретатора. Глобальная блокировка интерпретатора должна удерживаться.845846Возбуждает [событие аудита](https://python-all.ru/3.13/library/sys.html#auditing) `cpython.PyInterpreterState_Clear` без аргументов.847848#### `void PyInterpreterState_Delete(PyInterpreterState *interp)`849850*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*851852Уничтожает объект состояния интерпретатора. Глобальная блокировка интерпретатора может не удерживаться. Состояние интерпретатора должно быть предварительно сброшено вызовом [`PyInterpreterState_Clear()`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterState_Clear).853854#### `PyThreadState *PyThreadState_New(PyInterpreterState *interp)`855856*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*857858Создаёт новый объект состояния потока, принадлежащий данному объекту интерпретатора. Глобальная блокировка интерпретатора может не удерживаться, но может удерживаться, если необходимо сериализовать вызовы этой функции.859860#### `void PyThreadState_Clear(PyThreadState *tstate)`861862*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*863864Сбрасывает всю информацию в объекте состояния потока. Глобальная блокировка интерпретатора должна удерживаться.865866Изменено в версии 3.9: Теперь эта функция вызывает колбэк `PyThreadState.on_delete`. Ранее это происходило в [`PyThreadState_Delete()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Delete).867868Изменено в версии 3.13: Колбэк `PyThreadState.on_delete` удалён.869870#### `void PyThreadState_Delete(PyThreadState *tstate)`871872*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*873874Уничтожает объект состояния потока. Глобальная блокировка интерпретатора может не удерживаться. Состояние потока должно быть предварительно сброшено вызовом [`PyThreadState_Clear()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Clear).875876#### `void PyThreadState_DeleteCurrent(void)`877878Уничтожает текущее состояние потока и освобождает глобальную блокировку интерпретатора. Как и [`PyThreadState_Delete()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Delete), глобальная блокировка интерпретатора должна удерживаться. Состояние потока должно быть предварительно сброшено вызовом [`PyThreadState_Clear()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Clear).879880#### `PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)`881882*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*883884Возвращает текущий кадр состояния потока Python *tstate*.885886Возвращает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference). Возвращает `NULL`, если в данный момент кадр не выполняется.887888См. также [`PyEval_GetFrame()`](https://python-all.ru/3.13/c-api/reflection.html#c.PyEval_GetFrame).889890*tstate* не должно быть `NULL`.891892Добавлено в версии 3.9.893894#### `uint64_t PyThreadState_GetID(PyThreadState *tstate)`895896*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*897898Возвращает уникальный идентификатор состояния потока Python для *tstate*.899900*tstate* не должно быть `NULL`.901902Добавлено в версии 3.9.903904#### `PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)`905906*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*907908Возвращает интерпретатор состояния потока Python *tstate*.909910*tstate* не должно быть `NULL`.911912Добавлено в версии 3.9.913914#### `void PyThreadState_EnterTracing(PyThreadState *tstate)`915916Приостанавливает трассировку и профилирование в состоянии потока Python *tstate*.917918Возобновляет их с помощью функции [`PyThreadState_LeaveTracing()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_LeaveTracing).919920Добавлено в версии 3.12.921922#### `void PyThreadState_LeaveTracing(PyThreadState *tstate)`923924Возобновляет трассировку и профилирование в состоянии потока Python *tstate*, приостановленные функцией [`PyThreadState_EnterTracing()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_EnterTracing).925926См. также функции [`PyEval_SetTrace()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetTrace) и [`PyEval_SetProfile()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetProfile).927928Добавлено в версии 3.12.929930#### `PyInterpreterState *PyInterpreterState_Get(void)`931932*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.9.*933934Получает текущий интерпретатор.935936Выдаёт фатальную ошибку, если нет текущего состояния потока Python или текущего интерпретатора. Не может вернуть NULL.937938Вызывающий должен удерживать GIL.939940Добавлено в версии 3.9.941942#### `int64_t PyInterpreterState_GetID(PyInterpreterState *interp)`943944*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*945946Возвращает уникальный идентификатор интерпретатора. Если при этом произошла ошибка, возвращается `-1` и устанавливается исключение.947948Вызывающий должен удерживать GIL.949950Добавлено в версии 3.7.951952#### `PyObject *PyInterpreterState_GetDict(PyInterpreterState *interp)`953954*Возвращаемое значение: заимствованная ссылка.*955956*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.8.*957958Возвращает словарь, в котором могут храниться данные, специфичные для интерпретатора. Если эта функция возвращает `NULL`, исключение не было возбуждено, и вызывающий код должен считать, что словарь данных интерпретатора недоступен.959960Это не замена [`PyModule_GetState()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetState), который расширения должны использовать для хранения информации о состоянии интерпретатора.961962Возвращаемый словарь заимствуется из интерпретатора и действителен до завершения работы интерпретатора.963964Добавлено в версии 3.8.965966#### `PyObject *PyUnstable_InterpreterState_GetMainModule(PyInterpreterState *interp)`967968> *Это [нестабильное API](https://python-all.ru/3.13/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*969970Возвращает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на `__main__` [объект модуля](https://python-all.ru/3.13/c-api/module.html#moduleobjects) для указанного интерпретатора.971972Вызывающий должен удерживать GIL.973974Добавлено в версии 3.13.975976#### `typedef PyObject *(*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)`977978Тип функции вычисления фрейма.979980Параметр *throwflag* используется методом `throw()` генераторов: если он не равен нулю, обрабатывается текущее исключение.981982Изменено в версии 3.9: Теперь функция принимает параметр *tstate*.983984Изменено в версии 3.11: Параметр *frame* изменился с `PyFrameObject*` на `_PyInterpreterFrame*`.985986#### `_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)`987988Возвращает функцию вычисления фрейма.989990См. [**PEP 523**](https://python-all.ru/3.13/c-api/init.html) «Добавление API вычисления фрейма в CPython».991992Добавлено в версии 3.9.993994#### `void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)`995996Устанавливает функцию вычисления фрейма.997998См. [**PEP 523**](https://python-all.ru/3.13/c-api/init.html) «Добавление API вычисления фрейма в CPython».9991000Добавлено в версии 3.9.10011002#### `PyObject *PyThreadState_GetDict()`10031004*Возвращаемое значение: заимствованная ссылка.*10051006*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10071008Возвращает словарь, в котором расширения могут хранить информацию о состоянии, специфичном для потока. Каждое расширение должно использовать уникальный ключ для хранения состояния в словаре. Допускается вызывать эту функцию, когда нет текущего состояния потока. Если эта функция возвращает `NULL`, исключение не было возбуждено, и вызывающий должен предполагать, что текущее состояние потока недоступно.10091010#### `int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)`10111012*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10131014Асинхронно возбуждает исключение в потоке. Аргумент *id* – это идентификатор потока целевого потока; *exc* – это объект исключения, которое нужно возбудить. Эта функция не крадёт ссылки на *exc*. Для предотвращения наивного misuse требуется написать собственное C-расширение для её вызова. Должна вызываться с удержанием GIL. Возвращает количество изменённых состояний потока; обычно это единица, но будет нулём, если идентификатор потока не найден. Если *exc* равно `NULL`, отложенное исключение (если есть) для потока очищается. Эта функция не возбуждает исключений.10151016Изменено в версии 3.7: Тип параметра *id* изменён с long на unsigned long.10171018#### `void PyEval_AcquireThread(PyThreadState *tstate)`10191020*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10211022Захватывает глобальную блокировку интерпретатора и устанавливает текущее состояние потока в *tstate*, которое не должно быть `NULL`. Блокировка должна быть создана ранее. Если этот поток уже удерживает блокировку, возникает взаимоблокировка.10231024> **Примечание**1025>1026> Вызов этой функции из потока, когда среда выполнения завершается, приведёт к зависанию потока до выхода из программы, даже если поток не был создан Python. Подробнее см. в [Предостережения относительно завершения работы среды выполнения](https://python-all.ru/3.13/c-api/init.html#cautions-regarding-runtime-finalization).10271028Изменено в версии 3.8: Функция обновлена для согласованности с [`PyEval_RestoreThread()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_RestoreThread), [`Py_END_ALLOW_THREADS()`](https://python-all.ru/3.13/c-api/init.html#c.Py_END_ALLOW_THREADS) и [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure), и теперь завершает текущий поток, если вызвана во время завершения работы интерпретатора.10291030Изменено в версии 3.13.8: Вешает текущий поток, а не завершает его, если вызывается во время финализации интерпретатора.10311032[`PyEval_RestoreThread()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_RestoreThread) – функция более высокого уровня, которая всегда доступна (даже если потоки не были инициализированы).10331034#### `void PyEval_ReleaseThread(PyThreadState *tstate)`10351036*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*10371038Сбрасывает текущее состояние потока в `NULL` и освобождает глобальную блокировку интерпретатора. Блокировка должна быть создана ранее и должна удерживаться текущим потоком. Аргумент *tstate*, который не должен быть `NULL`, используется только для проверки, что он представляет текущее состояние потока – если это не так, выводится фатальная ошибка.10391040[`PyEval_SaveThread()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SaveThread) – функция более высокого уровня, которая всегда доступна (даже если потоки не были инициализированы).10411042## Поддержка под-интерпретаторов10431044Хотя в большинстве случаев достаточно встроить один интерпретатор Python, бывают ситуации, когда требуется создать несколько независимых интерпретаторов в одном процессе и даже в одном потоке. Под-интерпретаторы позволяют это сделать.10451046«Главный» интерпретатор – это первый интерпретатор, создаваемый при инициализации среды выполнения. Обычно он является единственным интерпретатором Python в процессе. В отличие от под-интерпретаторов, главный интерпретатор обладает уникальными общепроцессными обязанностями, такими как обработка сигналов. Он также отвечает за выполнение при инициализации среды выполнения и обычно является активным интерпретатором при завершении работы среды выполнения. Функция [`PyInterpreterState_Main()`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterState_Main) возвращает указатель на его состояние.10471048Переключаться между под-интерпретаторами можно с помощью функции [`PyThreadState_Swap()`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState_Swap). Создавать и удалять их можно с помощью следующих функций:10491050#### `type PyInterpreterConfig`10511052Структура, содержащая большинство параметров для настройки под-интерпретатора. Её значения используются только в [`Py_NewInterpreterFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreterFromConfig) и никогда не изменяются средой выполнения.10531054Добавлено в версии 3.12.10551056Поля структуры:10571058#### `int use_main_obmalloc`10591060Если это `0`, то под-интерпретатор будет использовать собственное состояние аллокатора «объектов». В противном случае он будет использовать (разделять) состояние главного интерпретатора.10611062Если это `0`, то [`check_multi_interp_extensions`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig.check_multi_interp_extensions) должен быть `1` (ненулевым). Если это `1`, то [`gil`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig.gil) не должен быть [`PyInterpreterConfig_OWN_GIL`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig_OWN_GIL).10631064#### `int allow_fork`10651066Если это `0`, то среда выполнения не будет поддерживать создание форка процесса в любом потоке, где в данный момент активен под-интерпретатор. В противном случае форк не ограничен.10671068Обратите внимание, что модуль [`subprocess`](https://python-all.ru/3.13/library/subprocess.html#module-subprocess) по-прежнему работает, когда форк запрещён.10691070#### `int allow_exec`10711072Если это `0`, то среда выполнения не будет поддерживать замену текущего процесса через exec (например, [`os.execv()`](https://python-all.ru/3.13/library/os.html#os.execv)) в любом потоке, где в данный момент активен под-интерпретатор. В противном случае exec не ограничен.10731074Обратите внимание, что модуль [`subprocess`](https://python-all.ru/3.13/library/subprocess.html#module-subprocess) по-прежнему работает, когда exec запрещён.10751076#### `int allow_threads`10771078Если это `0`, то модуль [`threading`](https://python-all.ru/3.13/library/threading.html#module-threading) под-интерпретатора не будет создавать потоки. В противном случае потоки разрешены.10791080#### `int allow_daemon_threads`10811082Если это `0`, то модуль [`threading`](https://python-all.ru/3.13/library/threading.html#module-threading) под-интерпретатора не будет создавать потоки-демоны. В противном случае потоки-демоны разрешены (при условии, что [`allow_threads`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig.allow_threads) не равен нулю).10831084#### `int check_multi_interp_extensions`10851086Если это `0`, то все модули расширений могут быть импортированы, включая устаревшие модули (с однофазной инициализацией), в любом потоке, где активен под-интерпретатор. В противном случае могут быть импортированы только модули расширений с многофазной инициализацией (см. [**PEP 489**](https://python-all.ru/3.13/c-api/init.html)). (См. также [`Py_mod_multiple_interpreters`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_multiple_interpreters).)10871088Это должно быть `1` (ненулевым), если [`use_main_obmalloc`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig.use_main_obmalloc) равно `0`.10891090#### `int gil`10911092Это определяет режим работы GIL для под-интерпретатора. Он может быть одним из следующих:10931094#### `PyInterpreterConfig_DEFAULT_GIL`10951096Использовать выбор по умолчанию ([`PyInterpreterConfig_SHARED_GIL`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig_SHARED_GIL)).10971098#### `PyInterpreterConfig_SHARED_GIL`10991100Использовать (разделять) GIL главного интерпретатора.11011102#### `PyInterpreterConfig_OWN_GIL`11031104Использовать собственный GIL под-интерпретатора.11051106Если это [`PyInterpreterConfig_OWN_GIL`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig_OWN_GIL), то [`PyInterpreterConfig.use_main_obmalloc`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterConfig.use_main_obmalloc) должен быть `0`.11071108#### `PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)`11091110Создаёт новый под-интерпретатор. Это (почти) полностью независимое окружение для выполнения кода Python. В частности, новый интерпретатор имеет отдельные, независимые версии всех импортированных модулей, включая фундаментальные модули [`builtins`](https://python-all.ru/3.13/library/builtins.html#module-builtins), [`__main__`](https://python-all.ru/3.13/library/__main__.html#module-__main__) и [`sys`](https://python-all.ru/3.13/library/sys.html#module-sys). Таблица загруженных модулей (`sys.modules`) и путь поиска модулей (`sys.path`) также отдельные. В новом окружении нет переменной `sys.argv` . У него есть новые файловые объекты стандартных потоков ввода-вывода `sys.stdin`, `sys.stdout` и `sys.stderr` (однако они ссылаются на те же нижележащие файловые дескрипторы).11111112Переданный *config* управляет параметрами, с которыми инициализируется интерпретатор.11131114В случае успеха *tstate\_p* будет установлен на первое состояние потока, созданное в новом под-интерпретаторе. Это состояние потока создаётся в текущем состоянии потока. Обратите внимание, что реальный поток не создаётся; см. обсуждение состояний потока ниже. Если создание нового интерпретатора не удаётся, *tstate\_p* устанавливается в `NULL`; исключение не устанавливается, так как состояние исключения хранится в текущем состоянии потока, и текущего состояния потока может не существовать.11151116Как и все остальные функции Python/C API, перед вызовом этой функции должна быть захвачена глобальная блокировка интерпретатора, и она остаётся захваченной после возврата. Также при входе должно быть установлено текущее состояние потока. В случае успеха возвращённое состояние потока становится текущим. Если под-интерпретатор создаётся с собственным GIL, то GIL вызывающего интерпретатора будет освобождён. Когда функция возвращает управление, GIL нового интерпретатора будет захвачен текущим потоком, а GIL предыдущего интерпретатора останется освобождённым.11171118Добавлено в версии 3.12.11191120Под-интерпретаторы наиболее эффективны при изоляции друг от друга, с ограничением определённой функциональности:11211122```c1123PyInterpreterConfig config = {1124    .use_main_obmalloc = 0,1125    .allow_fork = 0,1126    .allow_exec = 0,1127    .allow_threads = 1,1128    .allow_daemon_threads = 0,1129    .check_multi_interp_extensions = 1,1130    .gil = PyInterpreterConfig_OWN_GIL,1131};1132PyThreadState *tstate = NULL;1133PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);1134if (PyStatus_Exception(status)) {1135    Py_ExitStatusException(status);1136}1137```11381139Обратите внимание, что config используется только кратковременно и не изменяется. Во время инициализации значения config преобразуются в различные значения [`PyInterpreterState`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterState). Копия config только для чтения может быть сохранена внутри на `PyInterpreterState`.11401141Модули расширения совместно используются (под-)интерпретаторами следующим образом:11421143- Для модулей, использующих многофазную инициализацию, например [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_FromDefAndSpec), для каждого интерпретатора создаётся и инициализируется отдельный объект модуля. Между этими объектами модулей совместно используются только статические и глобальные переменные на уровне C.1144- Для модулей, использующих однофазную инициализацию, например [`PyModule_Create()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Create), при первом импорте определённого расширения оно инициализируется обычным образом, и (поверхностная) копия его словаря модуля сохраняется. Когда то же расширение импортируется другим (под-)интерпретатором, новый модуль инициализируется и заполняется содержимым этой копии; функция `init` расширения не вызывается. Таким образом, объекты в словаре модуля оказываются общими для (под-)интерпретаторов, что может вызывать нежелательное поведение (см. [Ошибки и предостережения](https://python-all.ru/3.13/c-api/init.html#bugs-and-caveats) ниже).11451146  Обратите внимание, что это отличается от ситуации, когда расширение импортируется после полной повторной инициализации интерпретатора вызовом [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx) и [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize); в этом случае функция `initmodule` расширения *вызывается* снова. Как и при многофазной инициализации, это означает, что между этими модулями совместно используются только статические и глобальные переменные на уровне C.11471148#### `PyThreadState *Py_NewInterpreter(void)`11491150*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11511152Создаёт новый под-интерпретатор. По сути, это просто обёртка вокруг [`Py_NewInterpreterFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreterFromConfig) с config, который сохраняет существующее поведение. Результатом является неизолированный под-интерпретатор, который разделяет GIL главного интерпретатора, допускает fork/exec, разрешает фоновые потоки и допускает модули с однофазной инициализацией.11531154#### `void Py_EndInterpreter(PyThreadState *tstate)`11551156*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11571158Уничтожает (под-)интерпретатор, представленный указанным состоянием потока. Указанное состояние потока должно быть текущим состоянием потока. См. обсуждение состояний потока ниже. Когда вызов возвращает управление, текущее состояние потока равно `NULL`. Все состояния потока, связанные с этим интерпретатором, уничтожаются. Глобальная блокировка интерпретатора, используемая целевым интерпретатором, должна быть захвачена перед вызовом этой функции. При возврате GIL не удерживается.11591160[`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx) уничтожит все под-интерпретаторы, которые не были явно уничтожены к этому моменту.11611162### Перинтерпретаторный GIL11631164С помощью [`Py_NewInterpreterFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_NewInterpreterFromConfig) можно создать под-интерпретатор, который полностью изолирован от других интерпретаторов, включая собственный GIL. Самое важное преимущество такой изоляции в том, что такой интерпретатор может выполнять код Python без блокировки другими интерпретаторами и не блокируя другие. Таким образом, один процесс Python может по-настоящему использовать несколько ядер CPU при выполнении кода Python. Изоляция также поощряет иной подход к параллелизму, отличный от простого использования потоков. (См. [**PEP 554**](https://python-all.ru/3.13/c-api/init.html) и [**PEP 684**](https://python-all.ru/3.13/c-api/init.html).)11651166Использование изолированного интерпретатора требует бдительности для сохранения этой изоляции. Это особенно означает, что нельзя совместно использовать объекты или изменяемое состояние без гарантий потокобезопасности. Даже объекты, которые в остальном неизменяемы (например, `None`, `(1, 5)`), обычно не могут быть использованы совместно из-за счётчика ссылок. Один простой, но менее эффективный подход – использовать глобальную блокировку при любом использовании некоторого состояния (или объекта). С другой стороны, эффективно неизменяемые объекты (такие как целые числа или строки) можно сделать безопасными, несмотря на их счётчики ссылок, сделав их [бессмертными](https://python-all.ru/3.13/glossary.html#term-immortal). Фактически, это уже сделано для встроенных синглтонов, маленьких целых чисел и ряда других встроенных объектов.11671168Если сохранять изоляцию, то будет доступ к настоящим многоядерным вычислениям без осложнений, связанных со свободной многопоточностью. Несоблюдение изоляции приведёт ко всем последствиям свободной многопоточности, включая гонки и трудноотлаживаемые крахи.11691170Кроме того, одна из главных проблем использования нескольких изолированных интерпретаторов – как безопасно (не нарушая изоляцию) и эффективно общаться между ними. Среда выполнения и стандартная библиотека пока не предоставляют стандартного подхода для этого. Будущий модуль стандартной библиотеки поможет уменьшить усилия по сохранению изоляции и предоставит эффективные инструменты для обмена (и совместного использования) данными между интерпретаторами.11711172Добавлено в версии 3.12.11731174### Ошибки и предостережения11751176Поскольку под-интерпретаторы (и главный интерпретатор) являются частью одного процесса, изоляция между ними не идеальна – например, с помощью низкоуровневых файловых операций, таких как [`os.close()`](https://python-all.ru/3.13/library/os.html#os.close), они могут (случайно или намеренно) влиять на открытые файлы друг друга. Из-за того, как расширения совместно используются (под-)интерпретаторами, некоторые расширения могут работать некорректно; это особенно вероятно при использовании однофазной инициализации или (статических) глобальных переменных. Можно вставлять объекты, созданные в одном под-интерпретаторе, в пространство имён другого (под-)интерпретатора; этого следует избегать, если возможно.11771178Следует проявлять особую осторожность, чтобы избежать совместного использования пользовательских функций, методов, экземпляров или классов между под-интерпретаторами, поскольку операции импорта, выполняемые такими объектами, могут повлиять на словарь загруженных модулей не того (под-)интерпретатора. Не менее важно избегать совместного использования объектов, из которых доступны вышеперечисленные.11791180Также обратите внимание, что комбинирование этой функциональности с API `PyGILState_*` является деликатным, поскольку эти API предполагают взаимно однозначное соответствие между состояниями потоков Python и потоками уровня ОС, а это предположение нарушается наличием под-интерпретаторов. Настоятельно рекомендуется не переключать под-интерпретаторы между парой соответствующих вызовов [`PyGILState_Ensure()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Ensure) и [`PyGILState_Release()`](https://python-all.ru/3.13/c-api/init.html#c.PyGILState_Release). Более того, расширения (такие как [`ctypes`](https://python-all.ru/3.13/library/ctypes.html#module-ctypes)), использующие эти API для вызова кода Python из потоков, созданных не в Python, вероятно, будут работать неправильно при использовании под-интерпретаторов.11811182## Асинхронные уведомления11831184Предоставляется механизм для асинхронных уведомлений основному потоку интерпретатора. Эти уведомления имеют форму указателя на функцию и аргумента в виде указателя void.11851186#### `int Py_AddPendingCall(int (*func)(void*), void *arg)`11871188*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*11891190Планирует вызов функции из основного потока интерпретатора. В случае успеха возвращается `0`, и *func* помещается в очередь для вызова в основном потоке. В случае неудачи возвращается `-1` без установки какого-либо исключения.11911192При успешной постановке в очередь *func* будет *в конечном итоге* вызвана из основного потока интерпретатора с аргументом *arg*. Она будет вызвана асинхронно по отношению к нормально выполняющемуся коду Python, но при соблюдении обоих этих условий:11931194- на границе [байткода](https://python-all.ru/3.13/glossary.html#term-bytecode);1195- при этом главный поток удерживает [глобальную блокировку интерпретатора](https://python-all.ru/3.13/glossary.html#term-global-interpreter-lock) (поэтому *func* может использовать полный C API).11961197*func* должна возвращать `0` при успехе или `-1` при неудаче с установленным исключением. *func* не будет прервана для рекурсивного выполнения другого асинхронного уведомления, но её всё ещё можно прервать для переключения потоков, если глобальная блокировка интерпретатора освобождена.11981199Для выполнения этой функции не требуется текущее состояние потока, и ей не нужна глобальная блокировка интерпретатора.12001201Для вызова этой функции в под-интерпретаторе вызывающий должен удерживать GIL. В противном случае функция *func* может быть запланирована к вызову из неправильного интерпретатора.12021203> **Предупреждение**1204>1205> Это низкоуровневая функция, полезная только в особых случаях. Нет гарантии, что *func* будет вызвана максимально быстро. Если главный поток занят выполнением системного вызова, *func* не будет вызвана до возврата из системного вызова. Эта функция в целом **не** подходит для вызова кода Python из произвольных C-потоков. Вместо неё используйте [PyGILState API](https://python-all.ru/3.13/c-api/init.html#gilstate).12061207Добавлено в версии 3.1.12081209Изменено в версии 3.9: Если эта функция вызывается в подынтерпретаторе, функция *func* теперь планируется для вызова из подынтерпретатора, а не из основного интерпретатора. Каждый подынтерпретатор теперь имеет свой собственный список запланированных вызовов.12101211Изменено в версии 3.12: Эта функция теперь всегда планирует выполнение *func* в основном интерпретаторе.12121213#### `int Py_MakePendingCalls(void)`12141215*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*12161217Выполняет все отложенные вызовы. Обычно это выполняется автоматически интерпретатором.12181219Эта функция возвращает `0` при успехе и `-1` с установленным исключением при ошибке.12201221Если эта функция вызывается не в главном потоке главного интерпретатора, она ничего не делает и возвращает `0`. Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).12221223Добавлено в версии 3.1.12241225Изменено в версии 3.12: Эта функция выполняет отложенные вызовы только в основном интерпретаторе.12261227## Профилирование и трассировка12281229Интерпретатор Python предоставляет низкоуровневую поддержку для подключения средств профилирования и трассировки выполнения. Они используются в инструментах профилирования, отладки и анализа покрытия.12301231Этот C-интерфейс позволяет коду профилирования или трассировки избежать накладных расходов на вызов через вызываемые объекты уровня Python, выполняя вместо этого прямой вызов C-функции. Основные характеристики механизма не изменились; интерфейс позволяет устанавливать функции трассировки для каждого потока, а базовые события, сообщаемые функции трассировки, такие же, как и в предыдущих версиях для функций трассировки уровня Python.12321233#### `typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)`12341235Тип функции трассировки, регистрируемой с помощью [`PyEval_SetProfile()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetProfile) и [`PyEval_SetTrace()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetTrace). Первый параметр – это объект, переданный функции регистрации как *obj*, *frame* – это объект фрейма, к которому относится событие, *what* – одна из констант [`PyTrace_CALL`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_CALL), [`PyTrace_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_EXCEPTION), [`PyTrace_LINE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_LINE), [`PyTrace_RETURN`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_RETURN), [`PyTrace_C_CALL`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_CALL), [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_EXCEPTION), [`PyTrace_C_RETURN`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_RETURN) или [`PyTrace_OPCODE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_OPCODE), а *arg* зависит от значения *what*:12361237| Значение *what* | Смысл *arg* |1238| --- | --- |1239| [`PyTrace_CALL`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_CALL) | Всегда [`Py_None`](https://python-all.ru/3.13/c-api/none.html#c.Py_None). |1240| [`PyTrace_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_EXCEPTION) | Информация об исключении, возвращаемая [`sys.exc_info()`](https://python-all.ru/3.13/library/sys.html#sys.exc_info). |1241| [`PyTrace_LINE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_LINE) | Всегда [`Py_None`](https://python-all.ru/3.13/c-api/none.html#c.Py_None). |1242| [`PyTrace_RETURN`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_RETURN) | Значение, возвращаемое вызывающему коду, или `NULL`, если вызвано исключением. |1243| [`PyTrace_C_CALL`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_CALL) | Вызываемый объект функции. |1244| [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_EXCEPTION) | Вызываемый объект функции. |1245| [`PyTrace_C_RETURN`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_RETURN) | Вызываемый объект функции. |1246| [`PyTrace_OPCODE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_OPCODE) | Всегда [`Py_None`](https://python-all.ru/3.13/c-api/none.html#c.Py_None). |12471248#### `int PyTrace_CALL`12491250Значение параметра *what* для функции [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда сообщается о новом вызове функции или метода, или о новом входе в генератор. Обратите внимание, что создание итератора для функции-генератора не сообщается, поскольку в соответствующем фрейме не происходит передачи управления байт-коду Python.12511252#### `int PyTrace_EXCEPTION`12531254Значение параметра *what* для функции [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда возникло исключение. Функция обратного вызова вызывается с этим значением для *what* после обработки любого байт-кода, после которого исключение становится установленным в выполняемом фрейме. В результате, когда распространение исключения вызывает раскрутку стека Python, функция обратного вызова вызывается при возврате в каждый фрейм по мере распространения исключения. Только функции трассировки получают эти события; профилировщику они не нужны.12551256#### `int PyTrace_LINE`12571258Значение, передаваемое в качестве параметра *what* функции [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc) (но не функции профилирования), когда сообщается о событии номера строки. Его можно отключить для фрейма, установив [`f_trace_lines`](https://python-all.ru/3.13/reference/datamodel.html#frame.f_trace_lines) в *0* в этом фрейме.12591260#### `int PyTrace_RETURN`12611262Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда вызов собирается вернуться.12631264#### `int PyTrace_C_CALL`12651266Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда собирается быть вызвана C-функция.12671268#### `int PyTrace_C_EXCEPTION`12691270Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда C-функция вызвала исключение.12711272#### `int PyTrace_C_RETURN`12731274Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc), когда C-функция вернулась.12751276#### `int PyTrace_OPCODE`12771278Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.13/c-api/init.html#c.Py_tracefunc) (но не функций профилирования), когда собирается быть выполнен новый опкод. Это событие не генерируется по умолчанию: его нужно явно запросить, установив [`f_trace_opcodes`](https://python-all.ru/3.13/reference/datamodel.html#frame.f_trace_opcodes) в *1* во фрейме.12791280#### `void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)`12811282Устанавливает функцию профилирования в *func*. Параметр *obj* передаётся функции в качестве первого аргумента; это может быть любой объект Python или `NULL`. Если функции профилирования нужно поддерживать состояние, использование разных значений *obj* для каждого потока предоставляет удобное и потокобезопасное место для его хранения. Функция профилирования вызывается для всех отслеживаемых событий, кроме [`PyTrace_LINE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_LINE), [`PyTrace_OPCODE`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_OPCODE) и [`PyTrace_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_EXCEPTION).12831284См. также функцию [`sys.setprofile()`](https://python-all.ru/3.13/library/sys.html#sys.setprofile).12851286Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).12871288#### `void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)`12891290Как [`PyEval_SetProfile()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetProfile), но устанавливает функцию профилирования во всех работающих потоках, принадлежащих текущему интерпретатору, а не только в текущем потоке.12911292Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).12931294Как и [`PyEval_SetProfile()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetProfile), эта функция игнорирует любые исключения, возникшие при установке функций профилирования во всех потоках.12951296Добавлено в версии 3.12.12971298#### `void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)`12991300Устанавливает функцию трассировки в *func*. Это похоже на [`PyEval_SetProfile()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetProfile), за исключением того, что функция трассировки получает события номеров строк и события на каждую операцию, но не получает событий, связанных с вызовом объектов функций C. Любая функция трассировки, зарегистрированная через [`PyEval_SetTrace()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetTrace), не будет получать [`PyTrace_C_CALL`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_CALL), [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_EXCEPTION) или [`PyTrace_C_RETURN`](https://python-all.ru/3.13/c-api/init.html#c.PyTrace_C_RETURN) в качестве значения параметра *what*.13011302См. также функцию [`sys.settrace()`](https://python-all.ru/3.13/library/sys.html#sys.settrace).13031304Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).13051306#### `void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)`13071308Как [`PyEval_SetTrace()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetTrace), но устанавливает функцию трассировки во всех работающих потоках, принадлежащих текущему интерпретатору, а не только в текущем потоке.13091310Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).13111312Как и [`PyEval_SetTrace()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SetTrace), эта функция игнорирует любые исключения, возникшие при установке функций трассировки во всех потоках.13131314Добавлено в версии 3.12.13151316## Трассировка ссылок13171318Добавлено в версии 3.13.13191320#### `typedef int (*PyRefTracer)(PyObject*, int event, void *data)`13211322Тип функции трассировки, регистрируемой с помощью [`PyRefTracer_SetTracer()`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer_SetTracer). Первый параметр – это объект Python, который только что был создан (когда **event** установлен в [`PyRefTracer_CREATE`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer_CREATE)) или собирается быть уничтожен (когда **event** установлен в [`PyRefTracer_DESTROY`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer_DESTROY)). Аргумент **data** – это непрозрачный указатель, который был предоставлен при вызове `PyRefTracer_SetTracer()`.13231324Добавлено в версии 3.13.13251326#### `int PyRefTracer_CREATE`13271328Значение параметра *event* для функций [`PyRefTracer`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer), когда объект Python был создан.13291330#### `int PyRefTracer_DESTROY`13311332Значение параметра *event* для функций [`PyRefTracer`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer), когда объект Python был уничтожен.13331334#### `int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)`13351336Регистрирует функцию-трассировщик ссылок. Эта функция будет вызываться при создании нового объекта Python или при уничтожении объекта. Если **data** передан, он должен быть непрозрачным указателем, который будет передаваться при вызове трассировщика. Возвращает `0` при успехе. Устанавливает исключение и возвращает `-1` при ошибке.13371338Обратите внимание, что функции-трассировщики **не должны** создавать объекты Python внутри, иначе вызов станет реентерабельным. Трассировщик также **не должен** очищать существующее исключение или устанавливать исключение. GIL будет удерживаться каждый раз при вызове функции-трассировщика.13391340При вызове этой функции необходимо удерживать GIL.13411342Добавлено в версии 3.13.13431344#### `PyRefTracer PyRefTracer_GetTracer(void **data)`13451346Возвращает зарегистрированную функцию трассировки ссылок и значение непрозрачного указателя данных, который был зарегистрирован при вызове [`PyRefTracer_SetTracer()`](https://python-all.ru/3.13/c-api/init.html#c.PyRefTracer_SetTracer). Если трассировщик не был зарегистрирован, эта функция вернёт NULL и установит указатель **data** в NULL.13471348При вызове этой функции необходимо удерживать GIL.13491350Добавлено в версии 3.13.13511352## Поддержка расширенного отладчика13531354Эти функции предназначены только для использования расширенными инструментами отладки.13551356#### `PyInterpreterState *PyInterpreterState_Head()`13571358Возвращает объект состояния интерпретатора, находящийся в начале списка всех таких объектов.13591360#### `PyInterpreterState *PyInterpreterState_Main()`13611362Возвращает объект состояния основного интерпретатора.13631364#### `PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)`13651366Возвращает следующий объект состояния интерпретатора после *interp* из списка всех таких объектов.13671368#### `PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)`13691370Возвращает указатель на первый объект [`PyThreadState`](https://python-all.ru/3.13/c-api/init.html#c.PyThreadState) в списке потоков, связанных с интерпретатором *interp*.13711372#### `PyThreadState *PyThreadState_Next(PyThreadState *tstate)`13731374Возвращает следующий объект состояния потока после *tstate* из списка всех таких объектов, принадлежащих тому же объекту [`PyInterpreterState`](https://python-all.ru/3.13/c-api/init.html#c.PyInterpreterState).13751376## Поддержка локального хранилища потоков13771378Интерпретатор Python предоставляет низкоуровневую поддержку для потоково-локального хранилища (TLS), которая оборачивает базовую нативную реализацию TLS для поддержки API потоково-локального хранилища на уровне Python ([`threading.local`](https://python-all.ru/3.13/library/threading.html#threading.local)). API CPython на уровне C похожи на те, что предоставляются pthreads и Windows: используется ключ потока и функции для ассоциации void\* значения на поток.13791380GIL *не* нужно удерживать при вызове этих функций; они обеспечивают собственную блокировку.13811382Обратите внимание, что `Python.h` не содержит объявления TLS-функций; для использования локальной памяти потока необходимо включить `pythread.h`.13831384> **Примечание**1385>1386> Ни одна из этих функций API не занимается управлением памятью для значений void\*. Вы должны сами выделять и освобождать память. Если значения void\* оказываются [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*, эти функции также не выполняют операции с подсчётом ссылок.13871388### API потоково-специфичного хранилища (TSS)13891390API TSS введен для замены использования существующего API TLS в интерпретаторе CPython. Этот API использует новый тип [`Py_tss_t`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_t) вместо int для представления ключей потоков.13911392Добавлено в версии 3.7.13931394> **См. также**1395>1396> «Новый C-API для локальной памяти потока в CPython» ([**PEP 539**](https://python-all.ru/3.13/c-api/init.html))13971398#### `type Py_tss_t`13991400Эта структура данных представляет состояние ключа потока; её определение может зависеть от конкретной реализации TLS, и она содержит внутреннее поле, отражающее состояние инициализации ключа. Открытых членов этой структуры нет.14011402Если [Py\_LIMITED\_API](https://python-all.ru/3.13/c-api/stable.html#stable) не определён, допускается статическое размещение этого типа с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_NEEDS_INIT).14031404#### `Py_tss_NEEDS_INIT`14051406Этот макрос раскрывается в инициализатор для переменных типа [`Py_tss_t`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_t). Обратите внимание, что этот макрос не будет определён вместе с [Py\_LIMITED\_API](https://python-all.ru/3.13/c-api/stable.html#stable).14071408#### Динамическое выделение14091410Динамическое выделение [`Py_tss_t`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_t) требуется в модулях расширения, собранных с [Py\_LIMITED\_API](https://python-all.ru/3.13/c-api/stable.html#stable), где статическое размещение этого типа невозможно из-за того, что его реализация скрыта во время сборки.14111412#### `Py_tss_t *PyThread_tss_alloc()`14131414*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14151416Возвращает значение, находящееся в том же состоянии, что и значение, инициализированное с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_NEEDS_INIT), или `NULL` в случае ошибки динамического выделения.14171418#### `void PyThread_tss_free(Py_tss_t *key)`14191420*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14211422Освобождает заданный *key*, выделенный с помощью [`PyThread_tss_alloc()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_alloc), предварительно вызвав [`PyThread_tss_delete()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_delete), чтобы сбросить все привязанные к нему локальные данные потока. Эта операция ничего не делает, если аргумент *key* равен `NULL`.14231424> **Примечание**1425>1426> Освобождённый ключ становится висячим указателем. Следует сбросить ключ обратно в `NULL`.14271428#### Методы14291430Параметр *key* этих функций не должен быть `NULL`. Кроме того, поведение [`PyThread_tss_set()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_set) и [`PyThread_tss_get()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_get) не определено, если заданный [`Py_tss_t`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_t) не был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_create).14311432#### `int PyThread_tss_is_created(Py_tss_t *key)`14331434*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14351436Возвращает ненулевое значение, если заданный [`Py_tss_t`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_t) был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_create).14371438#### `int PyThread_tss_create(Py_tss_t *key)`14391440*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14411442Возвращает нулевое значение при успешной инициализации TSS-ключа. Поведение не определено, если значение, на которое указывает аргумент *key*, не инициализировано с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.13/c-api/init.html#c.Py_tss_NEEDS_INIT). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже инициализированного ключа ничего не делает и сразу возвращает успех.14431444#### `void PyThread_tss_delete(Py_tss_t *key)`14451446*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14471448Уничтожает TSS-ключ, забывая связанные с ним значения во всех потоках, и переводит состояние инициализации ключа в «не инициализирован». Уничтоженный ключ можно повторно инициализировать с помощью [`PyThread_tss_create()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_tss_create). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже уничтоженного ключа ничего не делает.14491450#### `int PyThread_tss_set(Py_tss_t *key, void *value)`14511452*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14531454Возвращает нулевое значение при успешной привязке значения void\* к TSS-ключу в текущем потоке. Каждый поток имеет собственное отображение ключа на значение void\*.14551456#### `void *PyThread_tss_get(Py_tss_t *key)`14571458*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*14591460Возвращает значение void\*, связанное с ключом TSS в текущем потоке. Возвращает `NULL`, если с ключом в текущем потоке не связано никакого значения.14611462### API локального хранилища потоков (TLS)14631464Устарело с версии 3.7: Этот API заменён [API поток-специфичного хранилища (TSS)](https://python-all.ru/3.13/c-api/init.html#thread-specific-storage-api).14651466> **Примечание**1467>1468> Эта версия API не поддерживает платформы, где нативный ключ TLS определён так, что его нельзя безопасно привести к `int`. На таких платформах [`PyThread_create_key()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_create_key) немедленно возвращает статус ошибки, а остальные функции TLS на таких платформах ничего не делают.14691470Из-за упомянутой выше проблемы совместимости эту версию API не следует использовать в новом коде.14711472#### `int PyThread_create_key()`14731474*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14751476#### `void PyThread_delete_key(int key)`14771478*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14791480#### `int PyThread_set_key_value(int key, void *value)`14811482*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14831484#### `void *PyThread_get_key_value(int key)`14851486*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14871488#### `void PyThread_delete_key_value(int key)`14891490*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14911492#### `void PyThread_ReInitTLS()`14931494*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*14951496## Примитивы синхронизации14971498C-API предоставляет базовую блокировку взаимного исключения.14991500#### `type PyMutex`15011502Блокировка взаимного исключения. `PyMutex` следует инициализировать нулём для представления разблокированного состояния. Например:15031504```c1505PyMutex mutex = {0};1506```15071508Экземпляры `PyMutex` не должны копироваться или перемещаться. Как содержимое, так и адрес `PyMutex` имеют смысл, и он должен оставаться в фиксированном, доступном для записи месте в памяти.15091510> **Примечание**1511>1512> `PyMutex` в настоящее время занимает один байт, но размер следует считать нестабильным. Размер может измениться в будущих выпусках Python без периода устаревания.15131514Добавлено в версии 3.13.15151516#### `void PyMutex_Lock(PyMutex *m)`15171518Блокирует мьютекс *m*. Если другой поток уже заблокировал его, вызывающий поток будет ожидать, пока мьютекс не будет разблокирован. Во время ожидания поток временно освободит [GIL](https://python-all.ru/3.13/glossary.html#term-GIL), если он удерживается.15191520Добавлено в версии 3.13.15211522#### `void PyMutex_Unlock(PyMutex *m)`15231524Разблокирует мьютекс *m*. Мьютекс должен быть заблокирован – в противном случае функция выдаст фатальную ошибку.15251526Добавлено в версии 3.13.15271528### API критических секций Python15291530API критических секций предоставляет уровень предотвращения взаимных блокировок поверх объектных блокировок для [свободно-поточного](https://python-all.ru/3.13/glossary.html#term-free-threading) CPython. Они предназначены для замены зависимости от [глобальной блокировки интерпретатора](https://python-all.ru/3.13/glossary.html#term-global-interpreter-lock) и являются пустышками (no-op) в версиях Python с глобальной блокировкой интерпретатора.15311532Критические секции предназначены для использования с пользовательскими типами, реализованными в расширениях C-API. Их обычно не следует использовать со встроенными типами, такими как [`list`](https://python-all.ru/3.13/library/stdtypes.html#list) и [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict), поскольку их публичные C-API уже внутренне используют критические секции, за заметным исключением [`PyDict_Next()`](https://python-all.ru/3.13/c-api/dict.html#c.PyDict_Next), для которого требуется внешнее получение критической секции.15331534Критические секции предотвращают взаимные блокировки, неявно приостанавливая активные критические секции, поэтому они не предоставляют исключительный доступ, как традиционные блокировки, например [`PyMutex`](https://python-all.ru/3.13/c-api/init.html#c.PyMutex). При запуске критической секции захватывается объектная блокировка для данного объекта. Если код, выполняемый внутри критической секции, вызывает функции C-API, то он может приостановить критическую секцию, тем самым освободив объектную блокировку, так что другие потоки смогут захватить объектную блокировку для того же объекта.15351536Функции и структуры, используемые макросами, предоставлены для случаев, когда макросы C недоступны. Их следует использовать только так, как в соответствующих развёртках макросов. Учтите, что размеры и содержимое структур могут измениться в будущих версиях Python.15371538> **Примечание**1539>1540> Операции, которым необходимо заблокировать два объекта одновременно, должны использовать [`Py_BEGIN_CRITICAL_SECTION2`](https://python-all.ru/3.13/c-api/init.html#c.Py_BEGIN_CRITICAL_SECTION2). *Нельзя* использовать вложенные критические секции для блокировки более одного объекта одновременно, поскольку внутренняя критическая секция может приостановить внешние критические секции. Этот API не предоставляет способа заблокировать более двух объектов одновременно.15411542Пример использования:15431544```c1545static PyObject *1546set_field(MyObject *self, PyObject *value)1547{1548   Py_BEGIN_CRITICAL_SECTION(self);1549   Py_SETREF(self->field, Py_XNewRef(value));1550   Py_END_CRITICAL_SECTION();1551   Py_RETURN_NONE;1552}1553```15541555В приведённом выше примере [`Py_SETREF`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_SETREF) вызывает [`Py_DECREF`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF), который может вызывать произвольный код через функцию освобождения объекта. API критических секций избегает потенциальных взаимных блокировок из-за повторного входа и порядка блокировок, позволяя среде выполнения временно приостанавливать критическую секцию, если код, запущенный финализатором, блокируется и вызывает [`PyEval_SaveThread()`](https://python-all.ru/3.13/c-api/init.html#c.PyEval_SaveThread).15561557#### `Py_BEGIN_CRITICAL_SECTION(op)`15581559Захватывает объектную блокировку для объекта *op* и начинает критическую секцию.15601561В сборке free-threaded этот макрос раскрывается в:15621563```c1564{1565    PyCriticalSection _py_cs;1566    PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))1567```15681569В сборке по умолчанию этот макрос раскрывается в `{`.15701571Добавлено в версии 3.13.15721573#### `Py_END_CRITICAL_SECTION()`15741575Завершает критическую секцию и освобождает блокировку объекта.15761577В сборке free-threaded этот макрос раскрывается в:15781579```c1580    PyCriticalSection_End(&_py_cs);1581}1582```15831584В сборке по умолчанию этот макрос раскрывается в `}`.15851586Добавлено в версии 3.13.15871588#### `Py_BEGIN_CRITICAL_SECTION2(a, b)`15891590Захватывает блокировки для объектов *a* и *b* и начинает критическую секцию. Блокировки захватываются в согласованном порядке (сначала наименьший адрес), чтобы избежать взаимоблокировок из-за порядка блокировок.15911592В сборке free-threaded этот макрос раскрывается в:15931594```c1595{1596    PyCriticalSection2 _py_cs2;1597    PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))1598```15991600В сборке по умолчанию этот макрос раскрывается в `{`.16011602Добавлено в версии 3.13.16031604#### `Py_END_CRITICAL_SECTION2()`16051606Завершает критическую секцию и освобождает блокировки объектов.16071608В сборке free-threaded этот макрос раскрывается в:16091610```c1611    PyCriticalSection2_End(&_py_cs2);1612}1613```16141615В сборке по умолчанию этот макрос раскрывается в `}`.16161617Добавлено в версии 3.13.16181619### Устаревшие API блокировок16201621Эти API устарели с Python 3.13 с введением [`PyMutex`](https://python-all.ru/3.13/c-api/init.html#c.PyMutex).16221623Изменено в версии 3.15: Теперь эти API представляют собой простую обёртку вокруг `PyMutex`.16241625#### `type PyThread_type_lock`16261627Указатель на блокировку взаимного исключения.16281629#### `type PyLockStatus`16301631Результат захвата блокировки с таймаутом.16321633#### `enumerator PY_LOCK_FAILURE`16341635Не удалось захватить блокировку.16361637#### `enumerator PY_LOCK_ACQUIRED`16381639Блокировка успешно захвачена.16401641#### `enumerator PY_LOCK_INTR`16421643Захват блокировки прерван сигналом.16441645#### `PyThread_type_lock PyThread_allocate_lock(void)`16461647*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*16481649Выделить новую блокировку.16501651В случае успеха функция возвращает блокировку; в случае неудачи возвращает `0` без установленного исключения.16521653Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).16541655Изменено в версии 3.15: Теперь эта функция всегда использует [`PyMutex`](https://python-all.ru/3.13/c-api/init.html#c.PyMutex). В предыдущих версиях использовалась блокировка, предоставляемая операционной системой.16561657#### `void PyThread_free_lock(PyThread_type_lock lock)`16581659*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*16601661Уничтожить *блокировку*. Блокировка не должна удерживаться ни одним потоком при вызове этой функции.16621663Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).16641665#### `PyLockStatus PyThread_acquire_lock_timed(PyThread_type_lock lock, long long microseconds, int intr_flag)`16661667*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*16681669Захватить *блокировку* с таймаутом.16701671Будет ожидать *microseconds* микросекунд для захвата блокировки. Если таймаут истекает, функция возвращает [`PY_LOCK_FAILURE`](https://python-all.ru/3.13/c-api/init.html#c.PY_LOCK_FAILURE). Если *microseconds* равно `-1`, будет ожидать неопределённо долго, пока блокировка не будет освобождена.16721673Если *intr\_flag* равно `1`, захват блокировки может быть прерван сигналом, и в этом случае функция возвращает [`PY_LOCK_INTR`](https://python-all.ru/3.13/c-api/init.html#c.PY_LOCK_INTR). После прерывания ожидается, что вызывающая сторона вызовет [`Py_MakePendingCalls()`](https://python-all.ru/3.13/c-api/init.html#c.Py_MakePendingCalls) для передачи исключения в код Python.16741675Если блокировка успешно захвачена, функция возвращает [`PY_LOCK_ACQUIRED`](https://python-all.ru/3.13/c-api/init.html#c.PY_LOCK_ACQUIRED).16761677Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).16781679#### `int PyThread_acquire_lock(PyThread_type_lock lock, int waitflag)`16801681*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*16821683Захватить *блокировку*.16841685Если *waitflag* равно `1`, и другой поток в данный момент удерживает блокировку, эта функция будет ждать, пока блокировка не будет захвачена, и всегда будет возвращать `1`.16861687Если *waitflag* равно `0`, и другой поток удерживает блокировку, эта функция не будет ждать, а вернёт `0`. Если блокировка не удерживается никаким другим потоком, то эта функция захватит её и вернёт `1`.16881689В отличие от [`PyThread_acquire_lock_timed()`](https://python-all.ru/3.13/c-api/init.html#c.PyThread_acquire_lock_timed), захват блокировки не может быть прерван сигналом.16901691Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).16921693#### `int PyThread_release_lock(PyThread_type_lock lock)`16941695*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*16961697Освободить *блокировку*. Если *блокировка* не удерживается, то эта функция вызовет фатальную ошибку.16981699Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17001701## API потоков операционной системы17021703#### `PYTHREAD_INVALID_THREAD_ID`17041705Страж-значение для недопустимого идентификатора потока.17061707В настоящее время эквивалентно `(unsigned long)-1`.17081709#### `unsigned long PyThread_start_new_thread(void (*func)(void*), void *arg)`17101711*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17121713Запускает функцию *func* в новом потоке с аргументом *arg*. Полученный поток не предназначен для ожидания завершения.17141715*func* не должна быть `NULL`, но *arg* может быть `NULL`.17161717При успехе эта функция возвращает идентификатор нового потока; при неудаче возвращает [`PYTHREAD_INVALID_THREAD_ID`](https://python-all.ru/3.13/c-api/init.html#c.PYTHREAD_INVALID_THREAD_ID).17181719Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17201721#### `unsigned long PyThread_get_thread_ident(void)`17221723*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17241725Возвращает идентификатор текущего потока, который никогда не будет равен нулю.17261727Эта функция не может завершиться ошибкой, и вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17281729> **См. также**1730>1731> [`threading.get_ident()`](https://python-all.ru/3.13/library/threading.html#threading.get_ident)17321733#### `PyObject *PyThread_GetInfo(void)`17341735*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.3.*17361737Получает общую информацию о текущем потоке в виде объекта [структурной последовательности](https://python-all.ru/3.13/c-api/tuple.html#struct-sequence-objects). Эта информация доступна как [`sys.thread_info`](https://python-all.ru/3.13/library/sys.html#sys.thread_info) в Python.17381739В случае успеха возвращается новая [сильная ссылка](https://python-all.ru/3.13/glossary.html#term-strong-reference) на информацию о потоке; в случае неудачи возвращается `NULL` с установленным исключением.17401741Вызывающий должен удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17421743#### `PY_HAVE_THREAD_NATIVE_ID`17441745Этот макрос определён, когда система поддерживает нативные идентификаторы потоков.17461747#### `unsigned long PyThread_get_thread_native_id(void)`17481749*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) на платформах с нативными идентификаторами потоков.*17501751Возвращает нативный идентификатор текущего потока, назначенный ядром операционной системы; это значение никогда не бывает меньше нуля.17521753Эта функция доступна, только если определён [`PY_HAVE_THREAD_NATIVE_ID`](https://python-all.ru/3.13/c-api/init.html#c.PY_HAVE_THREAD_NATIVE_ID).17541755Эта функция не может завершиться ошибкой, и вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17561757> **См. также**1758>1759> [`threading.get_native_id()`](https://python-all.ru/3.13/library/threading.html#threading.get_native_id)17601761#### `void PyThread_exit_thread(void)`17621763*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17641765Завершает текущий поток. Эта функция обычно считается небезопасной, и её следует избегать. Она сохранена исключительно для обратной совместимости.17661767Эту функцию безопасно вызывать, только если все функции в полном стеке вызовов написаны так, чтобы допускать это безопасно.17681769> **Предупреждение**1770>1771> Если текущая система использует потоки POSIX (также известные как «pthreads»), эта функция вызывает *[pthread\_exit(3)](https://python-all.ru/3.13/c-api/init.html)*, которая пытается развернуть стек и вызвать деструкторы C++ в некоторых реализациях libc. Однако, если достигается функция `noexcept`, это может завершить процесс. Другие системы, такие как macOS, выполняют развёртывание.1772>1773> В Windows эта функция вызывает `_endthreadex()`, которая уничтожает поток без вызова деструкторов C++.1774>1775> В любом случае существует риск повреждения стека потока.17761777#### `void PyThread_init_thread(void)`17781779*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17801781Инициализирует API `PyThread*`. Python выполняет эту функцию автоматически, поэтому нет особой необходимости вызывать её из расширяющего модуля.17821783#### `int PyThread_set_stacksize(size_t size)`17841785*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17861787Устанавливает размер стека текущего потока в *size* байт.17881789Эта функция возвращает `0` при успехе, `-1`, если *size* некорректен, или `-2`, если система не поддерживает изменение размера стека. Эта функция не устанавливает исключения.17901791Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).17921793#### `size_t PyThread_get_stacksize(void)`17941795*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*17961797Возвращает размер стека текущего потока в байтах или `0`, если используется размер стека по умолчанию для системы.17981799Вызывающему не нужно удерживать [GIL](https://python-all.ru/3.13/glossary.html#term-GIL).1800