Configuración de inicialización de Python¶

PyConfig C API¶

Added in version 3.8.

Python se puede inicializar con Py_InitializeFromConfig() y la estructura PyConfig. Se puede preinicializar con Py_PreInitialize() y la estructura PyPreConfig.

Hay dos tipos de configuración:

The Python Configuration 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 Isolated Configuration 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.

La función Py_RunMain() se puede utilizar para escribir un programa Python personalizado.

Consulte también Inicialización, finalización y subprocesos.

Ver también

PEP 587 «Configuración de inicialización de Python».

Ejemplo¶

Ejemplo de Python personalizado que siempre se ejecuta en modo aislado:

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    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)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}

PyWideStringList¶

type PyWideStringList¶

Lista de cadenas de caracteres wchar_t*.

Si length no es cero, items no deben ser NULL y todas las cadenas de caracteres deben ser no NULL.

Métodos:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶

Agregar item a list.

Python debe estar preinicializado para llamar a esta función.

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

Inserta item en list en index.

Si index es mayor o igual que el largo de list, agrega item a list.

index must be greater than or equal to 0.

Python debe estar preinicializado para llamar a esta función.

Campos de estructura:

Py_ssize_t length¶: Longitud de la lista.

wchar_t **items¶: Elementos de la lista.

PyStatus¶

type PyStatus¶

Estructura para almacenar el estado de una función de inicialización: éxito, error o salida.

Para un error, puede almacenar el nombre de la función C que creó el error.

Campos de estructura:

int exitcode¶: Código de salida El argumento pasó a exit().

const char *err_msg¶: Mensaje de error.

const char *func¶: El nombre de la función que creó un error puede ser NULL.

Funciones para crear un estado:

PyStatus PyStatus_Ok(void)¶: Éxito.

PyStatus PyStatus_Error(const char *err_msg)¶

Error de inicialización con un mensaje.

err_msg no debe ser NULL.

PyStatus PyStatus_NoMemory(void)¶: Error de asignación de memoria (sin memoria).

PyStatus PyStatus_Exit(int exitcode)¶: Sale de Python con el código de salida especificado.

Funciones para manejar un estado:

int PyStatus_Exception(PyStatus status)¶: ¿Es el estado un error o una salida? Si es verdadero, la excepción debe ser manejada; por ejemplo llamando a Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)¶: ¿Es el resultado un error?

int PyStatus_IsExit(PyStatus status)¶: ¿El resultado es una salida?

void Py_ExitStatusException(PyStatus status)¶: Llama a exit(exitcode) si status es una salida. Imprime el mensaje de error y sale con un código de salida distinto de cero si status es un error. Solo se debe llamar si PyStatus_Exception(status) no es cero.

Nota

Internamente, Python usa macros que establecen PyStatus.func, mientras que las funciones para crear un estado establecen func en NULL.

Ejemplo:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig¶

type PyPreConfig¶

Estructura utilizada para preinicializar Python.

Función para inicializar una preconfiguración:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: Inicializa la preconfiguración con Configuración de Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: Inicializa la preconfiguración con Configuración aislada.

Campos de estructura:

int allocator¶

Nombre de los asignadores de memoria de Python:

PYMEM_ALLOCATOR_NOT_SET (0): no cambia asignadores de memoria (usa los valores predeterminados)
PYMEM_ALLOCATOR_DEFAULT (1): asignadores de memoria predeterminados.
PYMEM_ALLOCATOR_DEBUG (2): asignadores de memoria predeterminados con ganchos de depuración.
PYMEM_ALLOCATOR_MALLOC (3): usa malloc() de la biblioteca C.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): fuerza el uso de malloc() con ganchos de depuración.
PYMEM_ALLOCATOR_PYMALLOC (5): asignador de memoria pymalloc de Python
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): asignador de memoria pymalloc de Python con ganchos de depuración.
PYMEM_ALLOCATOR_MIMALLOC (6): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): use mimalloc, a fast malloc replacement with debug hooks.

