Example¶

Example of customized Python always running in isolated mode:

intmain(intargc,char**argv){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);config.isolated=1;/* Decode command line arguments.       Implicitly preinitialize Python (in isolated mode). */status=PyConfig_SetBytesArgv(&config,argc,argv);if(PyStatus_Exception(status)){gotoexception;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotoexception;}PyConfig_Clear(&config);returnPy_RunMain();exception:PyConfig_Clear(&config);if(PyStatus_IsExit(status)){returnstatus.exitcode;}/* Display the error message and exit the process with       non-zero exit code */Py_ExitStatusException(status);}

PyWideStringList¶

typePyWideStringList¶

List ofwchar_t* strings.

Iflength is non-zero,items must be non-NULL and all strings must benon-NULL.

Methods:

PyStatusPyWideStringList_Append(PyWideStringList*list,constwchar_t*item)¶

Appenditem tolist.

Python must be preinitialized to call this function.

PyStatusPyWideStringList_Insert(PyWideStringList*list,Py_ssize_tindex,constwchar_t*item)¶

Insertitem intolist atindex.

Ifindex is greater than or equal tolist length, appenditem tolist.

index must be greater than or equal to0.

Python must be preinitialized to call this function.

Structure fields:

Py_ssize_tlength¶

List length.

wchar_t**items¶

List items.

PyStatus¶

typePyStatus¶

Structure to store an initialization function status: success, erroror exit.

For an error, it can store the C function name which created the error.

Structure fields:

intexitcode¶

Exit code. Argument passed toexit().

constchar*err_msg¶

Error message.

constchar*func¶

Name of the function which created an error, can beNULL.

Functions to create a status:

PyStatusPyStatus_Ok(void)¶

Success.

PyStatusPyStatus_Error(constchar*err_msg)¶

Initialization error with a message.

err_msg must not beNULL.

PyStatusPyStatus_NoMemory(void)¶

Memory allocation failure (out of memory).

PyStatusPyStatus_Exit(intexitcode)¶

Exit Python with the specified exit code.

Functions to handle a status:

intPyStatus_Exception(PyStatusstatus)¶

Is the status an error or an exit? If true, the exception must behandled; by callingPy_ExitStatusException() for example.

intPyStatus_IsError(PyStatusstatus)¶

Is the result an error?

intPyStatus_IsExit(PyStatusstatus)¶

Is the result an exit?

voidPy_ExitStatusException(PyStatusstatus)¶

Callexit(exitcode) ifstatus is an exit. Print the errormessage and exit with a non-zero exit code ifstatus is an error. Mustonly be called ifPyStatus_Exception(status) is non-zero.

Example:

PyStatusalloc(void**ptr,size_tsize){*ptr=PyMem_RawMalloc(size);if(*ptr==NULL){returnPyStatus_NoMemory();}returnPyStatus_Ok();}intmain(intargc,char**argv){void*ptr;PyStatusstatus=alloc(&ptr,16);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}PyMem_Free(ptr);return0;}

PyPreConfig¶

typePyPreConfig¶

Structure used to preinitialize Python.

Function to initialize a preconfiguration:

voidPyPreConfig_InitPythonConfig(PyPreConfig*preconfig)¶

Initialize the preconfiguration withPython Configuration.

voidPyPreConfig_InitIsolatedConfig(PyPreConfig*preconfig)¶

Initialize the preconfiguration withIsolated Configuration.

Structure fields:

intallocator¶

Name of the Python memory allocators:

• PYMEM_ALLOCATOR_NOT_SET (0): don’t change memory allocators(use defaults).

• PYMEM_ALLOCATOR_DEFAULT (1):default memory allocators.

• PYMEM_ALLOCATOR_DEBUG (2):default memory allocators withdebug hooks.

• PYMEM_ALLOCATOR_MALLOC (3): usemalloc() of the C library.

• PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage ofmalloc() withdebug hooks.

• PYMEM_ALLOCATOR_PYMALLOC (5):Python pymalloc memoryallocator.

• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6):Python pymallocmemory allocator withdebug hooks.

• PYMEM_ALLOCATOR_MIMALLOC (6): usemimalloc, a fastmalloc replacement.

• PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): usemimalloc, a fastmalloc replacement withdebug hooks.

PYMEM_ALLOCATOR_PYMALLOC andPYMEM_ALLOCATOR_PYMALLOC_DEBUG arenot supported if Python isconfiguredusing--without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC andPYMEM_ALLOCATOR_MIMALLOC_DEBUG arenot supported if Python isconfiguredusing--without-mimalloc or if the underlying atomic support isn’tavailable.

SeeMemory Management.

Default:PYMEM_ALLOCATOR_NOT_SET.

intconfigure_locale¶

Set the LC_CTYPE locale to the user preferred locale.

If equals to0, setcoerce_c_locale andcoerce_c_locale_warn members to0.

See thelocale encoding.

