Utilidades del sistema operativo

PyObject *PyOS_FSPath(PyObject *path)

Return value: New reference. Part of the Stable ABI since version 3.6.

Return the file system representation for path. If the object is a str or bytes object, then a new strong reference is returned. If the object implements the os.PathLike interface, then __fspath__() is returned as long as it is a str or bytes object. Otherwise TypeError is raised and NULL is returned.

Nuevo en la versión 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

Return true (nonzero) if the standard I/O file fp with name filename is deemed interactive. This is the case for files for which isatty(fileno(fp)) is true. If the PyConfig.interactive is non-zero, this function also returns true if the filename pointer is NULL or if the name is equal to one of the strings '<stdin>' or '???'.

This function must not be called before Python is initialized.

void PyOS_BeforeFork()

Part of the Stable ABI on platforms with fork() since version 3.7.

Función para preparar algún estado interno antes de una bifurcación de proceso (process fork). Esto debería llamarse antes de llamar a fork() o cualquier función similar que clone el proceso actual. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_BeforeFork().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Parent()

Part of the Stable ABI on platforms with fork() since version 3.7.

Función para actualizar algún estado interno después de una bifurcación de proceso. Se debe invocar desde el proceso principal después de llamar a fork() o cualquier función similar que clone el proceso actual, independientemente de si la clonación del proceso fue exitosa. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_AfterFork_Parent().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Child()

Part of the Stable ABI on platforms with fork() since version 3.7.

Función para actualizar el estado del intérprete interno después de una bifurcación de proceso (process fork). Debe llamarse desde el proceso secundario después de llamar a fork(), o cualquier función similar que clone el proceso actual, si existe alguna posibilidad de que el proceso vuelva a llamar al intérprete de Python. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_AfterFork_Child().

Nuevo en la versión 3.7.

Ver también

os.register_at_fork() permite registrar funciones personalizadas de Python a las que puede llamar PyOS_BeforeFork(), PyOS_AfterFork_Parent() y PyOS_AfterFork_Child().

void PyOS_AfterFork()

Part of the Stable ABI on platforms with fork().

Función para actualizar algún estado interno después de una bifurcación de proceso (process fork); Esto debería llamarse en el nuevo proceso si el intérprete de Python continuará siendo utilizado. Si se carga un nuevo ejecutable en el nuevo proceso, no es necesario llamar a esta función.

Obsoleto desde la versión 3.7: Esta función es reemplazada por PyOS_AfterFork_Child().

int PyOS_CheckStack()

Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.

Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when USE_STACKCHECK is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). USE_STACKCHECK will be defined automatically; you should never change the definition in your own code.

typedef void (*PyOS_sighandler_t)(int)

Part of the Stable ABI.

PyOS_sighandler_t PyOS_getsig(int i)

Part of the Stable ABI.

Return the current signal handler for signal i. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Part of the Stable ABI.

Set the signal handler for signal i to be h; return the old signal handler. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly!

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)

Part of the Stable ABI since version 3.7.

Advertencia

Esta función no debe llamarse directamente: utilice la API PyConfig con la función PyConfig_SetBytesString() que asegura que Python está preinicializado.

Esta función no debe llamarse antes de que Python esté preinicializado y para que la configuración local LC_CTYPE esté correctamente configurada: véase la función Py_PreInitialize().

Decodifica una cadena de bytes a partir del manejador de codificación y errores del sistema de archivos. Si el controlador de error es el controlador de error surrogateescape, los bytes no codificables se decodifican como caracteres en el rango U+DC80..U+DCFF; y si una secuencia de bytes se puede decodificar como un carácter sustituto, escape los bytes usando el controlador de error surrogateescape en lugar de decodificarlos.

Retorna un puntero a una cadena de caracteres anchos recientemente asignada, use PyMem_RawFree() para liberar la memoria. Si el tamaño no es NULL, escribe el número de caracteres anchos excluyendo el carácter nulo en *size

Retorna NULL en caso de error de decodificación o error de asignación de memoria. Si size no es NULL, *size se establece en (size_t) -1 en caso de error de memoria o en (size_t) -2 en caso de error de decodificación.

El filesystem encoding and error handler son seleccionados por PyConfig_Read(): ver filesystem_encoding y filesystem_errors que pertenecen a PyConfig.

Los errores de decodificación nunca deberían ocurrir, a menos que haya un error en la biblioteca C.

Utilice la función Py_EncodeLocale() para codificar la cadena de caracteres en una cadena de bytes.

Ver también

Las funciones PyUnicode_DecodeFSDefaultAndSize() y PyUnicode_DecodeLocaleAndSize().

Nuevo en la versión 3.5.

Distinto en la versión 3.7: La función ahora utiliza la codificación UTF-8 en el Modo Python UTF-8.

Distinto en la versión 3.8: The function now uses the UTF-8 encoding on Windows if PyPreConfig.legacy_windows_fs_encoding is zero;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Part of the Stable ABI since version 3.7.

