Before Python Initialization¶

In an application embedding Python, thePy_Initialize() function mustbe called before using any other Python/C API functions; with the exception ofa few functions and theglobal configuration variables.

The following functions can be safely called before Python is initialized:

• Functions that initialize the interpreter:

  • Py_Initialize()

  • Py_InitializeEx()

  • Py_InitializeFromConfig()

  • Py_BytesMain()

  • Py_Main()

  • the runtime pre-initialization functions covered inPython Initialization Configuration

• Configuration functions:

  • PyImport_AppendInittab()

  • PyImport_ExtendInittab()

  • PyInitFrozenExtensions()

  • PyMem_SetAllocator()

  • PyMem_SetupDebugHooks()

  • PyObject_SetArenaAllocator()

  • Py_SetProgramName()

  • Py_SetPythonHome()

  • PySys_ResetWarnOptions()

  • the configuration functions covered inPython Initialization Configuration

• Informative functions:

  • Py_IsInitialized()

  • PyMem_GetAllocator()

  • PyObject_GetArenaAllocator()

  • Py_GetBuildInfo()

  • Py_GetCompiler()

  • Py_GetCopyright()

  • Py_GetPlatform()

  • Py_GetVersion()

  • Py_IsInitialized()

• Utilities:

  • Py_DecodeLocale()

  • the status reporting and utility functions covered inPython Initialization Configuration

• Memory allocators:

  • PyMem_RawMalloc()

  • PyMem_RawRealloc()

  • PyMem_RawCalloc()

  • PyMem_RawFree()

• Synchronization:

  • PyMutex_Lock()

  • PyMutex_Unlock()

Global configuration variables¶

Python has variables for the global configuration to control different featuresand options. By default, these flags are controlled bycommand lineoptions.

When a flag is set by an option, the value of the flag is the number of timesthat the option was set. For example,-b setsPy_BytesWarningFlagto 1 and-bb setsPy_BytesWarningFlag to 2.

intPy_BytesWarningFlag¶

This API is kept for backward compatibility: settingPyConfig.bytes_warning should be used instead, seePythonInitialization Configuration.

Issue a warning when comparingbytes orbytearray withstr orbytes withint. Issue an error if greateror equal to2.

Set by the-b option.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_DebugFlag¶

This API is kept for backward compatibility: settingPyConfig.parser_debug should be used instead, seePythonInitialization Configuration.

Turn on parser debugging output (for expert only, depending on compilationoptions).

Set by the-d option and thePYTHONDEBUG environmentvariable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_DontWriteBytecodeFlag¶

This API is kept for backward compatibility: settingPyConfig.write_bytecode should be used instead, seePythonInitialization Configuration.

If set to non-zero, Python won’t try to write.pyc files on theimport of source modules.

Set by the-B option and thePYTHONDONTWRITEBYTECODEenvironment variable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_FrozenFlag¶

This API is kept for backward compatibility: settingPyConfig.pathconfig_warnings should be used instead, seePython Initialization Configuration.

Suppress error messages when calculating the module search path inPy_GetPath().

Private flag used by_freeze_module andfrozenmain programs.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_HashRandomizationFlag¶

This API is kept for backward compatibility: settingPyConfig.hash_seed andPyConfig.use_hash_seed shouldbe used instead, seePython Initialization Configuration.

Set to1 if thePYTHONHASHSEED environment variable is set toa non-empty string.

If the flag is non-zero, read thePYTHONHASHSEED environmentvariable to initialize the secret hash seed.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_IgnoreEnvironmentFlag¶

This API is kept for backward compatibility: settingPyConfig.use_environment should be used instead, seePython Initialization Configuration.

Ignore allPYTHON* environment variables, e.g.PYTHONPATH andPYTHONHOME, that might be set.

Set by the-E and-I options.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_InspectFlag¶

This API is kept for backward compatibility: settingPyConfig.inspect should be used instead, seePython Initialization Configuration.

When a script is passed as first argument or the-c option is used,enter interactive mode after executing the script or the command, even whensys.stdin does not appear to be a terminal.

Set by the-i option and thePYTHONINSPECT environmentvariable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_InteractiveFlag¶

This API is kept for backward compatibility: settingPyConfig.interactive should be used instead, seePython Initialization Configuration.

Set by the-i option.

Deprecated since version 3.12, will be removed in version 3.15.

intPy_IsolatedFlag¶

This API is kept for backward compatibility: settingPyConfig.isolated should be used instead, seePython Initialization Configuration.

Run Python in isolated mode. In isolated modesys.path containsneither the script’s directory nor the user’s site-packages directory.

Set by the-I option.

Added in version 3.4.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_LegacyWindowsFSEncodingFlag¶

This API is kept for backward compatibility: settingPyPreConfig.legacy_windows_fs_encoding should be used instead, seePython Initialization Configuration.

If the flag is non-zero, use thembcs encoding withreplace errorhandler, instead of the UTF-8 encoding withsurrogatepass error handler,for thefilesystem encoding and error handler.

Set to1 if thePYTHONLEGACYWINDOWSFSENCODING environmentvariable is set to a non-empty string.

SeePEP 529 for more details.

Availability: Windows.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_LegacyWindowsStdioFlag¶

This API is kept for backward compatibility: settingPyConfig.legacy_windows_stdio should be used instead, seePython Initialization Configuration.

