Configuración de inicialización de Python

Nuevo en la versión 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 debe ser mayor o igual que 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_PYMALLOC y PYMEM_ALLOCATOR_PYMALLOC_DEBUG no son compatibles si Python es configurado usando --without-pymalloc.

Ver Administración de memorias.

Predeterminado: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

Si es igual a 0, establezca los miembros coerce_c_locale y coerce_c_locale_warn en 0.

Vea el locale encoding.

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

int coerce_c_locale

Si es igual a 2, imponga la configuración regional C.

Si es igual a 1, lea la configuración regional LC_CTYPE para decidir si debe ser coaccionado.

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

Si es distinto de cero, habilita el Modo de desarrollo de Python: consulte 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:

Inicializado desde valor de variable de entorno PYTHONLEGACYWINDOWSFSENCODING.

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.

Establecido por la opción de línea de comando -X utf8 y la variable de entorno PYTHONUTF8.

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:

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.

La función PyConfig_Read() solo analiza los argumentos PyConfig.argv una vez: PyConfig.parse_argv se establece en 2 después de analizar los argumentos. Dado que los argumentos de Python se eliminan de PyConfig.argv, analizar los argumentos dos veces analizaría las opciones de la aplicación como opciones de Python.

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.

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:

Además, si se usa PyConfig_SetArgv() o PyConfig_SetBytesArgv(), este método debe llamarse antes que otros métodos, ya que la configuración de preinicialización depende de los argumentos de la línea de comando (si parse_argv no es cero).

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

Argumentos de la línea de comando: sys.argv.

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.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

wchar_t *base_executable

Ejecutable base de Python: sys._base_executable.

Establecido por la variable de entorno __PYVENV_LAUNCHER__.

Establecido desde PyConfig.executable si NULL.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

wchar_t *base_prefix

sys.base_prefix.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

int buffered_stdio

Si es igual a 0 y configure_c_stdio no es cero, deshabilite el almacenamiento en búfer en las secuencias C stdout y stderr.

Establecido en 0 por la opción de línea de comando -u y la variable de entorno PYTHONUNBUFFERED.

stdin siempre se abre en modo de búfer.

Predeterminado: 1.

int bytes_warning

Si es igual a 1, emite una advertencia al comparar bytes o bytearray con str, o al comparar bytes con int.

Si es igual o mayor a 2, lanza una excepción BytesWarning en estos casos.

Incrementado por la opción de línea de comando -b.

Predeterminado: 0.

int warn_default_encoding

Si no es cero, emite una advertencia EncodingWarning cuando io.TextIOWrapper usa su codificación predeterminada. Consulte EncodingWarning opcional para obtener más detalles.

Predeterminado: 0.

Nuevo en la versión 3.10.

wchar_t *check_hash_pycs_mode

Controla el comportamiento de validación de archivos .pyc basados en hash: valor de la opción de línea de comando --check-hash-based-pycs.

Valores válidos:

  • L"always": Calcula el hash el archivo fuente para invalidación independientemente del valor de la marca “check_source”.

  • L"never": suponga que los pycs basados en hash siempre son válidos.

  • L"default": El indicador “check_source” en pycs basados en hash determina la invalidación.

Predeterminado: L"default".

Consulte también PEP 552 «Pycs deterministas».

int configure_c_stdio

Si es distinto de cero, configure los flujos estándar de C:

  • En Windows, configure el modo binario (O_BINARY) en stdin, stdout y stderr.

  • Si buffered_stdio es igual a cero, deshabilite el almacenamiento en búfer de los flujos stdin, stdout y stderr.

  • Si interactive no es cero, habilite el almacenamiento en búfer de flujo en stdin y stdout (solo stdout en Windows).

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

int dev_mode

Si es distinto de cero, habilita Modo de desarrollo de Python.

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

int dump_refs

Dump Python references?

Si no es cero, volcar todos los objetos que aún están vivos en la salida.

Establecido en 1 por la variable de entorno PYTHONDUMPREFS.

Necesita una compilación especial de Python con la macro Py_TRACE_REFS definida: consulte la opción de configure --with-trace-refs option.