Default:1 in Python config,0 in isolated config.

intcoerce_c_locale¶

If equals to2, coerce the C locale.

If equals to1, read the LC_CTYPE locale to decide if it should becoerced.

See thelocale encoding.

Default:-1 in Python config,0 in isolated config.

intcoerce_c_locale_warn¶

If non-zero, emit a warning if the C locale is coerced.

Default:-1 in Python config,0 in isolated config.

intdev_mode¶

Python Development Mode: seePyConfig.dev_mode.

Default:-1 in Python mode,0 in isolated mode.

intisolated¶

Isolated mode: seePyConfig.isolated.

Default:0 in Python mode,1 in isolated mode.

intlegacy_windows_fs_encoding¶

If non-zero:

• SetPyPreConfig.utf8_mode to0,

• SetPyConfig.filesystem_encoding to"mbcs",

• SetPyConfig.filesystem_errors to"replace".

Initialized from thePYTHONLEGACYWINDOWSFSENCODING environmentvariable value.

Only available on Windows.#ifdefMS_WINDOWS macro can be used forWindows specific code.

Default:0.

intparse_argv¶

If non-zero,Py_PreInitializeFromArgs() andPy_PreInitializeFromBytesArgs() parse theirargv argument thesame way the regular Python parses command line arguments: seeCommand Line Arguments.

Default:1 in Python config,0 in isolated config.

intuse_environment¶

Useenvironment variables? SeePyConfig.use_environment.

Default:1 in Python config and0 in isolated config.

intutf8_mode¶

If non-zero, enable thePython UTF-8 Mode.

Set to0 or1 by the-Xutf8 command line optionand thePYTHONUTF8 environment variable.

Also set to1 if theLC_CTYPE locale isC orPOSIX.

Default:-1 in Python config and0 in isolated config.

Preinitialize Python with PyPreConfig¶

The preinitialization of Python:

• Set the Python memory allocators (PyPreConfig.allocator)

• Configure the LC_CTYPE locale (locale encoding)

• Set thePython UTF-8 Mode(PyPreConfig.utf8_mode)

The current preconfiguration (PyPreConfig type) is stored in_PyRuntime.preconfig.

Functions to preinitialize Python:

PyStatusPy_PreInitialize(constPyPreConfig*preconfig)¶

Preinitialize Python frompreconfig preconfiguration.

preconfig must not beNULL.

PyStatusPy_PreInitializeFromBytesArgs(constPyPreConfig*preconfig,intargc,char*const*argv)¶

Preinitialize Python frompreconfig preconfiguration.

Parseargv command line arguments (bytes strings) ifparse_argv ofpreconfig is non-zero.

preconfig must not beNULL.

PyStatusPy_PreInitializeFromArgs(constPyPreConfig*preconfig,intargc,wchar_t*const*argv)¶

Preinitialize Python frompreconfig preconfiguration.

Parseargv command line arguments (wide strings) ifparse_argv ofpreconfig is non-zero.

preconfig must not beNULL.

The caller is responsible to handle exceptions (error or exit) usingPyStatus_Exception() andPy_ExitStatusException().

ForPython Configuration(PyPreConfig_InitPythonConfig()), if Python is initialized withcommand line arguments, the command line arguments must also be passed topreinitialize Python, since they have an effect on the pre-configurationlike encodings. For example, the-Xutf8 command line optionenables thePython UTF-8 Mode.

PyMem_SetAllocator() can be called afterPy_PreInitialize() andbeforePy_InitializeFromConfig() to install a custom memory allocator.It can be called beforePy_PreInitialize() ifPyPreConfig.allocator is set toPYMEM_ALLOCATOR_NOT_SET.

Python memory allocation functions likePyMem_RawMalloc() must not beused before the Python preinitialization, whereas calling directlymalloc()andfree() is always safe.Py_DecodeLocale() must not be calledbefore the Python preinitialization.

Example using the preinitialization to enablethePython UTF-8 Mode:

PyStatusstatus;PyPreConfigpreconfig;PyPreConfig_InitPythonConfig(&preconfig);preconfig.utf8_mode=1;status=Py_PreInitialize(&preconfig);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}/* at this point, Python speaks UTF-8 */Py_Initialize();/* ... use Python API here ... */Py_Finalize();

PyConfig¶

typePyConfig¶

Structure containing most parameters to configure Python.

When done, thePyConfig_Clear() function must be used to release theconfiguration memory.

Structure methods:

voidPyConfig_InitPythonConfig(PyConfig*config)¶

Initialize configuration with thePython Configuration.

voidPyConfig_InitIsolatedConfig(PyConfig*config)¶

Initialize configuration with theIsolated Configuration.

PyStatusPyConfig_SetString(PyConfig*config,wchar_t*const*config_str,constwchar_t*str)¶

Copy the wide character stringstr into*config_str.

Preinitialize Python if needed.