If the flag is non-zero, useio.FileIO instead ofio._WindowsConsoleIO forsys standard streams.

Set to1 if thePYTHONLEGACYWINDOWSSTDIO environmentvariable is set to a non-empty string.

SeePEP 528 for more details.

Availability: Windows.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_NoSiteFlag¶

This API is kept for backward compatibility: settingPyConfig.site_import should be used instead, seePython Initialization Configuration.

Disable the import of the modulesite and the site-dependentmanipulations ofsys.path that it entails. Also disable thesemanipulations ifsite is explicitly imported later (callsite.main() if you want them to be triggered).

Set by the-S option.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_NoUserSiteDirectory¶

This API is kept for backward compatibility: settingPyConfig.user_site_directory should be used instead, seePython Initialization Configuration.

Don’t add theusersite-packagesdirectory tosys.path.

Set by the-s and-I options, and thePYTHONNOUSERSITE environment variable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_OptimizeFlag¶

This API is kept for backward compatibility: settingPyConfig.optimization_level should be used instead, seePython Initialization Configuration.

Set by the-O option and thePYTHONOPTIMIZE environmentvariable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_QuietFlag¶

This API is kept for backward compatibility: settingPyConfig.quiet should be used instead, seePythonInitialization Configuration.

Don’t display the copyright and version messages even in interactive mode.

Set by the-q option.

Added in version 3.2.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_UnbufferedStdioFlag¶

This API is kept for backward compatibility: settingPyConfig.buffered_stdio should be used instead, seePythonInitialization Configuration.

Force the stdout and stderr streams to be unbuffered.

Set by the-u option and thePYTHONUNBUFFEREDenvironment variable.

Deprecated since version 3.12, will be removed in version 3.14.

intPy_VerboseFlag¶

This API is kept for backward compatibility: settingPyConfig.verbose should be used instead, seePythonInitialization Configuration.

Print a message each time a module is initialized, showing the place(filename or built-in module) from which it is loaded. If greater or equalto2, print a message for each file that is checked for whensearching for a module. Also provides information on module cleanup at exit.

Set by the-v option and thePYTHONVERBOSE environmentvariable.

Deprecated since version 3.12, will be removed in version 3.14.

Initializing and finalizing the interpreter¶

voidPy_Initialize()¶

Part of theStable ABI.

Initialize the Python interpreter. In an application embedding Python,this should be called before using any other Python/C API functions; seeBefore Python Initialization for the few exceptions.

This initializes the table of loaded modules (sys.modules), and createsthe fundamental modulesbuiltins,__main__ andsys.It also initializes the module search path (sys.path). It does not setsys.argv; use thePython Initialization ConfigurationAPI for that. This is a no-op when called for a second time (without callingPy_FinalizeEx() first). There is no return value; it is a fatalerror if the initialization fails.

UsePy_InitializeFromConfig() to customize thePython Initialization Configuration.

Note

On Windows, changes the console mode fromO_TEXT toO_BINARY,which will also affect non-Python uses of the console using the C Runtime.

voidPy_InitializeEx(intinitsigs)¶

Part of theStable ABI.

This function works likePy_Initialize() ifinitsigs is1. Ifinitsigs is0, it skips initialization registration of signal handlers,which may be useful when CPython is embedded as part of a larger application.

UsePy_InitializeFromConfig() to customize thePython Initialization Configuration.

PyStatusPy_InitializeFromConfig(constPyConfig*config)¶

Initialize Python fromconfig configuration, as described inInitialization with PyConfig.

See thePython Initialization Configuration section for details on pre-initializing theinterpreter, populating the runtime configuration structure, and queryingthe returned status structure.

intPy_IsInitialized()¶

Part of theStable ABI.

Return true (nonzero) when the Python interpreter has been initialized, false(zero) if not. AfterPy_FinalizeEx() is called, this returns false untilPy_Initialize() is called again.

intPy_IsFinalizing()¶

Part of theStable ABI since version 3.13.

Return true (non-zero) if the main Python interpreter isshutting down. Return false (zero) otherwise.

Added in version 3.13.

intPy_FinalizeEx()¶

Part of theStable ABI since version 3.6.

Undo all initializations made byPy_Initialize() and subsequent use ofPython/C API functions, and destroy all sub-interpreters (seePy_NewInterpreter() below) that were created and not yet destroyed sincethe last call toPy_Initialize(). Ideally, this frees all memoryallocated by the Python interpreter. This is a no-op when called for a secondtime (without callingPy_Initialize() again first).

Since this is the reverse ofPy_Initialize(), it should be calledin the same thread with the same interpreter active. That meansthe main thread and the main interpreter.This should never be called whilePy_RunMain() is running.

Normally the return value is0.If there were errors during finalization (flushing buffered data),-1 is returned.

This function is provided for a number of reasons. An embedding applicationmight want to restart Python without having to restart the application itself.An application that has loaded the Python interpreter from a dynamicallyloadable library (or DLL) might want to free all memory allocated by Pythonbefore unloading the DLL. During a hunt for memory leaks in an application adeveloper might want to free all memory allocated by Python before exiting fromthe application.

Bugs and caveats: The destruction of modules and objects in modules is donein random order; this may cause destructors (__del__() methods) to failwhen they depend on other objects (even functions) or modules. Dynamicallyloaded extension modules loaded by Python are not unloaded. Small amounts ofmemory allocated by the Python interpreter may not be freed (if you find a leak,please report it). Memory tied up in circular references between objects is notfreed. Some memory allocated by extension modules may not be freed. Someextensions may not work properly if their initialization routine is called morethan once; this can happen if an application callsPy_Initialize() andPy_FinalizeEx() more than once.

