PyWideStringList¶

PyWideStringList¶

List ofwchar_t* strings.

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

Methods:

PyStatusPyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶

Appenditem tolist.

Python must be preinitialized to call this function.

PyStatusPyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶

Insertitem intolist atindex.

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

index must be greater than or equal to 0.

Python must be preinitialized to call this function.

Structure fields:

Py_ssize_tlength¶

List length.

wchar_t**items¶

List items.

PyStatus¶

PyStatus¶

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

const char *err_msg¶

Error message.

const char *func¶

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

Functions to create a status:

PyStatusPyStatus_Ok(void)¶

Success.

PyStatusPyStatus_Error(const char *err_msg)¶

Initialization error with a message.

PyStatusPyStatus_NoMemory(void)¶

Memory allocation failure (out of memory).

PyStatusPyStatus_Exit(int exitcode)¶

Exit Python with the specified exit code.

Functions to handle a status:

intPyStatus_Exception(PyStatus status)¶

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

intPyStatus_IsError(PyStatus status)¶

Is the result an error?

intPyStatus_IsExit(PyStatus status)¶

Is the result an exit?

voidPy_ExitStatusException(PyStatus status)¶

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¶

PyPreConfig¶

Structure used to preinitialize Python:

• Set the Python memory allocator

• Configure the LC_CTYPE locale

• Set the UTF-8 mode

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 memory allocator:

• 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): force usage ofmalloc()

• PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage ofmalloc() with debug hooks

• PYMEM_ALLOCATOR_PYMALLOC (5):Python pymalloc memoryallocator

• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6):Python pymallocmemory allocator with debug hooks

PYMEM_ALLOCATOR_PYMALLOC andPYMEM_ALLOCATOR_PYMALLOC_DEBUGare not supported if Python is configured using--without-pymalloc

SeeMemory Management.

intconfigure_locale¶

Set the LC_CTYPE locale to the user preferred locale? If equals to 0, setcoerce_c_locale andcoerce_c_locale_warn to 0.

intcoerce_c_locale¶

If equals to 2, coerce the C locale; if equals to 1, read the LC_CTYPElocale to decide if it should be coerced.

intcoerce_c_locale_warn¶

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

intdev_mode¶

SeePyConfig.dev_mode.

intisolated¶

SeePyConfig.isolated.

intlegacy_windows_fs_encoding(Windows only)¶

If non-zero, disable UTF-8 Mode, set the Python filesystem encoding tombcs, set the filesystem error handler toreplace.

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

intparse_argv¶

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

intuse_environment¶

SeePyConfig.use_environment.

intutf8_mode¶

If non-zero, enable the UTF-8 mode.

Preinitialization with PyPreConfig¶

Functions to preinitialize Python:

PyStatusPy_PreInitialize(constPyPreConfig *preconfig)¶

Preinitialize Python frompreconfig preconfiguration.

PyStatusPy_PreInitializeFromBytesArgs(constPyPreConfig *preconfig, int argc, char * const *argv)¶

Preinitialize Python frompreconfig preconfiguration and command linearguments (bytes strings).

PyStatusPy_PreInitializeFromArgs(constPyPreConfig *preconfig, int argc, wchar_t * const * argv)¶

Preinitialize Python frompreconfig preconfiguration and command linearguments (wide strings).

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 the 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 Python preinitialization, whereas calling directlymalloc() andfree() is always safe.Py_DecodeLocale() must not be called beforethe preinitialization.

Example using the preinitialization to enable the 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 will speak UTF-8 */Py_Initialize();/* ... use Python API here ... */Py_Finalize();

PyConfig¶

PyConfig¶

Structure containing most parameters to configure Python.

Structure methods:

voidPyConfig_InitPythonConfig(PyConfig *config)¶

Initialize configuration withPython Configuration.

voidPyConfig_InitIsolatedConfig(PyConfig *config)¶

Initialize configuration withIsolated Configuration.

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

