Python Initialization Configuration¶

New in version 3.8.

Python can be initialized withPy_InitializeFromConfig() and thePyConfig structure. It can be preinitialized withPy_PreInitialize() and thePyPreConfig structure.

There are two kinds of configuration:

ThePython Configuration can be used to build acustomized Python which behaves as the regular Python. For example,environment variables and command line arguments are used to configurePython.
TheIsolated Configuration can be used to embedPython into an application. It isolates Python from the system. For example,environment variables are ignored, the LC_CTYPE locale is left unchanged andno signal handler is registered.

ThePy_RunMain() function can be used to write a customized Pythonprogram.

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.

Note

Internally, Python uses macros which setPyStatus.func,whereas functions to create a status setfunc toNULL.

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_PYMALLOC andPYMEM_ALLOCATOR_PYMALLOC_DEBUG arenot supported if Python isconfiguredusing--without-pymalloc.

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 the fromPYTHONLEGACYWINDOWSFSENCODING 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 arestrippped 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:

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¶

Command line arguments:sys.argv.

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.

Initialization with PyConfig¶

Function to initialize Python:

PyStatusPy_InitializeFromConfig(constPyConfig*config)¶: Initialize Python fromconfig configuration.

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:

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

intPy_RunMain(void)¶

Execute the command (PyConfig.run_command), the script(PyConfig.run_filename) or the module(PyConfig.run_module) specified on the command line or in theconfiguration.

By default and when if-i option is used, run the REPL.

Finally, finalizes Python and returns an exit status that can be passed totheexit() function.

SeePython Configuration for an example ofcustomized Python always running in isolated mode usingPy_RunMain().

Py_GetArgcArgv()¶

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

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

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.
PyConfig._isolated_interpreter: if non-zero,disallow threads, subprocesses and fork.

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 calculatin 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);}}

Movatterモバイル変換

Navigation

Python Initialization Configuration¶

Example¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

Preinitialize Python with PyPreConfig¶

PyConfig¶

Initialization with PyConfig¶

Isolated Configuration¶

Python Configuration¶

Python Path Configuration¶

Py_RunMain()¶

Py_GetArgcArgv()¶

Multi-Phase Initialization Private Provisional API¶

Table of Contents

Previous topic

Next topic

This Page

Navigation