Raises anauditing eventcpython._PySys_ClearAuditHooks with no arguments.

Added in version 3.6.

voidPy_Finalize()¶

Part of theStable ABI.

This is a backwards-compatible version ofPy_FinalizeEx() thatdisregards the return value.

intPy_BytesMain(intargc,char**argv)¶

Part of theStable ABI since version 3.8.

Similar toPy_Main() butargv is an array of bytes strings,allowing the calling application to delegate the text decoding step tothe CPython runtime.

Added in version 3.8.

intPy_Main(intargc,wchar_t**argv)¶

Part of theStable ABI.

The main program for the standard interpreter, encapsulating a fullinitialization/finalization cycle, as well as additionalbehaviour to implement reading configurations settings from the environmentand command line, and then executing__main__ in accordance withCommand line.

This is made available for programs which wish to support the full CPythoncommand line interface, rather than just embedding a Python runtime in alarger application.

Theargc andargv parameters are similar to those which are passed to aC program’smain() function, except that theargv entries are firstconverted towchar_t usingPy_DecodeLocale(). It is alsoimportant to note that the argument list entries may be modified to point tostrings other than those passed in (however, the contents of the stringspointed to by the argument list are not modified).

The return value will be0 if the interpreter exits normally (i.e.,without an exception),1 if the interpreter exits due to an exception,or2 if the argument list does not represent a valid Python commandline.

Note that if an otherwise unhandledSystemExit is raised, thisfunction will not return1, but exit the process, as long asPy_InspectFlag is not set. IfPy_InspectFlag is set, execution willdrop into the interactive Python prompt, at which point a second otherwiseunhandledSystemExit will still exit the process, while any othermeans of exiting will set the return value as described above.

In terms of the CPython runtime configuration APIs documented in theruntime configuration section (and without accountingfor error handling),Py_Main is approximately equivalent to:

PyConfigconfig;PyConfig_InitPythonConfig(&config);PyConfig_SetArgv(&config,argc,argv);Py_InitializeFromConfig(&config);PyConfig_Clear(&config);Py_RunMain();

In normal usage, an embedding application will call this functioninstead of callingPy_Initialize(),Py_InitializeEx() orPy_InitializeFromConfig() directly, and all settings will be appliedas described elsewhere in this documentation. If this function is insteadcalledafter a preceding runtime initialization API call, then exactlywhich environmental and command line configuration settings will be updatedis version dependent (as it depends on which settings correctly supportbeing modified after they have already been set once when the runtime wasfirst initialized).

intPy_RunMain(void)¶

Executes the main module in a fully configured CPython runtime.

Executes the command (PyConfig.run_command), the script(PyConfig.run_filename) or the module(PyConfig.run_module) specified on the command line or in theconfiguration. If none of these values are set, runs the interactive Pythonprompt (REPL) using the__main__ module’s global namespace.

IfPyConfig.inspect is not set (the default), the return valuewill be0 if the interpreter exits normally (that is, without raisingan exception), or1 if the interpreter exits due to an exception. If anotherwise unhandledSystemExit is raised, the function will immediatelyexit the process instead of returning1.

IfPyConfig.inspect is set (such as when the-i optionis used), rather than returning when the interpreter exits, execution willinstead resume in an interactive Python prompt (REPL) using the__main__module’s global namespace. If the interpreter exited with an exception, itis immediately raised in the REPL session. The function return value isthen determined by the way theREPL session terminates: returning0if the session terminates without raising an unhandled exception, exitingimmediately for an unhandledSystemExit, and returning1 forany other unhandled exception.

This function always finalizes the Python interpreter regardless of whetherit returns a value or immediately exits the process due to an unhandledSystemExit exception.

SeePython Configuration for an example of acustomized Python that always runs in isolated mode usingPy_RunMain().

intPyUnstable_AtExit(PyInterpreterState*interp,void(*func)(void*),void*data)¶

This isUnstable API. It may change without warning in minor releases.

Register anatexit callback for the target interpreterinterp.This is similar toPy_AtExit(), but takes an explicit interpreter anddata pointer for the callback.

TheGIL must be held forinterp.

Added in version 3.13.

Process-wide parameters¶

voidPy_SetProgramName(constwchar_t*name)¶

Part of theStable ABI.

This API is kept for backward compatibility: settingPyConfig.program_name should be used instead, seePythonInitialization Configuration.

This function should be called beforePy_Initialize() is called forthe first time, if it is called at all. It tells the interpreter the valueof theargv[0] argument to themain() function of the program(converted to wide characters).This is used byPy_GetPath() and some other functions below to findthe Python run-time libraries relative to the interpreter executable. Thedefault value is'python'. The argument should point to azero-terminated wide character string in static storage whose contents will notchange for the duration of the program’s execution. No code in the Pythoninterpreter will change the contents of this storage.

UsePy_DecodeLocale() to decode a bytes string to get awchar_t* string.

Deprecated since version 3.11.

wchar_t*Py_GetProgramName()¶

Part of theStable ABI.

Return the program name set withPyConfig.program_name, or the default.The returned string points into static storage; the caller should not modify itsvalue.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:Getsys.executable instead.