PyStatusPyConfig_SetBytesString(PyConfig*config,wchar_t*const*config_str,constchar*str)¶

Decodestr usingPy_DecodeLocale() and set the result into*config_str.

Preinitialize Python if needed.

PyStatusPyConfig_SetArgv(PyConfig*config,intargc,wchar_t*const*argv)¶

Set command line arguments (argv member ofconfig) from theargv list of wide character strings.

Preinitialize Python if needed.

PyStatusPyConfig_SetBytesArgv(PyConfig*config,intargc,char*const*argv)¶

Set command line arguments (argv member ofconfig) from theargv list of bytes strings. Decode bytes usingPy_DecodeLocale().

Preinitialize Python if needed.

PyStatusPyConfig_SetWideStringList(PyConfig*config,PyWideStringList*list,Py_ssize_tlength,wchar_t**items)¶

Set the list of wide stringslist tolength anditems.

Preinitialize Python if needed.

PyStatusPyConfig_Read(PyConfig*config)¶

Read all Python configuration.

Fields which are already initialized are left unchanged.

Fields forpath configuration are no longercalculated or modified when calling this function, as of Python 3.11.

ThePyConfig_Read() function only parsesPyConfig.argv arguments once:PyConfig.parse_argvis set to2 after arguments are parsed. Since Python arguments arestripped fromPyConfig.argv, parsing arguments twice wouldparse the application options as Python options.

Preinitialize Python if needed.

Changed in version 3.10:ThePyConfig.argv arguments are now only parsed once,PyConfig.parse_argv is set to2 after arguments areparsed, and arguments are only parsed ifPyConfig.parse_argv equals1.

Changed in version 3.11:PyConfig_Read() no longer calculates all paths, and so fieldslisted underPython Path Configuration mayno longer be updated untilPy_InitializeFromConfig() iscalled.

voidPyConfig_Clear(PyConfig*config)¶

Release configuration memory.

MostPyConfig methodspreinitialize Python if needed.In that case, the Python preinitialization configuration(PyPreConfig) in based on thePyConfig. If configurationfields which are in common withPyPreConfig are tuned, they mustbe set before calling aPyConfig method:

• PyConfig.dev_mode

• PyConfig.isolated

• PyConfig.parse_argv

• PyConfig.use_environment

Moreover, ifPyConfig_SetArgv() orPyConfig_SetBytesArgv()is used, this method must be called before other methods, since thepreinitialization configuration depends on command line arguments (ifparse_argv is non-zero).

The caller of these methods is responsible to handle exceptions (error orexit) usingPyStatus_Exception() andPy_ExitStatusException().

Structure fields:

PyWideStringListargv¶

Setsys.argv command line arguments based onargv. These parameters are similar to those passedto the program’smain() function with the difference that thefirst entry should refer to the script file to be executed rather thanthe executable hosting the Python interpreter. If there isn’t a scriptthat will be run, the first entry inargv can be anempty string.

Setparse_argv to1 to parseargv the same way the regular Python parses Pythoncommand line arguments and then to strip Python arguments fromargv.

Ifargv is empty, an empty string is added toensure thatsys.argv always exists and is never empty.

Default:NULL.

See also theorig_argv member.

intsafe_path¶

If equals to zero,Py_RunMain() prepends a potentially unsafe path tosys.path at startup:

• Ifargv[0] is equal toL"-m"(python-mmodule), prepend the current working directory.

• If running a script (pythonscript.py), prepend the script’sdirectory. If it’s a symbolic link, resolve symbolic links.

• Otherwise (python-ccode andpython), prepend an empty string,which means the current working directory.

Set to1 by the-P command line option and thePYTHONSAFEPATH environment variable.

Default:0 in Python config,1 in isolated config.

Added in version 3.11.

wchar_t*base_exec_prefix¶

sys.base_exec_prefix.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.exec_prefix.

wchar_t*base_executable¶

Python base executable:sys._base_executable.

Set by the__PYVENV_LAUNCHER__ environment variable.

Set fromPyConfig.executable ifNULL.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.executable.

wchar_t*base_prefix¶

sys.base_prefix.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.prefix.

intbuffered_stdio¶

If equals to0 andconfigure_c_stdio is non-zero,disable buffering on the C streams stdout and stderr.

Set to0 by the-u command line option and thePYTHONUNBUFFERED environment variable.

stdin is always opened in buffered mode.

Default:1.

intbytes_warning¶

If equals to1, issue a warning when comparingbytes orbytearray withstr, or comparingbytes withint.

If equal or greater to2, raise aBytesWarning exception in thesecases.

Incremented by the-b command line option.

Default:0.

intwarn_default_encoding¶

If non-zero, emit aEncodingWarning warning whenio.TextIOWrapperuses its default encoding. SeeOpt-in EncodingWarning for details.

Default:0.

Added in version 3.10.

intcode_debug_ranges¶

If equals to0, disables the inclusion of the end line and columnmappings in code objects. Also disables traceback printing carets tospecific error locations.