PYMEM_ALLOCATOR_PYMALLOC y PYMEM_ALLOCATOR_PYMALLOC_DEBUG no son compatibles si Python es configurado usando --without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC and PYMEM_ALLOCATOR_MIMALLOC_DEBUG are not supported if Python is configured using --without-mimalloc or if the underlying atomic support isn’t available.

Ver Administración de memorias.

Predeterminado: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale¶

Set the LC_CTYPE locale to the user preferred locale.

If equals to 0, set coerce_c_locale and coerce_c_locale_warn members to 0.

Vea el locale encoding.

Predeterminado: 1 en la configuración de Python, 0 en la configuración aislada.

int coerce_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.

Vea el locale encoding.

Predeterminado: -1 en la configuración de Python, 0 en la configuración aislada.

int coerce_c_locale_warn¶

Si no es cero, emita una advertencia si la configuración regional C está coaccionada.

Predeterminado: -1 en la configuración de Python, 0 en la configuración aislada.

int dev_mode¶

Python Development Mode: see PyConfig.dev_mode.

Por defecto: -1 en modo Python, 0 en modo aislado.

int isolated¶

Modo aislado: consulte PyConfig.isolated.

Por defecto: 0 en modo Python, 1 en modo aislado.

int legacy_windows_fs_encoding¶

Si no es cero:

Establezca PyPreConfig.utf8_mode en 0,
Establezca PyConfig.filesystem_encoding en "mbcs",
Establezca PyConfig.filesystem_errors en "replace".

Initialized from the PYTHONLEGACYWINDOWSFSENCODING environment variable value.

Solo disponible en Windows. La macro #ifdef MS_WINDOWS se puede usar para el código específico de Windows.

Predeterminado: 0.

int parse_argv¶

Si no es cero, Py_PreInitializeFromArgs() y Py_PreInitializeFromBytesArgs() analizan su argumento argv de la misma manera que Python analiza los argumentos de la línea de comandos: ver Argumentos de línea de comandos.

Predeterminado: 1 en la configuración de Python, 0 en la configuración aislada.

int use_environment¶

¿Utiliza variables de entorno? Consulte PyConfig.use_environment.

Predeterminado: 1 en la configuración de Python y 0 en la configuración aislada.

int utf8_mode¶

Si es distinto de cero, habilite Python UTF-8 Mode.

Set to 0 or 1 by the -X utf8 command line option and the PYTHONUTF8 environment variable.

También se pone a 1 si la configuración regional LC_CTYPE es C o POSIX.

Predeterminado: -1 en la configuración de Python y 0 en la configuración aislada.

Preinicialización de Python con PyPreConfig¶

La preinicialización de Python:

Establecer los asignadores de memoria de Python (PyPreConfig.allocator)
Configurar la configuración regional LC_CTYPE (locale encoding)
Establecer el Python UTF-8 Mode (PyPreConfig.utf8_mode)

La preconfiguración actual (tipo PyPreConfig) se almacena en _PyRuntime.preconfig.

Funciones para preinicializar Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶

Preinicializa Python desde la preconfiguración preconfig.

preconfig no debe ser NULL.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)¶

Preinicializa Python desde la preconfiguración preconfig.

Analice los argumentos de la línea de comando argv (cadenas de bytes) si parse_argv de preconfig no es cero.

preconfig no debe ser NULL.

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)¶

Preinicializa Python desde la preconfiguración preconfig.

Analice los argumentos de la línea de comando argv (cadenas anchas) si parse_argv de preconfig no es cero.

preconfig no debe ser NULL.

La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

Para Configuración de Python (PyPreConfig_InitPythonConfig()), si Python se inicializa con argumentos de línea de comando, los argumentos de la línea de comando también deben pasarse para preinicializar Python, ya que tienen un efecto en la preconfiguración como codificaciones. Por ejemplo, la opción de línea de comando -X utf8 habilita el Python UTF-8 Mode.