wchar_t*Py_GetPrefix()¶

Part of theStable ABI.

Return theprefix for installed platform-independent files. This is derivedthrough a number of complicated rules from the program name set withPyConfig.program_name and some environment variables; for example, if theprogram name is'/usr/local/bin/python', the prefix is'/usr/local'. Thereturned string points into static storage; the caller should not modify itsvalue. This corresponds to theprefix variable in the top-levelMakefile and the--prefix argument to theconfigurescript at build time. The value is available to Python code assys.base_prefix.It is only useful on Unix. See also the next function.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:Getsys.base_prefix instead, orsys.prefix ifvirtual environments need to be handled.

wchar_t*Py_GetExecPrefix()¶

Part of theStable ABI.

Return theexec-prefix for installed platform-dependent files. This isderived through a number of complicated rules from the program name set withPyConfig.program_name and some environment variables; for example, if theprogram name is'/usr/local/bin/python', the exec-prefix is'/usr/local'. The returned string points into static storage; the callershould not modify its value. This corresponds to theexec_prefixvariable in the top-levelMakefile and the--exec-prefixargument to theconfigure script at build time. The value isavailable to Python code assys.base_exec_prefix. It is only useful onUnix.

Background: The exec-prefix differs from the prefix when platform dependentfiles (such as executables and shared libraries) are installed in a differentdirectory tree. In a typical installation, platform dependent files may beinstalled in the/usr/local/plat subtree while platform independent maybe installed in/usr/local.

Generally speaking, a platform is a combination of hardware and softwarefamilies, e.g. Sparc machines running the Solaris 2.x operating system areconsidered the same platform, but Intel machines running Solaris 2.x are anotherplatform, and Intel machines running Linux are yet another platform. Differentmajor revisions of the same operating system generally also form differentplatforms. Non-Unix operating systems are a different story; the installationstrategies on those systems are so different that the prefix and exec-prefix aremeaningless, and set to the empty string. Note that compiled Python bytecodefiles are platform independent (but not independent from the Python version bywhich they were compiled!).

System administrators will know how to configure themount orautomount programs to share/usr/local between platformswhile having/usr/local/plat be a different filesystem for eachplatform.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:Getsys.base_exec_prefix instead, orsys.exec_prefix ifvirtual environments need to be handled.

wchar_t*Py_GetProgramFullPath()¶

Part of theStable ABI.

Return the full program name of the Python executable; this is computed as aside-effect of deriving the default module search path from the program name(set byPyConfig.program_name). The returned string points intostatic storage; the caller should not modify its value. The value is availableto Python code assys.executable.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:Getsys.executable instead.

wchar_t*Py_GetPath()¶

Part of theStable ABI.

Return the default module search path; this is computed from the program name(set byPyConfig.program_name) and some environment variables.The returned string consists of a series of directory names separated by aplatform dependent delimiter character. The delimiter character is':'on Unix and macOS,';' on Windows. The returned string points intostatic storage; the caller should not modify its value. The listsys.path is initialized with this value on interpreter startup; itcan be (and usually is) modified later to change the search path for loadingmodules.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:Getsys.path instead.

constchar*Py_GetVersion()¶

Part of theStable ABI.

Return the version of this Python interpreter. This is a string that lookssomething like

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

The first word (up to the first space character) is the current Python version;the first characters are the major and minor version separated by aperiod. The returned string points into static storage; the caller should notmodify its value. The value is available to Python code assys.version.

See also thePy_Version constant.

constchar*Py_GetPlatform()¶

Part of theStable ABI.

Return the platform identifier for the current platform. On Unix, this isformed from the “official” name of the operating system, converted to lowercase, followed by the major revision number; e.g., for Solaris 2.x, which isalso known as SunOS 5.x, the value is'sunos5'. On macOS, it is'darwin'. On Windows, it is'win'. The returned string points intostatic storage; the caller should not modify its value. The value is availableto Python code assys.platform.

constchar*Py_GetCopyright()¶

Part of theStable ABI.

Return the official copyright string for the current Python version, for example

'Copyright1991-1995StichtingMathematischCentrum,Amsterdam'

The returned string points into static storage; the caller should not modify itsvalue. The value is available to Python code assys.copyright.

constchar*Py_GetCompiler()¶

Part of theStable ABI.

Return an indication of the compiler used to build the current Python version,in square brackets, for example:

"[GCC 2.7.2.2]"

The returned string points into static storage; the caller should not modify itsvalue. The value is available to Python code as part of the variablesys.version.

constchar*Py_GetBuildInfo()¶

Part of theStable ABI.

Return information about the sequence number and build date and time of thecurrent Python interpreter instance, for example

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

The returned string points into static storage; the caller should not modify itsvalue. The value is available to Python code as part of the variablesys.version.

voidPySys_SetArgvEx(intargc,wchar_t**argv,intupdatepath)¶

Part of theStable ABI.

This API is kept for backward compatibility: settingPyConfig.argv,PyConfig.parse_argv andPyConfig.safe_path should be used instead, seePythonInitialization Configuration.

Setsys.argv based onargc andargv. These parameters aresimilar to those passed to the program’smain() function with thedifference that the first entry should refer to the script file to beexecuted rather than the executable hosting the Python interpreter. If thereisn’t a script that will be run, the first entry inargv can be an emptystring. If this function fails to initializesys.argv, a fatalcondition is signalled usingPy_FatalError().