Set to0 by thePYTHONNODEBUGRANGES environment variableand by the-Xno_debug_ranges command line option.

Default:1.

Added in version 3.11.

wchar_t*check_hash_pycs_mode¶

Control the validation behavior of hash-based.pyc files:value of the--check-hash-based-pycs command line option.

Valid values:

• L"always": Hash the source file for invalidation regardless ofvalue of the ‘check_source’ flag.

• L"never": Assume that hash-based pycs always are valid.

• L"default": The ‘check_source’ flag in hash-based pycsdetermines invalidation.

Default:L"default".

See alsoPEP 552 “Deterministic pycs”.

intconfigure_c_stdio¶

If non-zero, configure C standard streams:

• On Windows, set the binary mode (O_BINARY) on stdin, stdout andstderr.

• Ifbuffered_stdio equals zero, disable bufferingof stdin, stdout and stderr streams.

• Ifinteractive is non-zero, enable streambuffering on stdin and stdout (only stdout on Windows).

Default:1 in Python config,0 in isolated config.

intdev_mode¶

If non-zero, enable thePython Development Mode.

Set to1 by the-Xdev option and thePYTHONDEVMODE environment variable.

Default:-1 in Python mode,0 in isolated mode.

intdump_refs¶

Dump Python references?

If non-zero, dump all objects which are still alive at exit.

Set to1 by thePYTHONDUMPREFS environment variable.

Needs a special build of Python with thePy_TRACE_REFS macro defined:see theconfigure--with-trace-refsoption.

Default:0.

wchar_t*exec_prefix¶

The site-specific directory prefix where the platform-dependent Pythonfiles are installed:sys.exec_prefix.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.base_exec_prefix.

wchar_t*executable¶

The absolute path of the executable binary for the Python interpreter:sys.executable.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.base_executable.

intfaulthandler¶

Enable faulthandler?

If non-zero, callfaulthandler.enable() at startup.

Set to1 by-Xfaulthandler and thePYTHONFAULTHANDLER environment variable.

Default:-1 in Python mode,0 in isolated mode.

wchar_t*filesystem_encoding¶

Filesystem encoding:sys.getfilesystemencoding().

On macOS, Android and VxWorks: use"utf-8" by default.

On Windows: use"utf-8" by default, or"mbcs" iflegacy_windows_fs_encoding ofPyPreConfig is non-zero.

Default encoding on other platforms:

• "utf-8" ifPyPreConfig.utf8_mode is non-zero.

• "ascii" if Python detects thatnl_langinfo(CODESET) announcesthe ASCII encoding, whereas thembstowcs() functiondecodes from a different encoding (usually Latin1).

• "utf-8" ifnl_langinfo(CODESET) returns an empty string.

• Otherwise, use thelocale encoding:nl_langinfo(CODESET) result.

At Python startup, the encoding name is normalized to the Python codecname. For example,"ANSI_X3.4-1968" is replaced with"ascii".

See also thefilesystem_errors member.

wchar_t*filesystem_errors¶

Filesystem error handler:sys.getfilesystemencodeerrors().

On Windows: use"surrogatepass" by default, or"replace" iflegacy_windows_fs_encoding ofPyPreConfig is non-zero.

On other platforms: use"surrogateescape" by default.

Supported error handlers:

• "strict"

• "surrogateescape"

• "surrogatepass" (only supported with the UTF-8 encoding)

See also thefilesystem_encoding member.

unsignedlonghash_seed¶

intuse_hash_seed¶

Randomized hash function seed.

Ifuse_hash_seed is zero, a seed is chosen randomlyat Python startup, andhash_seed is ignored.

Set by thePYTHONHASHSEED environment variable.

Defaultuse_hash_seed value:-1 in Python mode,0 in isolatedmode.

wchar_t*home¶

Set the default Python “home” directory, that is, the location of thestandard Python libraries (seePYTHONHOME).

Set by thePYTHONHOME environment variable.

Default:NULL.

Part of thePython Path Configuration input.

intimport_time¶

If non-zero, profile import time.

Set the1 by the-Ximporttime option and thePYTHONPROFILEIMPORTTIME environment variable.

Default:0.

intinspect¶

Enter interactive mode after executing a script or a command.

If greater than0, enable inspect: when a script is passed as firstargument or the -c option is used, enter interactive mode after executingthe script or the command, even whensys.stdin does not appear tobe a terminal.

Incremented by the-i command line option. Set to1 if thePYTHONINSPECT environment variable is non-empty.

Default:0.

intinstall_signal_handlers¶

Install Python signal handlers?

Default:1 in Python mode,0 in isolated mode.

intinteractive¶

If greater than0, enable the interactive mode (REPL).

Incremented by the-i command line option.

Default:0.

intint_max_str_digits¶