PyMem_SetAllocator() se puede llamar después de Py_PreInitialize() y antes Py_InitializeFromConfig() para instalar un asignador de memoria personalizado. Se puede llamar antes Py_PreInitialize() si PyPreConfig.allocator está configurado en PYMEM_ALLOCATOR_NOT_SET.

Las funciones de asignación de memoria de Python como PyMem_RawMalloc() no deben usarse antes de la preinicialización de Python, mientras que llamar directamente a malloc() y free() siempre es seguro. No se debe llamar a Py_DecodeLocale() antes de la preinicialización de Python.

Ejemplo usando la preinicialización para habilitar el Python UTF-8 Mode

PyStatus status;
PyPreConfig preconfig;
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¶

type PyConfig¶

Estructura que contiene la mayoría de los parámetros para configurar Python.

Cuando termine, se debe utilizar la función PyConfig_Clear() para liberar la memoria de configuración.

Métodos de estructura:

void PyConfig_InitPythonConfig(PyConfig *config)¶: Inicialice la configuración con la Configuración de Python.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Inicialice la configuración con la Configuración Aislada.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)¶

Copia la cadena de caracteres anchos str en *config_str.

Preinicializa Python si es necesario.

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

Decodifique str usando Py_DecodeLocale() y establezca el resultado en *config_str.

Preinicializa Python si es necesario.

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

Configure los argumentos de la línea de comando (miembro argv de config) de la lista argv de cadenas de caracteres anchas.

Preinicializa Python si es necesario.

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

Establezca argumentos de línea de comando (miembro argv de config) de la lista argv de cadenas de bytes. Decodifica bytes usando Py_DecodeLocale().

Preinicializa Python si es necesario.

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)¶

Establece la lista de cadenas de caracteres anchas list a length y items.

Preinicializa Python si es necesario.

PyStatus PyConfig_Read(PyConfig *config)¶

Lee toda la configuración de Python.

Los campos que ya están inicializados no se modifican.

Los campos para la configuración de ruta ya no se calculan ni modifican al llamar a esta función, a partir de Python 3.11.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Preinicializa Python si es necesario.

Distinto en la versión 3.10: Los argumentos PyConfig.argv ahora solo se analizan una vez, PyConfig.parse_argv se establece en 2 después de analizar los argumentos y los argumentos solo se analizan si PyConfig.parse_argv es igual a 1.

Distinto en la versión 3.11: PyConfig_Read() ya no calcula todas las rutas, por lo que los campos listados en Python Path Configuration ya no pueden ser actualizados hasta que se llame a Py_InitializeFromConfig().

void PyConfig_Clear(PyConfig *config)¶: Libera memoria de configuración.

La mayoría de los método PyConfig preinitializan Python si es necesario. En ese caso, la configuración de preinicialización de Python (PyPreConfig) se basa en PyConfig. Si se ajustan los campos de configuración que son comunes con PyPreConfig, deben establecerse antes de llamar a un método PyConfig:

PyConfig.dev_mode
PyConfig.isolated
PyConfig.parse_argv
PyConfig.use_environment

Moreover, if PyConfig_SetArgv() or PyConfig_SetBytesArgv() is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if parse_argv is non-zero).

Quien llama de estos métodos es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

Campos de estructura:

PyWideStringList argv¶

Set sys.argv command line arguments based on argv. These parameters are similar to those passed to the program’s main() function with the difference that the first entry should refer to the script file to be executed rather than the executable hosting the Python interpreter. If there isn’t a script that will be run, the first entry in argv can be an empty string.

Configure parse_argv en 1 para analizar argv de la misma manera que Python normal analiza los argumentos de la línea de comandos de Python y luego quita los argumentos de Python de argv.

Si argv está vacío, se agrega una cadena vacía para garantizar que sys.argv siempre exista y nunca esté vacío.

Valor predeterminado: NULL.

Consulte también el miembro orig_argv.

int safe_path¶