Ifupdatepath is zero, this is all the function does. Ifupdatepathis non-zero, the function also modifiessys.path according to thefollowing algorithm:

• If the name of an existing script is passed inargv[0], the absolutepath of the directory where the script is located is prepended tosys.path.

• Otherwise (that is, ifargc is0 orargv[0] doesn’t pointto an existing file name), an empty string is prepended tosys.path, which is the same as prepending the current workingdirectory (".").

UsePy_DecodeLocale() to decode a bytes string to get awchar_t* string.

See alsoPyConfig.orig_argv andPyConfig.argvmembers of thePython Initialization Configuration.

Note

It is recommended that applications embedding the Python interpreterfor purposes other than executing a single script pass0 asupdatepath,and updatesys.path themselves if desired.SeeCVE 2008-5983.

On versions before 3.1.3, you can achieve the same effect by manuallypopping the firstsys.path element after having calledPySys_SetArgv(), for example using:

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

Added in version 3.1.3.

Deprecated since version 3.11.

voidPySys_SetArgv(intargc,wchar_t**argv)¶

Part of theStable ABI.

This API is kept for backward compatibility: settingPyConfig.argv andPyConfig.parse_argv should be usedinstead, seePython Initialization Configuration.

This function works likePySys_SetArgvEx() withupdatepath setto1 unless thepython interpreter was started with the-I.

UsePy_DecodeLocale() to decode a bytes string to get awchar_t* string.

See alsoPyConfig.orig_argv andPyConfig.argvmembers of thePython Initialization Configuration.

Changed in version 3.4:Theupdatepath value depends on-I.

Deprecated since version 3.11.

voidPy_SetPythonHome(constwchar_t*home)¶

Part of theStable ABI.

This API is kept for backward compatibility: settingPyConfig.home should be used instead, seePythonInitialization Configuration.

Set the default “home” directory, that is, the location of the standardPython libraries. SeePYTHONHOME for the meaning of theargument string.

The argument should point to a zero-terminated character string in staticstorage whose contents will not change for the duration of the program’sexecution. No code in the Python interpreter will change the contents ofthis storage.

UsePy_DecodeLocale() to decode a bytes string to get awchar_t* string.

Deprecated since version 3.11.

wchar_t*Py_GetPythonHome()¶

Part of theStable ABI.

Return the default “home”, that is, the value set byPyConfig.home, or the value of thePYTHONHOMEenvironment variable if it is set.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Changed in version 3.10:It now returnsNULL if called beforePy_Initialize().

Deprecated since version 3.13, will be removed in version 3.15:GetPyConfig.home orPYTHONHOME environmentvariable instead.

Thread State and the Global Interpreter Lock¶

The Python interpreter is not fully thread-safe. In order to supportmulti-threaded Python programs, there’s a global lock, called theglobalinterpreter lock orGIL, that must be held by the current thread beforeit can safely access Python objects. Without the lock, even the simplestoperations could cause problems in a multi-threaded program: for example, whentwo threads simultaneously increment the reference count of the same object, thereference count could end up being incremented only once instead of twice.

Therefore, the rule exists that only the thread that has acquired theGIL may operate on Python objects or call Python/C API functions.In order to emulate concurrency of execution, the interpreter regularlytries to switch threads (seesys.setswitchinterval()). The lock is alsoreleased around potentially blocking I/O operations like reading or writinga file, so that other Python threads can run in the meantime.

The Python interpreter keeps some thread-specific bookkeeping informationinside a data structure calledPyThreadState. There’s also oneglobal variable pointing to the currentPyThreadState: it canbe retrieved usingPyThreadState_Get().

Savethethreadstateinalocalvariable.Releasetheglobalinterpreterlock....DosomeblockingI/Ooperation...Reacquiretheglobalinterpreterlock.Restorethethreadstatefromthelocalvariable.

Py_BEGIN_ALLOW_THREADS...DosomeblockingI/Ooperation...Py_END_ALLOW_THREADS

PyThreadState*_save;_save=PyEval_SaveThread();...DosomeblockingI/Ooperation...PyEval_RestoreThread(_save);

PyGILState_STATEgstate;gstate=PyGILState_Ensure();/* Perform Python actions here. */result=CallSomeFunction();/* evaluate result or handle exception *//* Release the thread. No Python API allowed beyond this point. */PyGILState_Release(gstate);

Sub-interpreter support¶

While in most uses, you will only embed a single Python interpreter, thereare cases where you need to create several independent interpreters in thesame process and perhaps even in the same thread. Sub-interpreters allowyou to do that.

The “main” interpreter is the first one created when the runtime initializes.It is usually the only Python interpreter in a process. Unlike sub-interpreters,the main interpreter has unique process-global responsibilities like signalhandling. It is also responsible for execution during runtime initialization andis usually the active interpreter during runtime finalization. ThePyInterpreterState_Main() function returns a pointer to its state.

You can switch between sub-interpreters using thePyThreadState_Swap()function. You can create and destroy them using the following functions:

typePyInterpreterConfig¶

Structure containing most parameters to configure a sub-interpreter.Its values are used only inPy_NewInterpreterFromConfig() andnever modified by the runtime.

Added in version 3.12.

Structure fields:

intuse_main_obmalloc¶

If this is0 then the sub-interpreter will use its own“object” allocator state.Otherwise it will use (share) the main interpreter’s.