Codifica una cadena de caracteres amplios según el término filesystem encoding and error handler. Si el gestor de errores es surrogateescape error handler, los caracteres sustituidos en el rango U+DC80..U+DCFF se convierten en bytes 0x80..0xFF.

Retorna un puntero a una cadena de bytes recién asignada, usa PyMem_Free() para liberar la memoria. Retorna NULL si se genera un error de codificación o error de asignación de memoria.

Si error_pos no es NULL, *error_pos se establece en (size_t)-1 en caso de éxito, o se establece en el índice del carácter no válido en el error de codificación.

El filesystem encoding and error handler son seleccionados por PyConfig_Read(): ver filesystem_encoding y filesystem_errors que pertenecen a PyConfig.

Use la función Py_DecodeLocale() para decodificar la cadena de bytes en una cadena de caracteres anchos.

Advertencia

Esta función no debe llamarse antes de que Python esté preinicializado y para que la configuración local LC_CTYPE esté correctamente configurada: véase la función Py_PreInitialize().

Ver también

Las funciones PyUnicode_EncodeFSDefault() y PyUnicode_EncodeLocale().

Nuevo en la versión 3.5.

Distinto en la versión 3.7: La función ahora utiliza la codificación UTF-8 en el Modo Python UTF-8.

Distinto en la versión 3.8: The function now uses the UTF-8 encoding on Windows if PyPreConfig.legacy_windows_fs_encoding is zero.

Funciones del Sistema

Estas son funciones de utilidad que hacen que la funcionalidad del módulo sys sea accesible para el código C. Todos funcionan con el diccionario del módulo sys del subproceso actual del intérprete, que está contenido en la estructura interna del estado del subproceso.

PyObject *PySys_GetObject(const char *name)

Return value: Borrowed reference. Part of the Stable ABI.

Retorna el objeto name del módulo sys o NULL si no existe, sin establecer una excepción.

int PySys_SetObject(const char *name, PyObject *v)

Part of the Stable ABI.

Establece name en el módulo sys en v a menos que v sea NULL, en cuyo caso name se elimina del módulo sys. Retorna 0 en caso de éxito, -1 en caso de error.

void PySys_ResetWarnOptions()

Part of the Stable ABI.

Restablece sys.warnoptions a una lista vacía. Esta función puede llamarse antes de Py_Initialize().

void PySys_AddWarnOption(const wchar_t *s)

Part of the Stable ABI.

Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su lugar se debe usar: PyConfig.warnoptions, ver Configuración de inicialización de Python.

Agrega s a sys.warnoptions. Esta función debe llamarse antes de Py_Initialize() para afectar la lista de filtros de advertencias.

Obsoleto desde la versión 3.11.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

Part of the Stable ABI.

Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su lugar se debe usar: PyConfig.warnoptions, ver Configuración de inicialización de Python.

Agrega unicode a sys.warnoptions.

Nota: esta función no se puede utilizar actualmente desde fuera de la implementación de CPython, ya que debe llamarse antes de la importación implícita de warnings en Py_Initialize() para que sea efectiva, pero no se puede llamar hasta que se haya inicializado suficiente tiempo de ejecución para permitir la creación de objetos Unicode.

Obsoleto desde la versión 3.11.

void PySys_SetPath(const wchar_t *path)

Part of the Stable ABI.

Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su lugar se debe usar: PyConfig.module_search_paths y PyConfig.module_search_paths_set, ver Python Initialization Configuration.

Establece sys.path en un objeto lista de rutas que se encuentra en path, que debería ser una lista de rutas separadas con el delimitador de ruta de búsqueda de la plataforma (: en Unix, ; en Windows )

Obsoleto desde la versión 3.11.

void PySys_WriteStdout(const char *format, ...)

Part of the Stable ABI.

Escribe la cadena de caracteres de salida descrita por format en sys.stdout. No se lanzan excepciones, incluso si se produce el truncamiento (ver más abajo).

format debe limitar el tamaño total de la cadena de caracteres de salida formateada a 1000 bytes o menos; después de 1000 bytes, la cadena de caracteres de salida se trunca. En particular, esto significa que no deben existir formatos «%s» sin restricciones; estos deben limitarse usando «%.<N>s» donde <N> es un número decimal calculado de modo que <N> más el tamaño máximo de otro texto formateado no exceda los 1000 bytes. También tenga cuidado con «%f», que puede imprimir cientos de dígitos para números muy grandes.

Si ocurre un problema, o sys.stdout no está configurado, el mensaje formateado se escribe en el real (nivel C) stdout.

void PySys_WriteStderr(const char *format, ...)

Part of the Stable ABI.

Como PySys_WriteStdout(), pero escribe a sys.stderr o stderr en su lugar.

void PySys_FormatStdout(const char *format, ...)