Si es igual a cero, Py_RunMain() agrega una ruta potencialmente insegura a sys.path al inicio:

Si argv[0] es igual a L"-m" (python -m module), añade el directorio de trabajo actual.
If running a script (python script.py), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.
En caso contrario (python -c code and python), añade una cadena vacía, que significa el directorio de trabajo actual.

Set to 1 by the -P command line option and the PYTHONSAFEPATH 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.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

Inicialización con PyConfig¶

Initializing the interpreter from a populated configuration struct is handled by calling Py_InitializeFromConfig().

La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

Si se utilizan PyImport_FrozenModules(), PyImport_AppendInittab() o PyImport_ExtendInittab(), deben establecerse o llamarse después de la preinicialización de Python y antes de la inicialización de Python. Si Python se inicializa varias veces, se debe llamar a PyImport_AppendInittab() o PyImport_ExtendInittab() antes de cada inicialización de Python.

La configuración actual (tipo PyConfig) se almacena en PyInterpreterState.config.

Ejemplo de configuración del nombre del programa:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    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)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    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:

PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    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)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* 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)) {
        goto done;
    }
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

Configuración aislada¶

PyPreConfig_InitIsolatedConfig() y las funciones PyConfig_InitIsolatedConfig() crean una configuración para aislar Python del sistema. Por ejemplo, para incrustar Python en una aplicación.

This configuration ignores global configuration variables, environment variables, command line arguments (PyConfig.argv 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.

Los archivos de configuración se siguen utilizando con esta configuración para determinar las rutas que no se especifican. Asegúrese de que se especifica PyConfig.home para evitar que se calcule la configuración de la ruta por defecto.

Configuración de Python¶

PyPreConfig_InitPythonConfig() y las funciones PyConfig_InitPythonConfig() crean una configuración para construir un Python personalizado que se comporta como el Python normal.

Las variables de entorno y los argumentos de la línea de comandos se utilizan para configurar Python, mientras que las variables de configuración global se ignoran.

Esta función habilita la coerción de configuración regional C (PEP 538) y Python UTF-8 Mode (PEP 540) según la configuración regional LC_CTYPE, las variables de entorno PYTHONUTF8 y PYTHONCOERCECLOCALE.

Configuración de la ruta de Python¶

PyConfig contiene múltiples campos para la configuración de ruta:

Entradas de configuración de ruta:
- PyConfig.home
- PyConfig.platlibdir
- PyConfig.pathconfig_warnings
- PyConfig.program_name
- PyConfig.pythonpath_env
- directorio de trabajo actual: para obtener rutas absolutas
- Variable de entorno PATH para obtener la ruta completa del programa (de PyConfig.program_name)
- Variable de entorno __PYVENV_LAUNCHER__
- (Solo Windows) Rutas de aplicación en el registro en «SoftwarePythonPythonCoreX.YPythonPath» de HKEY_CURRENT_USER y HKEY_LOCAL_MACHINE (donde X.Y es la versión de Python).
Campos de salida de configuración de ruta:

Si al menos un «campo de salida» no está establecido, Python calcula la configuración de la ruta para rellenar los campos no establecidos. Si module_search_paths_set es igual a 0, module_search_paths se anula y module_search_paths_set se establece en 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 pathconfig_warnings to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).

Si base_prefix o los campos base_exec_prefix no están establecidos, heredan su valor de prefix y exec_prefix respectivamente.

Py_RunMain() y Py_Main() modifican sys.path:

Si run_filename está configurado y es un directorio que contiene un script __main__.py, anteponga run_filename a sys.path.
Si isolated es cero:
- Si run_module está configurado, anteponga el directorio actual a sys.path. No haga nada si el directorio actual no se puede leer.
- Si run_filename está configurado, anteponga el directorio del nombre del archivo a sys.path.
- De lo contrario, anteponga una cadena de caracteres vacía a sys.path.