If this is0 thencheck_multi_interp_extensionsmust be1 (non-zero).If this is1 thengilmust not bePyInterpreterConfig_OWN_GIL.

intallow_fork¶

If this is0 then the runtime will not support forking theprocess in any thread where the sub-interpreter is currently active.Otherwise fork is unrestricted.

Note that thesubprocess module still workswhen fork is disallowed.

intallow_exec¶

If this is0 then the runtime will not support replacing thecurrent process via exec (e.g.os.execv()) in any threadwhere the sub-interpreter is currently active.Otherwise exec is unrestricted.

Note that thesubprocess module still workswhen exec is disallowed.

intallow_threads¶

If this is0 then the sub-interpreter’sthreading modulewon’t create threads.Otherwise threads are allowed.

intallow_daemon_threads¶

If this is0 then the sub-interpreter’sthreading modulewon’t create daemon threads.Otherwise daemon threads are allowed (as long asallow_threads is non-zero).

intcheck_multi_interp_extensions¶

If this is0 then all extension modules may be imported,including legacy (single-phase init) modules,in any thread where the sub-interpreter is currently active.Otherwise only multi-phase init extension modules(seePEP 489) may be imported.(Also seePy_mod_multiple_interpreters.)

This must be1 (non-zero) ifuse_main_obmalloc is0.

intgil¶

This determines the operation of the GIL for the sub-interpreter.It may be one of the following:

PyInterpreterConfig_DEFAULT_GIL¶

Use the default selection (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL¶

Use (share) the main interpreter’s GIL.

PyInterpreterConfig_OWN_GIL¶

Use the sub-interpreter’s own GIL.

If this isPyInterpreterConfig_OWN_GIL thenPyInterpreterConfig.use_main_obmalloc must be0.

PyStatusPy_NewInterpreterFromConfig(PyThreadState**tstate_p,constPyInterpreterConfig*config)¶

Create a new sub-interpreter. This is an (almost) totally separate environmentfor the execution of Python code. In particular, the new interpreter hasseparate, independent versions of all imported modules, including thefundamental modulesbuiltins,__main__ andsys. Thetable of loaded modules (sys.modules) and the module search path(sys.path) are also separate. The new environment has nosys.argvvariable. It has new standard I/O stream file objectssys.stdin,sys.stdout andsys.stderr (however these refer to the same underlyingfile descriptors).

The givenconfig controls the options with which the interpreteris initialized.

Upon success,tstate_p will be set to the first thread statecreated in the newsub-interpreter. This thread state is made in the current thread state.Note that no actual thread is created; see the discussion of thread statesbelow. If creation of the new interpreter is unsuccessful,tstate_p is set toNULL;no exception is set since the exception state is stored in thecurrent thread state and there may not be a current thread state.

Like all other Python/C API functions, the global interpreter lockmust be held before calling this function and is still held when itreturns. Likewise a current thread state must be set on entry. Onsuccess, the returned thread state will be set as current. If thesub-interpreter is created with its own GIL then the GIL of thecalling interpreter will be released. When the function returns,the new interpreter’s GIL will be held by the current thread andthe previously interpreter’s GIL will remain released here.

Added in version 3.12.

Sub-interpreters are most effective when isolated from each other,with certain functionality restricted:

PyInterpreterConfigconfig={.use_main_obmalloc=0,.allow_fork=0,.allow_exec=0,.allow_threads=1,.allow_daemon_threads=0,.check_multi_interp_extensions=1,.gil=PyInterpreterConfig_OWN_GIL,};PyThreadState*tstate=NULL;PyStatusstatus=Py_NewInterpreterFromConfig(&tstate,&config);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}

Note that the config is used only briefly and does not get modified.During initialization the config’s values are converted into variousPyInterpreterState values. A read-only copy of the configmay be stored internally on thePyInterpreterState.

Extension modules are shared between (sub-)interpreters as follows:

• For modules using multi-phase initialization,e.g.PyModule_FromDefAndSpec(), a separate module object iscreated and initialized for each interpreter.Only C-level static and global variables are shared between thesemodule objects.

• For modules using single-phase initialization,e.g.PyModule_Create(), the first time a particular extensionis imported, it is initialized normally, and a (shallow) copy of itsmodule’s dictionary is squirreled away.When the same extension is imported by another (sub-)interpreter, a newmodule is initialized and filled with the contents of this copy; theextension’sinit function is not called.Objects in the module’s dictionary thus end up shared across(sub-)interpreters, which might cause unwanted behavior (seeBugs and caveats below).

  Note that this is different from what happens when an extension isimported after the interpreter has been completely re-initialized bycallingPy_FinalizeEx() andPy_Initialize(); in thatcase, the extension’sinitmodule functionis called again.As with multi-phase initialization, this means that only C-level staticand global variables are shared between these modules.

PyThreadState*Py_NewInterpreter(void)¶

Part of theStable ABI.

Create a new sub-interpreter. This is essentially just a wrapperaroundPy_NewInterpreterFromConfig() with a config thatpreserves the existing behavior. The result is an unisolatedsub-interpreter that shares the main interpreter’s GIL, allowsfork/exec, allows daemon threads, and allows single-phase initmodules.

voidPy_EndInterpreter(PyThreadState*tstate)¶

Part of theStable ABI.