Predeterminado: 0.

wchar_t *exec_prefix

El prefijo de directorio específico del sitio donde se instalan los archivos Python dependientes de la plataforma: sys.exec_prefix.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

wchar_t *executable

La ruta absoluta del binario ejecutable para el intérprete de Python: sys.executable.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

int faulthandler

¿Habilitar administrador de fallas?

Si no es cero, llama a faulthandler.enable() al inicio.

Establecido en 1 por -X faulthandler y la variable de entorno PYTHONFAULTHANDLER.

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

wchar_t *filesystem_encoding

Codificación del sistema de archvios: sys.getfilesystemencoding().

En macOS, Android y VxWorks: use "utf-8" de forma predeterminada.

En Windows: utilice "utf-8" de forma predeterminada o "mbcs" si legacy_windows_fs_encoding de PyPreConfig no es cero.

Codificación predeterminada en otras plataformas:

  • "utf-8" si PyPreConfig.utf8_mode es distinto de cero.

  • "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" si nl_langinfo(CODESET) retorna una cadena vacía.

  • De lo contrario, utilice el resultado locale encoding: nl_langinfo(CODESET).

Al inicio de Python, el nombre de codificación se normaliza al nombre del códec de Python. Por ejemplo, "ANSI_X3.4-1968" se reemplaza por "ascii".

Consulte también el miembro filesystem_errors.

wchar_t *filesystem_errors

Manejador de errores del sistema de archivos: sys.getfilesystemencodeerrors().

En Windows: utilice "surrogatepass" de forma predeterminada o "replace" si legacy_windows_fs_encoding de PyPreConfig no es cero.

En otras plataformas: utilice "surrogateescape" de forma predeterminada.

Controladores de errores admitidos:

  • "strict"

  • "surrogateescape"

  • "surrogatepass" (solo compatible con la codificación UTF-8)

Consulte también el miembro filesystem_encoding.

unsigned long hash_seed
int use_hash_seed

Funciones de semillas aleatorias hash.

Si use_hash_seed es cero, se elige una semilla al azar en el inicio de Python y se ignora hash_seed.

Establecido por la variable de entorno PYTHONHASHSEED.

Valor predeterminado de use_hash_seed: -1 en modo Python, 0 en modo aislado.

wchar_t *home

Directorio de inicio de Python.

Si se ha llamado a Py_SetPythonHome(), use su argumento si no es NULL.

Establecido por la variable de entorno PYTHONHOME.

Valor predeterminado: NULL.

Parte de la entrada Python Path Configuration.

int import_time

Si no es cero, el tiempo de importación del perfil.

Configure el 1 mediante la opción -X importtime y la variable de entorno PYTHONPROFILEIMPORTTIME.

Predeterminado: 0.

int inspect

Ingresa al modo interactivo después de ejecutar un script o un comando.

Si es mayor que 0, habilite inspeccionar: cuando se pasa una secuencia de comandos como primer argumento o se usa la opción -c, ingrese al modo interactivo después de ejecutar la secuencia de comandos o el comando, incluso cuando sys.stdin no parezca ser una terminal.

Incrementado por la opción de línea de comando -i. Establecido en 1 si la variable de entorno PYTHONINSPECT no está vacía.

Predeterminado: 0.

int install_signal_handlers

¿Instalar controladores de señales de Python?

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

int interactive

Si es mayor que 0, habilita el modo interactivo (REPL).

Incrementado por la opción de línea de comando -i.

Predeterminado: 0.

int isolated

Si es mayor que 0, habilite el modo aislado:

  • sys.path no contiene ni el directorio del script (calculado a partir de argv[0] o el directorio actual) ni el directorio de paquetes del sitio del usuario.

  • Python REPL no importa readline ni habilita la configuración predeterminada de readline en mensajes interactivos.

  • Establece use_environment y user_site_directory en 0.

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

Ver también PyPreConfig.isolated.

int legacy_windows_stdio

Si no es cero, usa io.FileIO en lugar de io.WindowsConsoleIO para sys.stdin, sys.stdout y sys.stderr.