Part of the Stable ABI.

Función similar a PySys_WriteStdout() pero formatea el mensaje usando PyUnicode_FromFormatV() y no trunca el mensaje a una longitud arbitraria.

Nuevo en la versión 3.2.

void PySys_FormatStderr(const char *format, ...)

Part of the Stable ABI.

Como PySys_FormatStdout(), pero escribe a sys.stderr o stderr en su lugar.

Nuevo en la versión 3.2.

void PySys_AddXOption(const wchar_t *s)

Part of the Stable ABI since version 3.7.

Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su lugar se debe usar: PyConfig.xoptions, ver Configuración de inicialización de Python.

Analiza (parse) s como un conjunto de opciones -X y los agrega a la asignación de opciones actual tal como lo retorna PySys_GetXOptions(). Esta función puede llamarse antes de Py_Initialize().

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.11.

PyObject *PySys_GetXOptions()

Return value: Borrowed reference. Part of the Stable ABI since version 3.7.

Retorna el diccionario actual de opciones -X, de manera similar a sys._xoptions. En caso de error, se retorna NULL y se establece una excepción.

Nuevo en la versión 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Lanza un evento de auditoría con cualquier gancho activo. Retorna cero para el éxito y no cero con una excepción establecida en caso de error.

Si se han agregado ganchos, format y otros argumentos se utilizarán para construir una tupla para pasar. Además de N, están disponibles los mismos caracteres de formato que los utilizados en Py_BuildValue(). Si el valor generado no es una tupla, se agregará a una tupla de un solo elemento. (La opción de formato N consume una referencia, pero dado que no hay forma de saber si se consumirán argumentos para esta función, su uso puede causar fugas de referencia).

Tenga en cuenta que los caracteres de formato # deben tratarse como Py_ssize_t, independientemente de si se definió PY_SSIZE_T_CLEAN.

sys.audit() realiza la misma función del código Python.

Nuevo en la versión 3.8.

Distinto en la versión 3.8.2: Requiere Py_ssize_t para los caracteres de formato #. Anteriormente, se lanzaba una advertencia de deprecación inevitable.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Agrega el hook invocable a la lista de hooks de auditoría activos. Retorna cero para el éxito y no cero en caso de error. Si el tiempo de ejecución se ha inicializado, también configura un error en caso de fallo. Los hooks agregados a través de esta API se llaman para todos los intérpretes creados por el tiempo de ejecución.

El puntero userData se pasa a la función gancho. Dado que las funciones de enlace pueden llamarse desde diferentes tiempos de ejecución, este puntero no debe referirse directamente al estado de Python.

Es seguro llamar a esta función antes de Py_Initialize(). Cuando se llama después de la inicialización del tiempo de ejecución, se notifican los enlaces de auditoría existentes y pueden anular silenciosamente la operación al generar un error subclasificado de Excepción (otros errores no se silenciarán).

The hook function is always called with the GIL held by the Python interpreter that raised the event.

Ver PEP 578 para una descripción detallada de la auditoría. Las funciones en el tiempo de ejecución y la biblioteca estándar que generan eventos se enumeran en table de eventos de auditoria. Los detalles se encuentran en la documentación de cada función.

Lanza un evento de auditoria sys.addaudithook sin argumentos.

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

The type of the hook function. event is the C string event argument passed to PySys_Audit(). args is guaranteed to be a PyTupleObject. userData is the argument passed to PySys_AddAuditHook().

Nuevo en la versión 3.8.

Control de procesos

void Py_FatalError(const char *message)

Part of the Stable ABI.

Print a fatal error message and kill the process. No cleanup is performed. This function should only be invoked when a condition is detected that would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. On Unix, the standard C library function abort() is called which will attempt to produce a core file.

La función Py_FatalError() se reemplaza con una macro que registra automáticamente el nombre de la función actual, a menos que se defina la macro Py_LIMITED_API.

Distinto en la versión 3.9: Registra el nombre de la función automáticamente.

void Py_Exit(int status)

Part of the Stable ABI.

Sale del proceso actual. Esto llama Py_FinalizeEx() y luego llama a la función estándar de la biblioteca C exit(status). Si Py_FinalizeEx() indica un error, el estado de salida se establece en 120.

Distinto en la versión 3.6: Los errores de finalización ya no se ignoran.

int Py_AtExit(void (*func)())

Part of the Stable ABI.

Registra una función de limpieza a la que llamará Py_FinalizeEx(). Se llamará a la función de limpieza sin argumentos y no debería retornar ningún valor. Como máximo se pueden registrar 32 funciones de limpieza. Cuando el registro es exitoso, Py_AtExit() retorna 0; en caso de error, retorna -1. La última función de limpieza registrada se llama primero. Cada función de limpieza se llamará como máximo una vez. Dado que la finalización interna de Python se habrá completado antes de la función de limpieza, func no debería llamar a las API de Python.