New in version 3.8.
Python can be initialized with
and the
structure. It can be preinitialized with
and the
structure.
There are two kinds of configuration:
The
can be used to build a customized Python which behaves as the regular Python. For example, environment variables and command line arguments are used to configure Python.
The
can be used to embed Python into an application. It isolates Python from the system. For example, environment variables are ignored, the LC_CTYPE locale is left unchanged and no signal handler is registered.
The
function can be used to write a customized Python program.
See also
Initialization, Finalization, and Threads
.
See also
“Python Initialization Configuration”.
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 of wchar_t* strings.
If length is non-zero, items must be non-NULL and all strings must be non-NULL.
Methods:
PyWideStringList_Append(
*list, constwchar_t*item)
Append item to list.
Python must be preinitialized to call this function.
PyWideStringList_Insert(
*list,
index, constwchar_t*item)
Insert item into list at index.
If index is greater than or equal to list length, append item to list.
index must be greater than or equal to 0.
Python must be preinitialized to call this function.
Structure fields:
length
List length.
wchar_t**items
List items.
PyStatus
typePyStatus
Structure to store an initialization function status: success, error or exit.
For an error, it can store the C function name which created the error.
Structure fields:
intexitcode
Exit code. Argument passed to exit().
constchar*err_msg
Error message.
constchar*func
Name of the function which created an error, can be NULL.
Functions to create a status:
PyStatus_Ok(void)
Success.
PyStatus_Error(constchar*err_msg)
Initialization error with a message.
err_msg must not be NULL.
PyStatus_NoMemory(void)
Memory allocation failure (out of memory).
PyStatus_Exit(intexitcode)
Exit Python with the specified exit code.
Functions to handle a status:
intPyStatus_Exception(
status)
Is the status an error or an exit? If true, the exception must be handled; by calling
for example.
intPyStatus_IsError(
status)
Is the result an error?
intPyStatus_IsExit(
status)
Is the result an exit?
voidPy_ExitStatusException(
status)
Call exit(exitcode) if status is an exit. Print the error message and exit with a non-zero exit code if status is an error. Must only be called if PyStatus_Exception(status) is non-zero.
Note
Internally, Python uses macros which set PyStatus.func, whereas functions to create a status set func to NULL.
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(
*preconfig)
Initialize the preconfiguration with
.
voidPyPreConfig_InitIsolatedConfig(
*preconfig)
Initialize the preconfiguration with
.
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):
.
PYMEM_ALLOCATOR_DEBUG (2):
with
.
PYMEM_ALLOCATOR_MALLOC (3): use malloc() of the C library.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage of malloc() with
.
PYMEM_ALLOCATOR_PYMALLOC (5):
Python pymalloc memory allocator
.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6):
Python pymalloc memory allocator
with
.
PYMEM_ALLOCATOR_PYMALLOC and PYMEM_ALLOCATOR_PYMALLOC_DEBUG are not supported if Python is
configured using --without-pymalloc
.
See
.
Default: PYMEM_ALLOCATOR_NOT_SET.
intconfigure_locale
Set the LC_CTYPE locale to the user preferred locale.
If equals to 0, set
and
members to 0.
See the
.
Default: 1 in Python config, 0 in isolated config.
intcoerce_c_locale
If equals to 2, coerce the C locale.
If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.
See the
.
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
: see
.
Default: -1 in Python mode, 0 in isolated mode.
intisolated
Isolated mode: see
.
Default: 0 in Python mode, 1 in isolated mode.
intlegacy_windows_fs_encoding
If non-zero:
Set
to 0,
Set
to "mbcs",
Set
to "replace".
Initialized the from
environment variable value.
Only available on Windows. #ifdefMS_WINDOWS macro can be used for Windows specific code.
Default: 0.
intparse_argv
If non-zero,
and
Py_PreInitializeFromBytesArgs()
parse their argv argument the same way the regular Python parses command line arguments: see
.
Default: 1 in Python config, 0 in isolated config.
intuse_environment
Use
? See
.
Default: 1 in Python config and 0 in isolated config.
intutf8_mode
If non-zero, enable the
.
Set to 0 or 1 by the
command line option and the
environment variable.
Also set to 1 if the LC_CTYPE locale is C or POSIX.
Default: -1 in Python config and 0 in isolated config.
Preinitialize Python with PyPreConfig
The preinitialization of Python:
Set the Python memory allocators (
)
Configure the LC_CTYPE locale (
)
Set the
(
)
The current preconfiguration (PyPreConfig type) is stored in _PyRuntime.preconfig.
Functions to preinitialize Python:
Py_PreInitialize(const
*preconfig)
Preinitialize Python from preconfig preconfiguration.
preconfig must not be NULL.
Py_PreInitializeFromBytesArgs(const
*preconfig, intargc, char*const*argv)
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (bytes strings) if
of preconfig is non-zero.
preconfig must not be NULL.
Py_PreInitializeFromArgs(const
*preconfig, intargc, wchar_t*const*argv)
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (wide strings) if
of preconfig is non-zero.
preconfig must not be NULL.
The caller is responsible to handle exceptions (error or exit) using
and
.
For
(
PyPreConfig_InitPythonConfig()
), if Python is initialized with command line arguments, the command line arguments must also be passed to preinitialize Python, since they have an effect on the pre-configuration like encodings. For example, the
command line option enables the
.
PyMem_SetAllocator() can be called after
and before
to install a custom memory allocator. It can be called before
if
is set to PYMEM_ALLOCATOR_NOT_SET.
Python memory allocation functions like
must not be used before the Python preinitialization, whereas calling directly malloc() and free() is always safe.
must not be called before the Python preinitialization.
Example using the preinitialization to enable the
:
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, the
function must be used to release the configuration memory.
Structure methods:
voidPyConfig_InitPythonConfig(
*config)
Initialize configuration with the
.
voidPyConfig_InitIsolatedConfig(
*config)
Initialize configuration with the
.
PyConfig_SetString(
*config, wchar_t*const*config_str, constwchar_t*str)
Copy the wide character string str into *config_str.
if needed.
PyConfig_SetBytesString(
*config, wchar_t*const*config_str, constchar*str)
Decode str using
and set the result into *config_str.
if needed.
PyConfig_SetArgv(
*config, intargc, wchar_t*const*argv)
Set command line arguments (
member of config) from the argv list of wide character strings.
if needed.
PyConfig_SetBytesArgv(
*config, intargc, char*const*argv)
Set command line arguments (
member of config) from the argv list of bytes strings. Decode bytes using
.
if needed.
PyConfig_SetWideStringList(
*config,
*list,
length, wchar_t**items)
Set the list of wide strings list to length and items.
if needed.
PyConfig_Read(
*config)
Read all Python configuration.
Fields which are already initialized are left unchanged.
Fields for
are no longer calculated or modified when calling this function, as of Python 3.11.
The
function only parses
arguments once:
is set to 2 after arguments are parsed. Since Python arguments are strippped from
, parsing arguments twice would parse the application options as Python options.
if needed.
Changed in version 3.10: The
arguments are now only parsed once,
is set to 2 after arguments are parsed, and arguments are only parsed if
equals 1.
Changed in version 3.11:
no longer calculates all paths, and so fields listed under
may no longer be updated until
is called.
voidPyConfig_Clear(
*config)
Release configuration memory.
Most PyConfig methods
if needed. In that case, the Python preinitialization configuration (
) in based on the
. If configuration fields which are in common with
are tuned, they must be set before calling a
method:
Moreover, if
or
is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if
is non-zero).
The caller of these methods is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().
Structure fields:
argv
Command line arguments:
.
Set
to 1 to parse
the same way the regular Python parses Python command line arguments and then to strip Python arguments from
.
If
is empty, an empty string is added to ensure that
always exists and is never empty.
Default: NULL.
See also the
member.
intsafe_path
If equals to zero, Py_RunMain() prepends a potentially unsafe path to
at startup:
If
is equal to L"-m" (python-mmodule), prepend the current working directory.
If running a script (pythonscript.py), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.
Otherwise (python-ccode and python), prepend an empty string, which means the current working directory.
Set to 1 by the
command line option and the
environment variable.
Default: 0 in Python config, 1 in isolated config.
New in version 3.11.
wchar_t*base_exec_prefix
.
Default: NULL.
Part of the
output.
wchar_t*base_executable
Python base executable: sys._base_executable.
Set by the __PYVENV_LAUNCHER__ environment variable.
Set from
if NULL.
Default: NULL.
Part of the
output.
wchar_t*base_prefix
.
Default: NULL.
Part of the
output.
intbuffered_stdio
If equals to 0 and
is non-zero, disable buffering on the C streams stdout and stderr.
Set to 0 by the
command line option and the
environment variable.
stdin is always opened in buffered mode.
Default: 1.
intbytes_warning
If equals to 1, issue a warning when comparing
or
with
, or comparing
with
.
If equal or greater to 2, raise a
exception in these cases.
Incremented by the
command line option.
Default: 0.
intwarn_default_encoding
If non-zero, emit a
warning when
uses its default encoding. See
for details.
Default: 0.
New in version 3.10.
intcode_debug_ranges
If equals to 0, disables the inclusion of the end line and column mappings in code objects. Also disables traceback printing carets to specific error locations.
Set to 0 by the
environment variable and by the
command line option.
Default: 1.
New in version 3.11.
wchar_t*check_hash_pycs_mode
Control the validation behavior of hash-based .pyc files: value of the
command line option.
Valid values:
L"always": Hash the source file for invalidation regardless of value of the ‘check_source’ flag.
L"never": Assume that hash-based pycs always are valid.
L"default": The ‘check_source’ flag in hash-based pycs determines invalidation.
Default: L"default".
See also
“Deterministic pycs”.
intconfigure_c_stdio
If non-zero, configure C standard streams:
On Windows, set the binary mode (O_BINARY) on stdin, stdout and stderr.
If
equals zero, disable buffering of stdin, stdout and stderr streams.
If
is non-zero, enable stream buffering on stdin and stdout (only stdout on Windows).
Default: 1 in Python config, 0 in isolated config.
intdev_mode
If non-zero, enable the
.
Set to 1 by the
option and the
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 to 1 by the
environment variable.
Need a special build of Python with the Py_TRACE_REFS macro defined: see the
configure --with-trace-refs option
.
Default: 0.
wchar_t*exec_prefix
The site-specific directory prefix where the platform-dependent Python files are installed:
.
Default: NULL.
Part of the
output.
wchar_t*executable
The absolute path of the executable binary for the Python interpreter:
.
Default: NULL.
Part of the
output.
intfaulthandler
Enable faulthandler?
If non-zero, call
at startup.
Set to 1 by
and the
environment variable.
Default: -1 in Python mode, 0 in isolated mode.
wchar_t*filesystem_encoding
:
.
On macOS, Android and VxWorks: use "utf-8" by default.
On Windows: use "utf-8" by default, or "mbcs" if
of
is non-zero.
Default encoding on other platforms:
"utf-8" if
is non-zero.
"ascii" if Python detects that nl_langinfo(CODESET) announces the ASCII encoding, whereas the mbstowcs() function decodes from a different encoding (usually Latin1).
"utf-8" if nl_langinfo(CODESET) returns an empty string.
Otherwise, use the
: nl_langinfo(CODESET) result.
At Python startup, the encoding name is normalized to the Python codec name. For example, "ANSI_X3.4-1968" is replaced with "ascii".
See also the
member.
wchar_t*filesystem_errors
:
sys.getfilesystemencodeerrors()
.
On Windows: use "surrogatepass" by default, or "replace" if
of
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 the
member.
unsignedlonghash_seed
intuse_hash_seed
Randomized hash function seed.
If
is zero, a seed is chosen randomly at Python startup, and
is ignored.
Set by the
environment variable.
Default use_hash_seed value: -1 in Python mode, 0 in isolated mode.
wchar_t*home
Python home directory.
If
has been called, use its argument if it is not NULL.
Set by the
environment variable.
Default: NULL.
Part of the
input.
intimport_time
If non-zero, profile import time.
Set the 1 by the
option and the
environment variable.
Default: 0.
intinspect
Enter interactive mode after executing a script or a command.
If greater than 0, enable inspect: 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 when
does not appear to be a terminal.
Incremented by the
command line option. Set to 1 if the
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 than 0, enable the interactive mode (REPL).
Incremented by the
command line option.
Default: 0.
intisolated
If greater than 0, enable isolated mode:
Set
to 1: don’t prepend a potentially unsafe path to
at Python startup.
Set
to 0.
Set
to 0: don’t add the user site directory to
.
Python REPL doesn’t import
nor enable default readline configuration on interactive prompts.
Set to 1 by the
command line option.
Default: 0 in Python mode, 1 in isolated mode.
See also
.
intlegacy_windows_stdio
If non-zero, use
instead of io._WindowsConsoleIO for
,
and
.
Set to 1 if the
environment variable is set to a non-empty string.
Only available on Windows. #ifdefMS_WINDOWS macro can be used for Windows specific code.
Default: 0.
See also the
(Change Windows console encoding to UTF-8).
intmalloc_stats
If non-zero, dump statistics on
Python pymalloc memory allocator
at exit.
Set to 1 by the
environment variable.
The option is ignored if Python is
configured using the --without-pymalloc option
.
Default: 0.
wchar_t*platlibdir
Platform library directory name:
.
Set by the
environment variable.
Default: value of the PLATLIBDIR macro which is set by the
configure --with-platlibdir option
(default: "lib", or "DLLs" on Windows).
Part of the
input.
New in version 3.9.
Changed in version 3.11: This macro is now used on Windows to locate the standard library extension modules, typically under DLLs. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.
wchar_t*pythonpath_env
Module search paths (
) as a string separated by DELIM (
).
Set by the
environment variable.
Default: NULL.
Part of the
input.
module_search_paths
intmodule_search_paths_set
Module search paths:
.
If
is equal to 0,
will replace
and sets
to 1.
Default: empty list (module_search_paths) and 0 (module_search_paths_set).
Part of the
output.
intoptimization_level
Compilation optimization level:
0: Peephole optimizer, set __debug__ to True.
1: Level 0, remove assertions, set __debug__ to False.
2: Level 1, strip docstrings.
Incremented by the
command line option. Set to the
environment variable value.
Default: 0.
orig_argv
The list of the original command line arguments passed to the Python executable:
.
If
list is empty and
is not a list only containing an empty string,
copies
into
before modifying
(if
is non-zero).
See also the
member and the
function.
Default: empty list.
New in version 3.10.
intparse_argv
Parse command line arguments?
If equals to 1, parse
the same way the regular Python parses
, and strip Python arguments from
.
The
function only parses
arguments once:
is set to 2 after arguments are parsed. Since Python arguments are strippped from
, parsing arguments twice would parse the application options as Python options.
Default: 1 in Python mode, 0 in isolated mode.
Changed in version 3.10: The
arguments are now only parsed if
equals to 1.
intparser_debug
Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending on compilation options).
Incremented by the
command line option. Set to the
environment variable value.
Default: 0.
intpathconfig_warnings
If non-zero, calculation of path configuration is allowed to log warnings into stderr. If equals to 0, suppress these warnings.
Default: 1 in Python mode, 0 in isolated mode.
Part of the
input.
Changed in version 3.11: Now also applies on Windows.
wchar_t*prefix
The site-specific directory prefix where the platform independent Python files are installed:
.
Default: NULL.
Part of the
output.
wchar_t*program_name
Program name used to initialize
and in early error messages during Python initialization.
If Py_SetProgramName() has been called, use its argument.
On macOS, use
environment variable if set.
If the WITH_NEXT_FRAMEWORK macro is defined, use __PYVENV_LAUNCHER__ environment variable if set.
Use argv[0] of
if available and non-empty.
Otherwise, use L"python" on Windows, or L"python3" on other platforms.
Default: NULL.
Part of the
input.
wchar_t*pycache_prefix
Directory where cached .pyc files are written:
.
Set by the
command line option and the
environment variable.
If NULL,
is set to None.
Default: NULL.
intquiet
Quiet mode. If greater than 0, don’t display the copyright and version at Python startup in interactive mode.
Incremented by the
command line option.
Default: 0.
wchar_t*run_command
Value of the
command line option.
Used by
.
Default: NULL.
wchar_t*run_filename
Filename passed on the command line: trailing command line argument without
or
. It is used by the
function.
For example, it is set to script.py by the python3script.pyarg command line.
See also the
PyConfig.skip_source_first_line
option.
Default: NULL.
wchar_t*run_module
Value of the
command line option.
Used by
.
Default: NULL.
intshow_ref_count
Show total reference count at exit?
Set to 1 by
command line option.
Need a
(the Py_REF_DEBUG macro must be defined).
Default: 0.
intsite_import
Import the
module at startup?
If equal to zero, disable the import of the module site and the site-dependent manipulations of
that it entails.
Also disable these manipulations if the
module is explicitly imported later (call
if you want them to be triggered).
Set to 0 by the
command line option.
is set to the inverted value of
.
Default: 1.
intskip_source_first_line
If non-zero, skip the first line of the
source.
It allows the usage of non-Unix forms of #!cmd. This is intended for a DOS specific hack only.
Set to 1 by the
command line option.
Default: 0.
wchar_t*stdio_encoding
wchar_t*stdio_errors
Encoding and encoding errors of
,
and
(but
always uses "backslashreplace" error handler).
If
Py_SetStandardStreamEncoding()
has been called, use its error and errors arguments if they are not NULL.
Use the
environment variable if it is non-empty.
Default encoding:
"UTF-8" if
is non-zero.
Otherwise, use the
.
Default error handler:
On Windows: use "surrogateescape".
"surrogateescape" if
is non-zero, or if the LC_CTYPE locale is “C” or “POSIX”.
"strict" otherwise.
inttracemalloc
Enable tracemalloc?
If non-zero, call
at startup.
Set by
command line option and by the
environment variable.
Default: -1 in Python mode, 0 in isolated mode.
intuse_environment
Use
?
If equals to zero, ignore the
.
Set to 0 by the
environment variable.
Default: 1 in Python config and 0 in isolated config.
intuser_site_directory
If non-zero, add the user site directory to
.
Set to 0 by the
and
command line options.
Set to 0 by the
environment variable.
Default: 1 in Python mode, 0 in isolated mode.
intverbose
Verbose mode. If greater than 0, print a message each time a module is imported, showing the place (filename or built-in module) from which it is loaded.
If greater or equal to 2, print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.
Incremented by the
command line option.
Set to the
environment variable value.
Default: 0.
warnoptions
Options of the
module to build warnings filters, lowest to highest priority:
.
The
module adds
in the reverse order: the last
item becomes the first item of warnings.filters which is checked first (highest priority).
The
command line options adds its value to
, it can be used multiple times.
The
environment variable can also be used to add warning options. Multiple options can be specified, separated by commas (,).
Default: empty list.
intwrite_bytecode
If equal to 0, Python won’t try to write .pyc files on the import of source modules.
Set to 0 by the
command line option and the
environment variable.
is initialized to the inverted value of
.
Default: 1.
xoptions
Values of the
command line options:
.
Default: empty list.
If
is non-zero,
arguments are parsed the same way the regular Python parses
, and Python arguments are stripped from
.
The
options are parsed to set other options: see the
command line option.
Changed in version 3.9: The show_alloc_count field has been removed.
Initialization with PyConfig
Function to initialize Python:
Py_InitializeFromConfig(const
*config)
Initialize Python from config configuration.
The caller is responsible to handle exceptions (error or exit) using
and
.
If
,
or
are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times,
or
must be called before each Python initialization.
The current configuration (PyConfig type) is stored in PyInterpreterState.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 the configuration, and then override some parameters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:
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()
and
functions create a configuration to isolate Python from the system. For example, to embed Python into an application.
This configuration ignores global configuration variables, environment variables, command line arguments (
is not parsed) and user site directory. The C standard streams (ex: stdout) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Configuration files are still used with this configuration to determine paths that are unspecified. Ensure
is specified to avoid computing the default path configuration.
Python Configuration
PyPreConfig_InitPythonConfig()
and
functions create a configuration to build a customized Python which behaves as the regular Python.
Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored.
This function enables C locale coercion (
) and
(
) depending on the LC_CTYPE locale,
and
environment variables.
Python Path Configuration
contains multiple fields for the path configuration:
Path configuration inputs:
current working directory: to get absolute paths
PATH environment variable to get the program full path (from
)
__PYVENV_LAUNCHER__ environment variable
(Windows only) Application paths in the registry under “SoftwarePythonPythonCoreX.YPythonPath” of HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE (where X.Y is the Python version).
Path configuration output fields:
PyConfig.module_search_paths_set
,
If at least one “output field” is not set, Python calculates the path configuration to fill unset fields. If
is equal to 0,
is overridden and
is set to 1.
It is possible to completely ignore the function calculating the default path configuration by setting explicitly all path configuration output fields listed above. A string is considered as set even if it is non-empty. module_search_paths is considered as set if module_search_paths_set is set to 1. In this case, module_search_paths will be used without modification.
Set
to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).
If
or
fields are not set, they inherit their value from
and
respectively.
and
modify
:
If
is set and is a directory which contains a __main__.py script, prepend
to
.
If
is zero:
If
is set, prepend the current directory to
. Do nothing if the current directory cannot be read.
If
is set, prepend the directory of the filename to
.
Otherwise, prepend an empty string to
.
If
is non-zero,
can be modified by the
module. If
is non-zero and the user’s site-package directory exists, the
module appends the user’s site-package directory to
.
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:
Set
to 1.
Set
to 0.
Set
to 0.
Set
to 1.
The __PYVENV_LAUNCHER__ environment variable is used to set
Py_RunMain()
intPy_RunMain(void)
Execute the command (
), the script (
) or the module (
) specified on the command line or in the configuration.
By default and when if
option is used, run the REPL.
Finally, finalizes Python and returns an exit status that can be passed to the exit() function.
See
for an example of customized Python always running in isolated mode using
.
Py_GetArgcArgv()
voidPy_GetArgcArgv(int*argc, wchar_t***argv)
Get the original command line arguments, before Python modified them.
See also
member.
Multi-Phase Initialization Private Provisional API
This section is a private provisional API introducing multi-phase initialization, the core feature of
:
“Core” initialization phase, “bare minimum Python”:
Builtin types;
Builtin exceptions;
Builtin and frozen modules;
The
module is only partially initialized (ex:
doesn’t exist yet).
“Main” initialization phase, Python is fully initialized:
Install and configure
;
Apply the
;
Install signal handlers;
Finish
module initialization (ex: create
and
);
Enable optional features like
and
;
Import the
module;
etc.
Private provisional API:
PyConfig._init_main: if set to 0,
stops at the “Core” initialization phase.
PyConfig._isolated_interpreter: if non-zero, disallow threads, subprocesses and fork.
_Py_InitializeMain(void)
Move to the “Main” initialization phase, finish the Python initialization.
No module is imported during the “Core” phase and the importlib module is not configured: the
is only applied during the “Main” phase. It may allow to customize Python in Python to override or tune the
, maybe install a custom
importer or an import hook, etc.
It may become possible to calculatin the
in Python, after the Core phase and before the Main phase, which is one of the
motivation.
The “Core” phase is not properly defined: what should be and what should not be available at this phase is not specified yet. The API is marked as private and provisional: the API can be modified or even be removed anytime until a proper public API is designed.
Example running Python code between “Core” and “Main” initialization phases:
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);}}