Establecido en 1 si la variable de entorno PYTHONLEGACYWINDOWSSTDIO está establecida en una cadena no vacía.

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

Predeterminado: 0.

Consulte también PEP 528 (Cambiar la codificación de la consola de Windows a UTF-8).

int malloc_stats

Si no es cero, volcar las estadísticas en Asignador de memoria Python pymalloc en la salida.

Establecido en 1 por la variable de entorno PYTHONMALLOCSTATS.

La opción se ignora si Python es configurado usando la opción --without-pymalloc.

Predeterminado: 0.

wchar_t *platlibdir

Nombre del directorio de la biblioteca de la plataforma: sys.platlibdir.

Establecido por la variable de entorno PYTHONPLATLIBDIR.

Predeterminado: valor de la macro PLATLIBDIR que establece la opción configure --with-platlibdir (predeterminado: "lib").

Parte de la entrada Python Path Configuration.

Nuevo en la versión 3.9.

wchar_t *pythonpath_env

Rutas de búsqueda de módulos (sys.path) como una cadena separada por DELIM (os.path.pathsep).

Establecido por la variable de entorno PYTHONPATH.

Valor predeterminado: NULL.

Parte de la entrada Python Path Configuration.

PyWideStringList module_search_paths
int module_search_paths_set

Rutas de búsqueda del módulo: sys.path.

Si module_search_paths_set es igual a 0, la función que calcula Python Path Configuration anula module_search_paths y establece module_search_paths_set en 1.

Por defecto: lista vacía (module_search_paths) y 0 (module_search_paths_set).

Parte de la salida Python Path Configuration.

int optimization_level

Nivel de optimización de compilación:

  • 0: Optimizador de mirilla, configure __debug__ en True.

  • 1: Nivel 0, elimina las aserciones, establece __debug__ en False.

  • 2: Nivel 1, elimina docstrings.

Incrementado por la opción de línea de comando -O. Establecido en el valor de la variable de entorno PYTHONOPTIMIZE.

Predeterminado: 0.

PyWideStringList orig_argv

La lista de los argumentos originales de la línea de comandos pasados al ejecutable de Python: sys.orig_argv.

Si la lista orig_argv está vacía y argv no es una lista que solo contiene una cadena vacía, PyConfig_Read() copia argv en orig_argv antes de modificar argv (si parse_argv no es cero).

Consulte también el miembro argv y la función Py_GetArgcArgv().

Predeterminado: lista vacía.

Nuevo en la versión 3.10.

int parse_argv

¿Analizar los argumentos de la línea de comando?

Si es igual a 1, analiza argv de la misma forma que Python normal analiza argumentos de línea de comando y elimina los argumentos de Python de argv.

La función PyConfig_Read() solo analiza los argumentos PyConfig.argv una vez: PyConfig.parse_argv se establece en 2 después de analizar los argumentos. Dado que los argumentos de Python se eliminan de PyConfig.argv, analizar los argumentos dos veces analizaría las opciones de la aplicación como opciones de Python.

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

Distinto en la versión 3.10: Los argumentos PyConfig.argv ahora solo se analizan si PyConfig.parse_argv es igual a 1.

int parser_debug

Modo de depuración del analizador. Si es mayor que 0, active la salida de depuración del analizador (solo para expertos, según las opciones de compilación).

Incrementado por la opción de línea de comando -d. Establecido en el valor de la variable de entorno PYTHONDEBUG.

Predeterminado: 0.

int pathconfig_warnings

En Unix, si es distinto de cero, el cálculo de Python Path Configuration puede registrar advertencias en stderr. Si es igual a 0, suprima estas advertencias.

No tiene ningún efecto en Windows.

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

Parte de la entrada Python Path Configuration.

wchar_t *prefix

El prefijo de directorio específico del sitio donde se instalan los archivos Python independientes de la plataforma: sys.prefix.

Valor predeterminado: NULL.

Parte de la salida Python Path Configuration.

wchar_t *program_name