Configures theinteger string conversion length limitation. An initial value of-1 means the value willbe taken from the command line or environment or otherwise default to4300 (sys.int_info.default_max_str_digits). A value of0disables the limitation. Values greater than zero but less than 640(sys.int_info.str_digits_check_threshold) are unsupported andwill produce an error.

Configured by the-Xint_max_str_digits command lineflag or thePYTHONINTMAXSTRDIGITS environment variable.

Default:-1 in Python mode. 4300(sys.int_info.default_max_str_digits) in isolated mode.

Added in version 3.12.

intcpu_count¶

If the value ofcpu_count is not-1 then it willoverride the return values ofos.cpu_count(),os.process_cpu_count(), andmultiprocessing.cpu_count().

Configured by the-Xcpu_count=n|default command lineflag or thePYTHON_CPU_COUNT environment variable.

Default:-1.

Added in version 3.13.

intisolated¶

If greater than0, enable isolated mode:

• Setsafe_path to1:don’t prepend a potentially unsafe path tosys.path at Pythonstartup, such as the current directory, the script’s directory or anempty string.

• Setuse_environment to0: ignorePYTHONenvironment variables.

• Setuser_site_directory to0: don’t add the usersite directory tosys.path.

• Python REPL doesn’t importreadline nor enable default readlineconfiguration on interactive prompts.

Set to1 by the-I command line option.

Default:0 in Python mode,1 in isolated mode.

See also theIsolated Configuration andPyPreConfig.isolated.

intlegacy_windows_stdio¶

If non-zero, useio.FileIO instead ofio._WindowsConsoleIO forsys.stdin,sys.stdoutandsys.stderr.

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

Only available on Windows.#ifdefMS_WINDOWS macro can be used forWindows specific code.

Default:0.

See also thePEP 528 (Change Windows console encoding to UTF-8).

intmalloc_stats¶

If non-zero, dump statistics onPython pymalloc memory allocator at exit.

Set to1 by thePYTHONMALLOCSTATS environment variable.

The option is ignored if Python isconfiguredusingthe--without-pymallocoption.

Default:0.

wchar_t*platlibdir¶

Platform library directory name:sys.platlibdir.

Set by thePYTHONPLATLIBDIR environment variable.

Default: value of thePLATLIBDIR macro which is set by theconfigure--with-platlibdiroption(default:"lib", or"DLLs" on Windows).

Part of thePython Path Configuration input.

Added in version 3.9.

Changed in version 3.11:This macro is now used on Windows to locate the standardlibrary extension modules, typically underDLLs. However,for compatibility, note that this value is ignored for anynon-standard layouts, including in-tree builds and virtualenvironments.

wchar_t*pythonpath_env¶

Module search paths (sys.path) as a string separated byDELIM(os.pathsep).

Set by thePYTHONPATH environment variable.

Default:NULL.

Part of thePython Path Configuration input.

PyWideStringListmodule_search_paths¶

intmodule_search_paths_set¶

Module search paths:sys.path.

Ifmodule_search_paths_set is equal to0,Py_InitializeFromConfig() will replacemodule_search_paths and setsmodule_search_paths_set to1.

Default: empty list (module_search_paths) and0(module_search_paths_set).

Part of thePython Path Configuration output.

intoptimization_level¶

Compilation optimization level:

• 0: Peephole optimizer, set__debug__ toTrue.

• 1: Level 0, remove assertions, set__debug__ toFalse.

• 2: Level 1, strip docstrings.

Incremented by the-O command line option. Set to thePYTHONOPTIMIZE environment variable value.

Default:0.

PyWideStringListorig_argv¶

The list of the original command line arguments passed to the Pythonexecutable:sys.orig_argv.

Iforig_argv list is empty andargv is not a list only containing an emptystring,PyConfig_Read() copiesargv intoorig_argv before modifyingargv (ifparse_argv isnon-zero).

See also theargv member and thePy_GetArgcArgv() function.

Default: empty list.

Added in version 3.10.

intparse_argv¶

Parse command line arguments?

If equals to1, parseargv the same way the regularPython parsescommand line arguments, and stripPython arguments fromargv.

ThePyConfig_Read() function only parsesPyConfig.argv arguments once:PyConfig.parse_argvis set to2 after arguments are parsed. Since Python arguments arestripped fromPyConfig.argv, parsing arguments twice wouldparse the application options as Python options.

Default:1 in Python mode,0 in isolated mode.

Changed in version 3.10:ThePyConfig.argv arguments are now only parsed ifPyConfig.parse_argv equals to1.

intparser_debug¶

Parser debug mode. If greater than0, turn on parser debugging output (for expert only, dependingon compilation options).

Incremented by the-d command line option. Set to thePYTHONDEBUG environment variable value.

Needs adebug build of Python (thePy_DEBUG macromust be defined).

Default:0.

intpathconfig_warnings¶

If non-zero, calculation of path configuration is allowed to logwarnings intostderr. If equals to0, suppress these warnings.

Default:1 in Python mode,0 in isolated mode.

