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

  • 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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

intPy_FrozenFlag¶

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

Private flag used by_freeze_module andfrozenmain programs.

Deprecated since version 3.12, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, 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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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

Note that Python will do a best effort at freeing all memory allocated by the Pythoninterpreter. Therefore, any C-Extension should make sure to correctly clean up allof the previously allocated PyObjects before using them in subsequent calls toPy_Initialize(). Otherwise it could introduce vulnerabilities and incorrectbehavior.

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. Interned strings will all be deallocated regardless of their reference count.Some memory allocated by extension modules may not be freed. Some extensions may notwork properly if their initialization routine is called more than once; this canhappen if an application callsPy_Initialize() andPy_FinalizeEx()more than once.Py_FinalizeEx() must not be called recursively fromwithin itself. Therefore, it must not be called by any code that may be runas part of the interpreter shutdown process, such asatexithandlers, object finalizers, or any code that may be run while flushing thestdout and stderr files.

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 is2 if the argument list does not represent a validPython command line, and otherwise the same asPy_RunMain().

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), the exit status of an unhandledSystemExit, or1for any other unhandled exception.

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:0,1, orthe status of aSystemExit, as specified above.

This function always finalizes the Python interpreter before it returns.

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.

There must be anattached thread state forinterp.

Added in version 3.13.

Cautions regarding runtime finalization¶

In the late stage ofinterpreter shutdown, after attempting to wait fornon-daemon threads to exit (though this can be interrupted byKeyboardInterrupt) and running theatexit functions, the runtimeis marked asfinalizing:Py_IsFinalizing() andsys.is_finalizing() return true. At this point, only thefinalizationthread that initiated finalization (typically the main thread) is allowed toacquire theGIL.

If any thread, other than the finalization thread, attempts to attach athread stateduring finalization, either explicitly orimplicitly, the thread entersa permanently blocked statewhere it remains until the program exits. In most cases this is harmless, but this can resultin deadlock if a later stage of finalization attempts to acquire a lock owned by theblocked thread, or otherwise waits on the blocked thread.

Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++finalizations further up the call stack when such threads were forcibly exitedhere in CPython 3.13 and earlier. The CPython runtimethread state C APIshave never had any error reporting or handling expectations atthread stateattachment time that would’ve allowed for graceful exit from this situation. Changing thatwould require new stable C APIs and rewriting the majority of C code in theCPython ecosystem to use those with error handling.

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 by 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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.

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, removed in version 3.15.