Nombre del programa utilizado para inicializar executable y en los primeros mensajes de error durante la inicialización de Python.

  • Si se ha llamado a Py_SetProgramName(), usa su argumento.

  • En macOS, usa la variable de entorno PYTHONEXECUTABLE si está configurada.

  • Si se define la macro WITH_NEXT_FRAMEWORK, utiliza la variable de entorno __PYVENV_LAUNCHER__ si está configurada.

  • Utiliza argv[0] de argv si está disponible y no está vacío.

  • De lo contrario, utiliza L"python" en Windows o L"python3" en otras plataformas.

Valor predeterminado: NULL.

Parte de la entrada Python Path Configuration.

wchar_t *pycache_prefix

Directorio donde se escriben los archivos .pyc almacenados en caché: sys.pycache_prefix.

Establecido por la opción de línea de comando -X pycache_prefix=PATH y la variable de entorno PYTHONPYCACHEPREFIX.

Si NULL, sys.pycache_prefix es establecido a None.

Valor predeterminado: NULL.

int quiet

Modo silencioso. Si es mayor que 0, no muestre los derechos de autor y la versión al inicio de Python en modo interactivo.

Incrementado por la opción de línea de comando -q.

Predeterminado: 0.

wchar_t *run_command

Valor de la opción de línea de comando -c.

Usado por Py_RunMain().

Valor predeterminado: NULL.

wchar_t *run_filename

Nombre de archivo pasado en la línea de comando: argumento de línea de comando final sin -c o -m.

Por ejemplo, el comando python3 script.py arg lo establece en script.py.

Usado por Py_RunMain().

Valor predeterminado: NULL.

wchar_t *run_module

Valor de la opción de línea de comando -m.

Usado por Py_RunMain().

Valor predeterminado: NULL.

int show_ref_count

¿Mostrar el recuento de referencia total en la salida?

Establecido en 1 por la opción de línea de comandos -X showrefcount.

Necesita una compilación de depuración de Python (se debe definir la macro Py_REF_DEBUG).

Predeterminado: 0.

int site_import

¿Importar el módulo site al inicio?

Si es igual a cero, desactive la importación del sitio del módulo y las manipulaciones dependientes del sitio de sys.path que conlleva.

También deshabilite estas manipulaciones si el módulo site se importa explícitamente más tarde (llame a site.main() si desea que se activen).

Establecido en 0 mediante la opción de línea de comando -S.

sys.flags.no_site se establece en el valor invertido de site_import.

Predeterminado: 1.

int skip_source_first_line

Si no es cero, omita la primera línea de la fuente PyConfig.run_filename.

Permite el uso de formas de #!cmd que no son Unix. Esto está destinado únicamente a un truco específico de DOS.

Establecido en 1 mediante la opción de línea de comando -x.

Predeterminado: 0.

wchar_t *stdio_encoding
wchar_t *stdio_errors

Codificación y errores de codificación de sys.stdin, sys.stdout y sys.stderr (pero sys.stderr siempre usa el controlador de errores "backslashreplace").

Si se ha llamado a Py_SetStandardStreamEncoding(), utilice sus argumentos error y errors si no son NULL.

Utilice la variable de entorno PYTHONIOENCODING si no está vacía.

Codificación predeterminada:

Manejador de errores predeterminado:

  • En Windows: use "surrogateescape".

  • "surrogateescape" si PyPreConfig.utf8_mode no es cero o si la configuración regional LC_CTYPE es «C» o «POSIX».

  • "strict" de lo contrario.

int tracemalloc

¿Habilitar tracemalloc?

Si no es cero, llama a tracemalloc.start() al inicio.

Establecido por la opción de línea de comando -X tracemalloc=N y por la variable de entorno PYTHONTRACEMALLOC.

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

int use_environment

¿Utiliza variables de entorno?

Si es igual a cero, ignora las variables de entorno.

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

int user_site_directory

Si es distinto de cero, agregue el directorio del sitio del usuario a sys.path.

Establecido en 0 por las opciones de línea de comando -s y -I.

Establecido en 0 por la variable de entorno PYTHONNOUSERSITE.

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

int verbose

Modo detallado. Si es mayor que 0, imprima un mensaje cada vez que se importe un módulo, mostrando el lugar (nombre de archivo o módulo integrado) desde el que se carga.