Part of thePython Path Configuration input.

Changed in version 3.11:Now also applies on Windows.

wchar_t*prefix¶

The site-specific directory prefix where the platform independent Pythonfiles are installed:sys.prefix.

Default:NULL.

Part of thePython Path Configuration output.

See alsoPyConfig.base_prefix.

wchar_t*program_name¶

Program name used to initializeexecutable and inearly error messages during Python initialization.

• On macOS, usePYTHONEXECUTABLE environment variable if set.

• If theWITH_NEXT_FRAMEWORK macro is defined, use__PYVENV_LAUNCHER__ environment variable if set.

• Useargv[0] ofargv if available andnon-empty.

• Otherwise, useL"python" on Windows, orL"python3" on otherplatforms.

Default:NULL.

Part of thePython Path Configuration input.

wchar_t*pycache_prefix¶

Directory where cached.pyc files are written:sys.pycache_prefix.

Set by the-Xpycache_prefix=PATH command line option andthePYTHONPYCACHEPREFIX environment variable.The command-line option takes precedence.

IfNULL,sys.pycache_prefix is set toNone.

Default:NULL.

intquiet¶

Quiet mode. If greater than0, don’t display the copyright and version atPython startup in interactive mode.

Incremented by the-q command line option.

Default:0.

wchar_t*run_command¶

Value of the-c command line option.

Used byPy_RunMain().

Default:NULL.

wchar_t*run_filename¶

Filename passed on the command line: trailing command line argumentwithout-c or-m. It is used by thePy_RunMain() function.

For example, it is set toscript.py by thepython3script.pyargcommand line.

See also thePyConfig.skip_source_first_line option.

Default:NULL.

wchar_t*run_module¶

Value of the-m command line option.

Used byPy_RunMain().

Default:NULL.

wchar_t*run_presite¶

package.module path to module that should be imported beforesite.py is run.

Set by the-Xpresite=package.module command-lineoption and thePYTHON_PRESITE environment variable.The command-line option takes precedence.

Needs adebug build of Python (thePy_DEBUG macromust be defined).

Default:NULL.

intshow_ref_count¶

Show total reference count at exit (excludingimmortal objects)?

Set to1 by-Xshowrefcount command line option.

Needs adebug build of Python (thePy_REF_DEBUGmacro must be defined).

Default:0.

intsite_import¶

Import thesite module at startup?

If equal to zero, disable the import of the module site and thesite-dependent manipulations ofsys.path that it entails.

Also disable these manipulations if thesite module is explicitlyimported later (callsite.main() if you want them to be triggered).

Set to0 by the-S command line option.

sys.flags.no_site is set to the inverted value ofsite_import.

Default:1.

intskip_source_first_line¶

If non-zero, skip the first line of thePyConfig.run_filenamesource.

It allows the usage of non-Unix forms of#!cmd. This is intended fora DOS specific hack only.

Set to1 by the-x command line option.

Default:0.

wchar_t*stdio_encoding¶

wchar_t*stdio_errors¶

Encoding and encoding errors ofsys.stdin,sys.stdout andsys.stderr (butsys.stderr always uses"backslashreplace" error handler).

Use thePYTHONIOENCODING environment variable if it isnon-empty.

Default encoding:

• "UTF-8" ifPyPreConfig.utf8_mode is non-zero.

• Otherwise, use thelocale encoding.

Default error handler:

• On Windows: use"surrogateescape".

• "surrogateescape" ifPyPreConfig.utf8_mode is non-zero,or if the LC_CTYPE locale is “C” or “POSIX”.

• "strict" otherwise.

See alsoPyConfig.legacy_windows_stdio.

inttracemalloc¶

Enable tracemalloc?

If non-zero, calltracemalloc.start() at startup.

Set by-Xtracemalloc=N command line option and by thePYTHONTRACEMALLOC environment variable.

Default:-1 in Python mode,0 in isolated mode.

intperf_profiling¶

Enable compatibility mode with the perf profiler?

If non-zero, initialize the perf trampoline. SeePython support for the Linux perf profilerfor more information.

Set by-Xperf command-line option and by thePYTHON_PERF_JIT_SUPPORT environment variable for perf supportwith stack pointers and-Xperf_jit command-line optionand by thePYTHON_PERF_JIT_SUPPORT environment variable for perfsupport with DWARF JIT information.

Default:-1.

Added in version 3.12.

intuse_environment¶

Useenvironment variables?

If equals to zero, ignore theenvironment variables.

Set to0 by the-E environment variable.

Default:1 in Python config and0 in isolated config.

intuser_site_directory¶

If non-zero, add the user site directory tosys.path.

Set to0 by the-s and-I command line options.

Set to0 by thePYTHONNOUSERSITE environment variable.

Default:1 in Python mode,0 in isolated mode.

intverbose¶

Verbose mode. If greater than0, print a message each time a module isimported, showing the place (filename or built-in module) from whichit is loaded.