Copy the wide character stringstr into*config_str.

Preinitialize Python if needed.

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

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

Preinitialize Python if needed.

PyStatusPyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)¶

Set command line arguments from wide character strings.

Preinitialize Python if needed.

PyStatusPyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)¶

Set command line arguments: decode bytes usingPy_DecodeLocale().

Preinitialize Python if needed.

PyStatusPyConfig_SetWideStringList(PyConfig *config,PyWideStringList *list, Py_ssize_t length, 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.

Preinitialize Python if needed.

voidPyConfig_Clear(PyConfig *config)¶

Release configuration memory.

MostPyConfig methods preinitialize Python if needed. In that case, thePython preinitialization configuration in based on thePyConfig.If configuration fields which are in common withPyPreConfig aretuned, they must be set before calling aPyConfig method:

• dev_mode

• isolated

• parse_argv

• use_environment

Moreover, ifPyConfig_SetArgv() orPyConfig_SetBytesArgv()is used, this method must be called first, 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. Seeparse_argv to parseargv thesame way the regular Python parses Python command line arguments. Ifargv is empty, an empty string is added to ensurethatsys.argv always exists and is never empty.

wchar_t*base_exec_prefix¶

sys.base_exec_prefix.

wchar_t*base_executable¶

sys._base_executable:__PYVENV_LAUNCHER__ environmentvariable value, or copy ofPyConfig.executable.

wchar_t*base_prefix¶

sys.base_prefix.

intbuffered_stdio¶

If equals to 0, enable unbuffered mode, making the stdout and stderrstreams unbuffered.

stdin is always opened in buffered mode.

intbytes_warning¶

If equals to 1, issue a warning when comparingbytes orbytearray withstr, or comparingbytes withint. If equal or greater to 2, raise aBytesWarningexception.

wchar_t*check_hash_pycs_mode¶

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

Valid values:always,never anddefault.

The default value is:default.

intconfigure_c_stdio¶

If non-zero, configure C standard streams (stdio,stdout,stdout). For example, set their mode toO_BINARY on Windows.

intdev_mode¶

Development mode: see-Xdev.

intdump_refs¶

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

Require a debug build of Python (Py_REF_DEBUG macro must be defined).

wchar_t*exec_prefix¶

sys.exec_prefix.

wchar_t*executable¶

sys.executable.

intfaulthandler¶

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

wchar_t*filesystem_encoding¶

Filesystem encoding,sys.getfilesystemencoding().

wchar_t*filesystem_errors¶

Filesystem encoding errors,sys.getfilesystemencodeerrors().

unsigned longhash_seed¶

intuse_hash_seed¶

Randomized hash function seed.

Ifuse_hash_seed is zero, a seed is chosen randomlyat Pythonstartup, andhash_seed is ignored.

wchar_t*home¶

Python home directory.

Initialized fromPYTHONHOME environment variable value bydefault.

intimport_time¶

If non-zero, profile import time.

intinspect¶

Enter interactive mode after executing a script or a command.

intinstall_signal_handlers¶

Install signal handlers?

intinteractive¶

Interactive mode.

intisolated¶

If greater than 0, enable isolated mode:

• sys.path contains neither the script’s directory (computed fromargv[0] or the current directory) nor the user’s site-packagesdirectory.

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

• Setuse_environment anduser_site_directory to 0.

intlegacy_windows_stdio¶

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

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

intmalloc_stats¶

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

The option is ignored if Python is built using--without-pymalloc.

wchar_t*pythonpath_env¶

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

Initialized fromPYTHONPATH environment variable value bydefault.

PyWideStringListmodule_search_paths¶

intmodule_search_paths_set¶

sys.path. Ifmodule_search_paths_set isequal to 0, themodule_search_paths is overriddenby the function calculating thePath Configuration.

intoptimization_level¶

Compilation optimization level:

• 0: Peephole optimizer (and__debug__ is set toTrue)

• 1: Remove assertions, set__debug__ toFalse

• 2: Strip docstrings

intparse_argv¶

If non-zero, parseargv the same way the regularPython command line arguments, and strip Python arguments fromargv: seeCommand Line Arguments.

intparser_debug¶

If non-zero, turn on parser debugging output (for expert only, dependingon compilation options).

intpathconfig_warnings¶

If equal to 0, suppress warnings when calculating thePathConfiguration (Unix only, Windows does not log anywarning). Otherwise, warnings are written intostderr.

wchar_t*prefix¶

sys.prefix.

wchar_t*program_name¶

Program name. Used to initializeexecutable, and inearly error messages.

wchar_t*pycache_prefix¶

sys.pycache_prefix:.pyc cache prefix.

IfNULL,sys.pycache_prefix is set toNone.

intquiet¶

Quiet mode. For example, don’t display the copyright and version messagesin interactive mode.

wchar_t*run_command¶

python3-cCOMMAND argument. Used byPy_RunMain().

wchar_t*run_filename¶

python3FILENAME argument. Used byPy_RunMain().

wchar_t*run_module¶

python3-mMODULE argument. Used byPy_RunMain().

intshow_alloc_count¶

Show allocation counts at exit?

Set to 1 by-Xshowalloccount command line option.

Need a special Python build withCOUNT_ALLOCS macro defined.

intshow_ref_count¶

Show total reference count at exit?

Set to 1 by-Xshowrefcount command line option.

Need a debug build of Python (Py_REF_DEBUG macro must be defined).

intsite_import¶

Import thesite module at startup?

intskip_source_first_line¶

Skip the first line of the source?

wchar_t*stdio_encoding¶

wchar_t*stdio_errors¶

Encoding and encoding errors ofsys.stdin,sys.stdout andsys.stderr.

inttracemalloc¶

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

intuse_environment¶

If greater than 0, useenvironment variables.

intuser_site_directory¶

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

intverbose¶

If non-zero, enable verbose mode.

PyWideStringListwarnoptions¶

sys.warnoptions: options of thewarnings module to buildwarnings filters: lowest to highest priority.

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

intwrite_bytecode¶

If non-zero, write.pyc files.

sys.dont_write_bytecode is initialized to the inverted value ofwrite_bytecode.

PyWideStringListxoptions¶

sys._xoptions.

Ifparse_argv is non-zero,argv arguments are parsed the sameway the regular Python parses command line arguments, and Pythonarguments are stripped fromargv: seeCommand Line Arguments.

Thexoptions options are parsed to set other options: see-Xoption.

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 after Pythonpreinitialization and before the Python initialization.

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)){gotofail;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotofail;}PyConfig_Clear(&config);return;fail:PyConfig_Clear(&config);Py_ExitStatusException(status);}

More complete example modifying the default configuration, read theconfiguration, and then override some parameters:

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;}/* Append our custom search path to sys.path */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, environmentsvariables, 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. Set thePath Configuration (“output fields”) to ignore theseconfiguration files and avoid the function computing the default pathconfiguration.

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) and UTF-8 Mode(PEP 540) depending on the LC_CTYPE locale,PYTHONUTF8 andPYTHONCOERCECLOCALE environment variables.

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)){gotofail;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotofail;}PyConfig_Clear(&config);returnPy_RunMain();fail: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);}

Path Configuration¶

PyConfig contains multiple fields for the path configuration:

• Path configuration inputs:

  • PyConfig.home

  • 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 to 0,module_search_paths is overridden andmodule_search_paths_set is set to 1.

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 to 1. In this case, pathconfiguration input fields are ignored as well.

Setpathconfig_warnings to 0 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

• python._pth (Windows only)

• pybuilddir.txt (Unix only)

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

Multi-Phase Initialization Private Provisional API¶

This section is a private provisional API introducing multi-phaseinitialization, the core feature of thePEP 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 to 0,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 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);}}