Si site_import no es cero, sys.path puede ser modificado por el módulo site. Si user_site_directory no es cero y el directorio del paquete del sitio del usuario existe, el módulo site agrega el directorio del paquete del sitio del usuario a sys.path.

La configuración de ruta utiliza los siguientes archivos de configuración:

pyvenv.cfg
archivo ._pth (ej: python._pth)
pybuilddir.txt (sólo Unix)

Si un archivo ._pth está presente:

Set isolated to 1.
Set use_environment to 0.
Set site_import to 0.
Set safe_path to 1.

The __PYVENV_LAUNCHER__ environment variable is used to set PyConfig.base_executable.

PyInitConfig C API¶

C API to configure the Python initialization (PEP 741).

Added in version 3.14.

Create Config¶

struct PyInitConfig¶: Opaque structure to configure the Python initialization.

PyInitConfig *PyInitConfig_Create(void)¶

Create a new initialization configuration using Isolated Configuration default values.

It must be freed by PyInitConfig_Free().

Return NULL on memory allocation failure.

void PyInitConfig_Free(PyInitConfig *config)¶

Free memory of the initialization configuration config.

If config is NULL, no operation is performed.

Error Handling¶

int PyInitConfig_GetError(PyInitConfig *config, const char **err_msg)¶

Get the config error message.

Set *err_msg and return 1 if an error is set.
Set *err_msg to NULL and return 0 otherwise.

An error message is an UTF-8 encoded string.

If config has an exit code, format the exit code as an error message.

The error message remains valid until another PyInitConfig function is called with config. The caller doesn’t have to free the error message.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶

Get the config exit code.

Set *exitcode and return 1 if config has an exit code set.
Return 0 if config has no exit code set.

Only the Py_InitializeFromInitConfig() function can set an exit code if the parse_argv option is non-zero.

An exit code can be set when parsing the command line failed (exit code 2) or when a command line option asks to display the command line help (exit code 0).

Get Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

int PyInitConfig_HasOption(PyInitConfig *config, const char *name)¶

Test if the configuration has an option called name.

Return 1 if the option exists, or return 0 otherwise.

int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)¶

Get an integer configuration option.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)¶

Get a string configuration option as a null-terminated UTF-8 encoded string.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

*value can be set to NULL if the option is an optional string and the option is unset.

On success, the string must be released with free(value) if it’s not NULL.

int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)¶

Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.

Set *length and *value, and return 0 on success.
Set an error in config and return -1 on error.

On success, the string list must be released with PyInitConfig_FreeStrList(length, items).

void PyInitConfig_FreeStrList(size_t length, char **items)¶: Free memory of a string list created by PyInitConfig_GetStrList().

Set Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

Some configuration options have side effects on other options. This logic is only implemented when Py_InitializeFromInitConfig() is called, not by the «Set» functions below. For example, setting dev_mode to 1 does not set faulthandler to 1.

int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)¶

Set an integer configuration option.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)¶

Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char *const *items)¶

Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.

Return 0 on success.
Set an error in config and return -1 on error.

Module¶

int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))¶

Add a built-in extension module to the table of built-in modules.

The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import.

Return 0 on success.
Set an error in config and return -1 on error.

If Python is initialized multiple times, PyInitConfig_AddModule() must be called at each Python initialization.

Similar to the PyImport_AppendInittab() function.

Initialize Python¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

Initialize Python from the initialization configuration.

Return 0 on success.
Set an error in config and return -1 on error.
Set an exit code in config and return -1 if Python wants to exit.

See PyInitConfig_GetExitcode() for the exit code case.

Ejemplo¶

Example initializing Python, set configuration options of various types, return -1 on error:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) {
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    }

    // Set an integer (dev mode)
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Set a list of UTF-8 strings (argv)
    char *argv[] = {"my_program", "-c", "pass"};
    if (PyInitConfig_SetStrList(config, "argv",
                                 Py_ARRAY_LENGTH(argv), argv) < 0) {
        goto error;
    }

    // Set a UTF-8 string (program name)
    if (PyInitConfig_SetStr(config, "program_name", L"my_program") < 0) {
        goto error;
    }

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    PyInitConfig_Free(config);
    return 0;