If greater than or equal to2, print a message for each file that ischecked for when searching for a module. Also provides information onmodule cleanup at exit.

Incremented by the-v command line option.

Set by thePYTHONVERBOSE environment variable value.

Default:0.

PyWideStringListwarnoptions¶

Options of thewarnings module to build warnings filters, lowestto highest priority:sys.warnoptions.

Thewarnings module addssys.warnoptions in the reverseorder: the lastPyConfig.warnoptions item becomes the firstitem ofwarnings.filters which is checked first (highestpriority).

The-W command line options adds its value towarnoptions, it can be used multiple times.

ThePYTHONWARNINGS environment variable can also be used to addwarning options. Multiple options can be specified, separated by commas(,).

Default: empty list.

intwrite_bytecode¶

If equal to0, Python won’t try to write.pyc files on the import ofsource modules.

Set to0 by the-B command line option and thePYTHONDONTWRITEBYTECODE environment variable.

sys.dont_write_bytecode is initialized to the inverted value ofwrite_bytecode.

Default:1.

PyWideStringListxoptions¶

Values of the-X command line options:sys._xoptions.

Default: empty list.

Ifparse_argv is non-zero,argvarguments are parsed the same way the regular Python parsescommand linearguments, and Python arguments are stripped fromargv.

Thexoptions options are parsed to set other options: seethe-X command line option.

Initialization with PyConfig¶

Initializing the interpreter from a populated configuration struct is handledby callingPy_InitializeFromConfig().

The caller is responsible to handle exceptions (error or exit) usingPyStatus_Exception() andPy_ExitStatusException().

IfPyImport_FrozenModules(),PyImport_AppendInittab() orPyImport_ExtendInittab() are used, they must be set or called afterPython preinitialization and before the Python initialization. If Python isinitialized multiple times,PyImport_AppendInittab() orPyImport_ExtendInittab() must be called before each Pythoninitialization.

The current configuration (PyConfig type) is stored inPyInterpreterState.config.

Example setting the program name:

voidinit_python(void){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);/* Set the program name. Implicitly preinitialize Python. */status=PyConfig_SetString(&config,&config.program_name,L"/path/to/my_program");if(PyStatus_Exception(status)){gotoexception;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotoexception;}PyConfig_Clear(&config);return;exception:PyConfig_Clear(&config);Py_ExitStatusException(status);}

More complete example modifying the default configuration, read theconfiguration, and then override some parameters. Note that since3.11, many parameters are not calculated until initialization, andso values cannot be read from the configuration structure. Any valuesset before initialize is called will be left unchanged byinitialization:

PyStatusinit_python(constchar*program_name){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);/* Set the program name before reading the configuration       (decode byte string from the locale encoding).       Implicitly preinitialize Python. */status=PyConfig_SetBytesString(&config,&config.program_name,program_name);if(PyStatus_Exception(status)){gotodone;}/* Read all configuration at once */status=PyConfig_Read(&config);if(PyStatus_Exception(status)){gotodone;}/* Specify sys.path explicitly *//* If you want to modify the default set of paths, finish       initialization first and then use PySys_GetObject("path") */config.module_search_paths_set=1;status=PyWideStringList_Append(&config.module_search_paths,L"/path/to/stdlib");if(PyStatus_Exception(status)){gotodone;}status=PyWideStringList_Append(&config.module_search_paths,L"/path/to/more/modules");if(PyStatus_Exception(status)){gotodone;}/* Override executable computed by PyConfig_Read() */status=PyConfig_SetString(&config,&config.executable,L"/path/to/my_executable");if(PyStatus_Exception(status)){gotodone;}status=Py_InitializeFromConfig(&config);done:PyConfig_Clear(&config);returnstatus;}

Isolated Configuration¶

PyPreConfig_InitIsolatedConfig() andPyConfig_InitIsolatedConfig() functions create a configuration toisolate Python from the system. For example, to embed Python into anapplication.

This configuration ignores global configuration variables, environmentvariables, command line arguments (PyConfig.argv is not parsed)and user site directory. The C standard streams (ex:stdout) and theLC_CTYPE locale are left unchanged. Signal handlers are not installed.

Configuration files are still used with this configuration to determinepaths that are unspecified. EnsurePyConfig.home is specifiedto avoid computing the default path configuration.

Python Configuration¶

PyPreConfig_InitPythonConfig() andPyConfig_InitPythonConfig()functions create a configuration to build a customized Python which behaves asthe regular Python.

Environments variables and command line arguments are used to configurePython, whereas global configuration variables are ignored.

This function enables C locale coercion (PEP 538)andPython UTF-8 Mode(PEP 540) depending on the LC_CTYPE locale,PYTHONUTF8 andPYTHONCOERCECLOCALE environment variables.

Python Path Configuration¶

PyConfig contains multiple fields for the path configuration:

