This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# Objetos archivo

Estas API son una emulación mínima de la API Python 2 en C para objetos de archivo incorporados, que solía depender del soporte de E/S (I/O) almacenadas en la memoria intermedia (`FILE*`) de la biblioteca estándar C. En Python 3, los archivos y las secuencias utilizan el nuevo módulo `io`, que define varias capas sobre las E/S sin búfer de bajo nivel del sistema operativo. Las funciones que se describen a continuación son envoltorios en C de conveniencia sobre estas nuevas API y están destinadas principalmente a la notificación de errores internos en el intérprete; se recomienda que el código de terceros acceda a las API `io`.

PyObject* `PyFile_FromFd`(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
  Return value: New reference.

  Crea un objeto archivo Python a partir del descriptor de archivo de un archivo ya abierto fd. Los argumentos name, encoding, errors y newline pueden ser `NULL` para usar los valores predeterminados; buffering puede ser -1 para usar el valor predeterminado. name se ignora y se mantiene por compatibilidad con versiones anteriores. Retorna `NULL` en caso de error. Para obtener una descripción más completa de los argumentos, consulte la documentación de la función `io.open()`.

  Advertencia

  Dado que las transmisiones (streams) de Python tienen su propia capa de almacenamiento en búfer, combinarlas con descriptores de archivos a nivel del sistema operativo puede producir varios problemas (como un pedido inesperado de datos).

  Distinto en la versión 3.2: Ignora el atributo name.

int `PyObject_AsFileDescriptor`(PyObject *p)

  Retorna el descriptor de archivo asociado con p como `int`. Si el objeto es un entero, se retorna su valor. Si no, se llama al método `fileno()` del objeto si existe; el método debe retornar un número entero, que se retorna como el valor del descriptor de archivo. Establece una excepción y retorna `-1` en caso de error.

PyObject* `PyFile_GetLine`(PyObject *p, int n)
  Return value: New reference.

  Equivalente a `p.readline([n])`, esta función lee una línea del objeto p. p puede ser un objeto archivo o cualquier objeto con un método `readline()`. Si n es `0`, se lee exactamente una línea, independientemente de la longitud de la línea. Si n es mayor que `0`, no se leerán más de n bytes del archivo; se puede retornar una línea parcial. En ambos casos, se retorna una cadena de caracteres vacía si se llega al final del archivo de inmediato. Si n es menor que `0`, sin embargo, se lee una línea independientemente de la longitud, pero `EOFError` se lanza si se llega al final del archivo de inmediato.

int `PyFile_SetOpenCodeHook`(Py_OpenCodeHookFunction handler)

  Sobrescribe el comportamiento normal de `io.open_code()` para pasar su parámetro a través del controlador proporcionado.

  El controlador es una función de tipo `PyObject *(*)(PyObject *path, void *userData)`, donde se garantiza que path sea `PyUnicodeObject`.

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

  Como este hook se usa intencionalmente durante la importación, evite importar nuevos módulos durante su ejecución a menos que se sepa que están congelados o disponibles en `sys.modules`.

  Una vez que se ha establecido un hook, no se puede quitar ni reemplazar, y luego llamadas a `PyFile_SetOpenCodeHook()` fallarán. En caso de error, la función retorna -1 y establece una excepción si el intérprete se ha inicializado.

  Es seguro llamar a esta función antes de `Py_Initialize()`.

  Genera un evento de auditoría `setopencodehook` sin argumentos.

  Nuevo en la versión 3.8.

int `PyFile_WriteObject`(PyObject *obj, PyObject *p, int flags)

  Escribe el objecto obj en el objeto archivo p. El único indicador admitido para flags es `Py_PRINT_RAW`; si se proporciona, se escribe el `str()` del objeto en lugar de `repr()`. Retorna `0` en caso de éxito o `-1` en caso de error; se establecerá la excepción apropiada.

int `PyFile_WriteString`(const char *s, PyObject *p)

  Escribe la cadena s en el objeto archivo p. Retorna `0` en caso de éxito o `-1` en caso de error; se establecerá la excepción apropiada.