Destroy the (sub-)interpreter represented by the given thread state.The given thread state must be the current thread state. See thediscussion of thread states below. When the call returns,the current thread state isNULL. All thread states associatedwith this interpreter are destroyed. The global interpreter lockused by the target interpreter must be held before calling thisfunction. No GIL is held when it returns.

Py_FinalizeEx() will destroy all sub-interpreters thathaven’t been explicitly destroyed at that point.

Asynchronous Notifications¶

A mechanism is provided to make asynchronous notifications to the maininterpreter thread. These notifications take the form of a functionpointer and a void pointer argument.

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

Part of theStable ABI.

Schedule a function to be called from the main interpreter thread. Onsuccess,0 is returned andfunc is queued for being called in themain thread. On failure,-1 is returned without setting any exception.

When successfully queued,func will beeventually called from themain interpreter thread with the argumentarg. It will be calledasynchronously with respect to normally running Python code, but withboth these conditions met:

• on abytecode boundary;

• with the main thread holding theglobal interpreter lock(func can therefore use the full C API).

func must return0 on success, or-1 on failure with an exceptionset.func won’t be interrupted to perform another asynchronousnotification recursively, but it can still be interrupted to switchthreads if the global interpreter lock is released.

This function doesn’t need a current thread state to run, and it doesn’tneed the global interpreter lock.

To call this function in a subinterpreter, the caller must hold the GIL.Otherwise, the functionfunc can be scheduled to be called from the wronginterpreter.

Warning

This is a low-level function, only useful for very special cases.There is no guarantee thatfunc will be called as quick aspossible. If the main thread is busy executing a system call,func won’t be called before the system call returns. Thisfunction is generallynot suitable for calling Python code fromarbitrary C threads. Instead, use thePyGILState API.

Added in version 3.1.

Changed in version 3.9:If this function is called in a subinterpreter, the functionfunc isnow scheduled to be called from the subinterpreter, rather than beingcalled from the main interpreter. Each subinterpreter now has its ownlist of scheduled calls.

Profiling and Tracing¶

The Python interpreter provides some low-level support for attaching profilingand execution tracing facilities. These are used for profiling, debugging, andcoverage analysis tools.

This C interface allows the profiling or tracing code to avoid the overhead ofcalling through Python-level callable objects, making a direct C function callinstead. The essential attributes of the facility have not changed; theinterface allows trace functions to be installed per-thread, and the basicevents reported to the trace function are the same as had been reported to thePython-level trace functions in previous versions.

typedefint(*Py_tracefunc)(PyObject*obj,PyFrameObject*frame,intwhat,PyObject*arg)¶

The type of the trace function registered usingPyEval_SetProfile() andPyEval_SetTrace(). The first parameter is the object passed to theregistration function asobj,frame is the frame object to which the eventpertains,what is one of the constantsPyTrace_CALL,PyTrace_EXCEPTION,PyTrace_LINE,PyTrace_RETURN,PyTrace_C_CALL,PyTrace_C_EXCEPTION,PyTrace_C_RETURN,orPyTrace_OPCODE, andarg depends on the value ofwhat:

Value ofwhat	Meaning ofarg
PyTrace_CALL	AlwaysPy_None.
PyTrace_EXCEPTION	Exception information as returned bysys.exc_info().
PyTrace_LINE	AlwaysPy_None.
PyTrace_RETURN	Value being returned to the caller,orNULL if caused by an exception.
PyTrace_C_CALL	Function object being called.
PyTrace_C_EXCEPTION	Function object being called.
PyTrace_C_RETURN	Function object being called.
PyTrace_OPCODE	AlwaysPy_None.

intPyTrace_CALL¶

The value of thewhat parameter to aPy_tracefunc function when a newcall to a function or method is being reported, or a new entry into a generator.Note that the creation of the iterator for a generator function is not reportedas there is no control transfer to the Python bytecode in the correspondingframe.

intPyTrace_EXCEPTION¶

The value of thewhat parameter to aPy_tracefunc function when anexception has been raised. The callback function is called with this value forwhat when after any bytecode is processed after which the exception becomesset within the frame being executed. The effect of this is that as exceptionpropagation causes the Python stack to unwind, the callback is called uponreturn to each frame as the exception propagates. Only trace functions receivesthese events; they are not needed by the profiler.

intPyTrace_LINE¶

The value passed as thewhat parameter to aPy_tracefunc function(but not a profiling function) when a line-number event is being reported.It may be disabled for a frame by settingf_trace_lines to0 on that frame.

intPyTrace_RETURN¶

The value for thewhat parameter toPy_tracefunc functions when acall is about to return.

intPyTrace_C_CALL¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction is about to be called.

intPyTrace_C_EXCEPTION¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction has raised an exception.

intPyTrace_C_RETURN¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction has returned.

intPyTrace_OPCODE¶

The value for thewhat parameter toPy_tracefunc functions (but notprofiling functions) when a new opcode is about to be executed. This event isnot emitted by default: it must be explicitly requested by settingf_trace_opcodes to1 on the frame.

voidPyEval_SetProfile(Py_tracefuncfunc,PyObject*obj)¶

Set the profiler function tofunc. Theobj parameter is passed to thefunction as its first parameter, and may be any Python object, orNULL. Ifthe profile function needs to maintain state, using a different value forobjfor each thread provides a convenient and thread-safe place to store it. Theprofile function is called for all monitored events exceptPyTrace_LINEPyTrace_OPCODE andPyTrace_EXCEPTION.