• Path configuration inputs:

  • PyConfig.home

  • PyConfig.platlibdir

  • PyConfig.pathconfig_warnings

  • PyConfig.program_name

  • PyConfig.pythonpath_env

  • current working directory: to get absolute paths

  • PATH environment variable to get the program full path(fromPyConfig.program_name)

  • __PYVENV_LAUNCHER__ environment variable

  • (Windows only) Application paths in the registry under“SoftwarePythonPythonCoreX.YPythonPath” of HKEY_CURRENT_USER andHKEY_LOCAL_MACHINE (where X.Y is the Python version).

• Path configuration output fields:

  • PyConfig.base_exec_prefix

  • PyConfig.base_executable

  • PyConfig.base_prefix

  • PyConfig.exec_prefix

  • PyConfig.executable

  • PyConfig.module_search_paths_set,PyConfig.module_search_paths

  • PyConfig.prefix

If at least one “output field” is not set, Python calculates the pathconfiguration to fill unset fields. Ifmodule_search_paths_set is equal to0,module_search_paths is overridden andmodule_search_paths_set is set to1.

It is possible to completely ignore the function calculating the defaultpath configuration by setting explicitly all path configuration outputfields listed above. A string is considered as set even if it is non-empty.module_search_paths is considered as set ifmodule_search_paths_set is set to1. In this case,module_search_paths will be used without modification.

Setpathconfig_warnings to0 to suppress warnings whencalculating the path configuration (Unix only, Windows does not log any warning).

Ifbase_prefix orbase_exec_prefixfields are not set, they inherit their value fromprefixandexec_prefix respectively.

Py_RunMain() andPy_Main() modifysys.path:

• Ifrun_filename is set and is a directory which contains a__main__.py script, prependrun_filename tosys.path.

• Ifisolated is zero:

  • Ifrun_module is set, prepend the current directorytosys.path. Do nothing if the current directory cannot be read.

  • Ifrun_filename is set, prepend the directory of thefilename tosys.path.

  • Otherwise, prepend an empty string tosys.path.

Ifsite_import is non-zero,sys.path can bemodified by thesite module. Ifuser_site_directory is non-zero and the user’ssite-package directory exists, thesite module appends the user’ssite-package directory tosys.path.

The following configuration files are used by the path configuration:

• pyvenv.cfg

• ._pth file (ex:python._pth)

• pybuilddir.txt (Unix only)

If a._pth file is present:

• Setisolated to1.

• Setuse_environment to0.

• Setsite_import to0.

• Setsafe_path to1.

The__PYVENV_LAUNCHER__ environment variable is used to setPyConfig.base_executable.

Py_GetArgcArgv()¶

voidPy_GetArgcArgv(int*argc,wchar_t***argv)¶

Get the original command line arguments, before Python modified them.

See alsoPyConfig.orig_argv member.

Multi-Phase Initialization Private Provisional API¶

This section is a private provisional API introducing multi-phaseinitialization, the core feature ofPEP 432:

• “Core” initialization phase, “bare minimum Python”:

  • Builtin types;

  • Builtin exceptions;

  • Builtin and frozen modules;

  • Thesys module is only partially initialized(ex:sys.path doesn’t exist yet).

• “Main” initialization phase, Python is fully initialized:

  • Install and configureimportlib;

  • Apply thePath Configuration;

  • Install signal handlers;

  • Finishsys module initialization (ex: createsys.stdoutandsys.path);

  • Enable optional features likefaulthandler andtracemalloc;

  • Import thesite module;

  • etc.

Private provisional API:

• PyConfig._init_main: if set to0,Py_InitializeFromConfig() stops at the “Core” initialization phase.

PyStatus_Py_InitializeMain(void)¶

Move to the “Main” initialization phase, finish the Python initialization.

No module is imported during the “Core” phase and theimportlib module isnot configured: thePath Configuration is onlyapplied during the “Main” phase. It may allow to customize Python in Python tooverride or tune thePath Configuration, maybeinstall a customsys.meta_path importer or an import hook, etc.

It may become possible to calculate thePath Configuration in Python, after the Core phase and before the Main phase,which is one of thePEP 432 motivation.

The “Core” phase is not properly defined: what should be and what shouldnot be available at this phase is not specified yet. The API is markedas private and provisional: the API can be modified or even be removedanytime until a proper public API is designed.

Example running Python code between “Core” and “Main” initializationphases:

voidinit_python(void){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);config._init_main=0;/* ... customize 'config' configuration ... */status=Py_InitializeFromConfig(&config);PyConfig_Clear(&config);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}/* Use sys.stderr because sys.stdout is only created       by _Py_InitializeMain() */intres=PyRun_SimpleString("import sys; ""print('Run Python code before _Py_InitializeMain', ""file=sys.stderr)");if(res<0){exit(1);}/* ... put more configuration code here ... */status=_Py_InitializeMain();if(PyStatus_Exception(status)){Py_ExitStatusException(status);}}