Si es mayor o igual a 2, imprima un mensaje para cada archivo que se compruebe al buscar un módulo. También proporciona información sobre la limpieza del módulo al salir.

Incrementado por la opción de línea de comando -v.

Establecido en el valor de la variable de entorno PYTHONVERBOSE.

Predeterminado: 0.

PyWideStringList warnoptions

Opciones del módulo warnings para crear filtros de advertencias, de menor a mayor prioridad: sys.warnoptions.

El módulo warnings agrega sys.warnoptions en el orden inverso: el último elemento PyConfig.warnoptions se convierte en el primer elemento de warnings.filters que es verificado primero (máxima prioridad).

Las opciones de la línea de comando -W agregan su valor a warnoptions, se puede usar varias veces.

La variable de entorno PYTHONWARNINGS también se puede utilizar para agregar opciones de advertencia. Se pueden especificar varias opciones, separadas por comas (,).

Predeterminado: lista vacía.

int write_bytecode

Si es igual a 0, Python no intentará escribir archivos .pyc en la importación de módulos fuente.

Establecido en 0 por la opción de línea de comando -B y la variable de entorno PYTHONDONTWRITEBYTECODE.

sys.dont_write_bytecode se inicializa al valor invertido de write_bytecode.

Predeterminado: 1.

PyWideStringList xoptions

Valores de las opciones de la línea de comando -X: sys._xoptions.

Predeterminado: lista vacía.

Si parse_argv no es cero, los argumentos de argv se analizan de la misma forma que Python normal analiza argumentos de línea de comando, y los argumentos de Python se eliminan de argv.

Las opciones de xoptions se analizan para establecer otras opciones: consulte la opción de línea de comando -X.

Distinto en la versión 3.9: El campo show_alloc_count fue removido.

Inicialización con PyConfig

Función para inicializar Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Inicializa Python desde la configuración config.

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

Ejemplo más completo que modifica la configuración predeterminada, lee la configuración y luego anula algunos parámetros

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

    /* Append our custom search path to sys.path */
    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 todavía se utilizan con esta configuración. Configure el Python Path Configuration («campos de salida») para ignorar estos archivos de configuración y evitar que la función calcule la configuración de ruta predeterminada.

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:

Si no se establece al menos un «campo de salida», Python calcula la configuración de la ruta para completar los campos no definidos. Si module_search_paths_set es igual a 0, module_search_paths se reemplaza y module_search_paths_set se establece en 1.

Es posible ignorar por completo la función que calcula la configuración de ruta predeterminada al establecer explícitamente todos los campos de salida de configuración de ruta enumerados anteriormente. Una cadena de caracteres se considera como un conjunto, incluso si no está vacía. module_search_paths se considera como establecido si module_search_paths_set se establece en 1. En este caso, los campos de entrada de configuración de ruta también se ignoran.

Establezca pathconfig_warnings en 0 para suprimir las advertencias al calcular la configuración de la ruta (solo Unix, Windows no registra ninguna advertencia).

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

  • python._pth (sólo Windows)

  • pybuilddir.txt (sólo Unix)

La variable de entorno __PYVENV_LAUNCHER__ se usa para establecer PyConfig.base_executable

Py_RunMain()

int Py_RunMain(void)

Ejecuta el comando (PyConfig.run_command), el script (PyConfig.run_filename) o el módulo (PyConfig.run_module) especificado en la línea de comando o en la configuración.

Por defecto y cuando se usa la opción -i, ejecuta el REPL.

Finalmente, finaliza Python y retorna un estado de salida que se puede pasar a la función exit().

Consulte Configuración de Python para ver un ejemplo de Python personalizado que siempre se ejecuta en modo aislado usando Py_RunMain().

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:

API provisional privada:

  • PyConfig._init_main: si se establece en 0, Py_InitializeFromConfig() se detiene en la fase de inicialización «Core».

  • PyConfig._isolated_interpreter: si no es cero, no permite hilos, subprocesos y bifurcaciones.

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.

Puede ser posible calcular Configuración de ruta en Python, después de la fase Core y antes de la fase Main, que es una de las motivaciones PEP 432.

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