See also thesys.setprofile() function.

The caller must hold theGIL.

voidPyEval_SetProfileAllThreads(Py_tracefuncfunc,PyObject*obj)¶

LikePyEval_SetProfile() but sets the profile function in all running threadsbelonging to the current interpreter instead of the setting it only on the current thread.

The caller must hold theGIL.

AsPyEval_SetProfile(), this function ignores any exceptions raised whilesetting the profile functions in all threads.

voidPyEval_SetTrace(Py_tracefuncfunc,PyObject*obj)¶

Set the tracing function tofunc. This is similar toPyEval_SetProfile(), except the tracing function does receive line-numberevents and per-opcode events, but does not receive any event related to C functionobjects being called. Any trace function registered usingPyEval_SetTrace()will not receivePyTrace_C_CALL,PyTrace_C_EXCEPTION orPyTrace_C_RETURN as a value for thewhat parameter.

See also thesys.settrace() function.

The caller must hold theGIL.

voidPyEval_SetTraceAllThreads(Py_tracefuncfunc,PyObject*obj)¶

LikePyEval_SetTrace() but sets the tracing function in all running threadsbelonging to the current interpreter instead of the setting it only on the current thread.

The caller must hold theGIL.

AsPyEval_SetTrace(), this function ignores any exceptions raised whilesetting the trace functions in all threads.

Reference tracing¶

typedefint(*PyRefTracer)(PyObject*,intevent,void*data)¶

The type of the trace function registered usingPyRefTracer_SetTracer().The first parameter is a Python object that has been just created (wheneventis set toPyRefTracer_CREATE) or about to be destroyed (wheneventis set toPyRefTracer_DESTROY). Thedata argument is the opaque pointerthat was provided whenPyRefTracer_SetTracer() was called.

intPyRefTracer_CREATE¶

The value for theevent parameter toPyRefTracer functions when a Pythonobject has been created.

intPyRefTracer_DESTROY¶

The value for theevent parameter toPyRefTracer functions when a Pythonobject has been destroyed.

intPyRefTracer_SetTracer(PyRefTracertracer,void*data)¶

Register a reference tracer function. The function will be called when a newPython has been created or when an object is going to be destroyed. Ifdata is provided it must be an opaque pointer that will be provided whenthe tracer function is called. Return0 on success. Set an exception andreturn-1 on error.

Not that tracer functionsmust not create Python objects inside orotherwise the call will be re-entrant. The tracer alsomust not clearany existing exception or set an exception. The GIL will be held every timethe tracer function is called.

The GIL must be held when calling this function.

PyRefTracerPyRefTracer_GetTracer(void**data)¶

Get the registered reference tracer function and the value of the opaque datapointer that was registered whenPyRefTracer_SetTracer() was called.If no tracer was registered this function will return NULL and will set thedata pointer to NULL.

The GIL must be held when calling this function.

Advanced Debugger Support¶

These functions are only intended to be used by advanced debugging tools.

PyInterpreterState*PyInterpreterState_Head()¶

Return the interpreter state object at the head of the list of all such objects.

PyInterpreterState*PyInterpreterState_Main()¶

Return the main interpreter state object.

PyInterpreterState*PyInterpreterState_Next(PyInterpreterState*interp)¶

Return the next interpreter state object afterinterp from the list of allsuch objects.

PyThreadState*PyInterpreterState_ThreadHead(PyInterpreterState*interp)¶

Return the pointer to the firstPyThreadState object in the list ofthreads associated with the interpreterinterp.

PyThreadState*PyThreadState_Next(PyThreadState*tstate)¶

Return the next thread state object aftertstate from the list of all suchobjects belonging to the samePyInterpreterState object.

Thread Local Storage Support¶

The Python interpreter provides low-level support for thread-local storage(TLS) which wraps the underlying native TLS implementation to support thePython-level thread local storage API (threading.local). TheCPython C level APIs are similar to those offered by pthreads and Windows:use a thread key and functions to associate avoid* value perthread.

The GIL doesnot need to be held when calling these functions; they supplytheir own locking.

Note thatPython.h does not include the declaration of the TLS APIs,you need to includepythread.h to use thread-local storage.

Synchronization Primitives¶

The C-API provides a basic mutual exclusion lock.

typePyMutex¶

A mutual exclusion lock. ThePyMutex should be initialized tozero to represent the unlocked state. For example:

PyMutexmutex={0};

Instances ofPyMutex should not be copied or moved. Both thecontents and address of aPyMutex are meaningful, and it mustremain at a fixed, writable location in memory.

Note

APyMutex currently occupies one byte, but the size should beconsidered unstable. The size may change in future Python releaseswithout a deprecation period.

Added in version 3.13.

voidPyMutex_Lock(PyMutex*m)¶

Lock mutexm. If another thread has already locked it, the callingthread will block until the mutex is unlocked. While blocked, the threadwill temporarily release theGIL if it is held.

Added in version 3.13.

voidPyMutex_Unlock(PyMutex*m)¶

Unlock mutexm. The mutex must be locked — otherwise, the function willissue a fatal error.

Added in version 3.13.

staticPyObject*set_field(MyObject*self,PyObject*value){Py_BEGIN_CRITICAL_SECTION(self);Py_SETREF(self->field,Py_XNewRef(value));Py_END_CRITICAL_SECTION();Py_RETURN_NONE;}