error:
    {
        // Display the error message
        // This uncommon braces style is used, because you cannot make
        // goto targets point to variable declarations.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);

        return -1;
    }
}

Runtime Python configuration API¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

Some options are read from the sys attributes. For example, the option "argv" is read from sys.argv.

PyObject *PyConfig_Get(const char *name)¶

Get the current runtime value of a configuration option as a Python object.

Return a new reference on success.
Set an exception and return NULL on error.

The object type depends on the configuration option. It can be:

bool
int
str
list[str]
dict[str, str]

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

int PyConfig_GetInt(const char *name, int *value)¶

Similar to PyConfig_Get(), but get the value as a C int.

Return 0 on success.
Set an exception and return -1 on error.

Added in version 3.14.

PyObject *PyConfig_Names(void)¶

Get all configuration option names as a frozenset.

Return a new reference on success.
Set an exception and return NULL on error.

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

int PyConfig_Set(const char *name, PyObject *value)¶

Set the current runtime value of a configuration option.

Raise a ValueError if there is no option name.
Raise a ValueError if value is an invalid value.
Raise a ValueError if the option is read-only (cannot be set).
Raise a TypeError if value has not the proper type.

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

Py_GetArgcArgv()¶

void Py_GetArgcArgv(int *argc, wchar_t ***argv)¶

Obtiene los argumentos originales de la línea de comandos, antes de que Python los modificara.

Ver también el miembro PyConfig.orig_argv.

API Provisional Privada de Inicialización Multifásica¶

This section is a private provisional API introducing multi-phase initialization, the core feature of PEP 432:

Fase de inicialización «Core», «Python mínimo»:
- Tipos incorporados;
- Excepciones incorporadas;
- Módulos incorporados y congelados;
- El módulo sys solo se inicializa parcialmente (por ejemplo sys.path aún no existe).
Fase de inicialización «principal», Python está completamente inicializado:
- Instala y configura importlib;
- Aplique la Configuración de ruta;
- Instala manejadores de señal;
- Finaliza la inicialización del módulo sys (por ejemplo: crea sys.stdout y sys.path);
- Habilita características opcionales como faulthandler y tracemalloc;
- Importe el módulo site;
- etc.

API provisional privada:

PyConfig._init_main: if set to 0, Py_InitializeFromConfig() stops at the «Core» initialization phase.

PyStatus _Py_InitializeMain(void)¶: Vaya a la fase de inicialización «Principal», finalice la inicialización de Python.

No se importa ningún módulo durante la fase «Core» y el módulo importlib no está configurado: la Configuración de ruta solo se aplica durante la fase «Principal». Puede permitir personalizar Python en Python para anular o ajustar Configuración de ruta, tal vez instale un importador personalizado sys.meta_path o un enlace de importación, etc.

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

La fase «Núcleo» no está definida correctamente: lo que debería estar y lo que no debería estar disponible en esta fase aún no se ha especificado. La API está marcada como privada y provisional: la API se puede modificar o incluso eliminar en cualquier momento hasta que se diseñe una API pública adecuada.

Ejemplo de ejecución de código Python entre las fases de inicialización «Core» y «Main»:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    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() */
    int res = 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);
    }
}

Configuración de inicialización de Python¶

PyConfig C API¶

Ejemplo¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

Preinicialización de Python con PyPreConfig¶

PyConfig¶

Inicialización con PyConfig¶

Configuración aislada¶

Configuración de Python¶

Configuración de la ruta de Python¶

PyInitConfig C API¶

Create Config¶

Error Handling¶

Get Options¶

Set Options¶

Module¶

Initialize Python¶

Ejemplo¶

Runtime Python configuration API¶

Py_GetArgcArgv()¶

API Provisional Privada de Inicialización Multifásica¶

Tabla de contenido

Tema anterior

Próximo tema

Esta página