# `io` — Herramientas principales para trabajar con streams

Código fuente: Lib/io.py

## Resumen

El módulo `io` provee las facilidades principales de Python para manejar diferentes tipos de E/S. Hay tres diferentes tipos de E/S: texto E/S, binario E/S e E/S sin formato. Estas son categorías generales y varios respaldos de almacenamiento se pueden usar para cada una de ellas. Un objeto concreto perteneciendo a cualquiera de estas categorías se llama un file object. Otros términos comunes son stream y file-like object.

Independiente de su categoría, cada objeto stream también tendrá varias capacidades: puede ser solamente para lectura, solo escritura, or lectura y escritura. También permite arbitrariamente acceso aleatorio (buscando adelante o hacia atrás en cualquier lugar) o solamente acceso secuencial (por ejemplo en el caso de un socket o pipe).

Todas los streams son cuidadosas del tipo de datos que se les provee. Por ejemplo dando un objeto de clase `str` al método `write()` de un stream binaria lanzará un `TypeError`. También dándole un objeto de tipo `bytes` al método `write()` de un stream de tipo texto.

Distinto en la versión 3.3: Operaciones que lanzarán un `IOError` ahora lanzan `OSError`, ya que `IOError` es un alias de `OSError`.

### E/S Texto

E/S de tipo texto espera y produce objetos de clase `str`. Esto significa que cuando el respaldo de almacenamiento está compuesto de forma nativa de bytes (como en el caso de un archivo), la codificación y descodificación de datos está hecho de forma transparente tanto como traducción opcional de caracteres de nueva línea específicos de la plataforma.

La manera más fácil de crear un stream de tipo texto es con el método `open()`, con la opción de especificar una codificación:

    f = open("myfile.txt", "r", encoding="utf-8")

Streams de texto en memoria también están disponibles como objetos de tipo `StringIO`:

    f = io.StringIO("some initial text data")

El API (interfaz de programación de aplicaciones) de streams tipo texto está descrito con detalle en la documentación de `TextIOBase`.

### E/S Binaria

E/S binaria (también conocido como buffered E/S) espera objetos tipo bytes y produce objetos tipo `bytes`. No se hace codificación, descodificación, o traducciones de nueva línea. Esta categoría de streams puede ser usada para todos tipos de datos sin texto, y también cuando se desea control manual sobre el manejo de dato textual.

La manera más fácil para crear un stream binario es con el método `open()` con `'b'` en el modo de la cadena de caracteres:

    f = open("myfile.jpg", "rb")

Los streams binarios en memoria también están disponibles como objetos tipo `BytesIO`:

    f = io.BytesIO(b"some initial binary data: \x00\x01")

El API de stream binario está descrito con detalle en la documentación de `BufferedIOBase`.

Otros módulos bibliotecarios pueden proveer maneras alternativas para crear streams de tipo texto o binario. Ver `socket.socket.makefile()` como ejemplo.

### E/S sin formato

E/S sin formato (también conocido como unbuffered E/S) es generalmente usado como un fundamento de nivel bajo para streams binario y tipo texto; es raramente útil para manipular directamente streams sin formatos del código de usuario. Sin embargo puedes crear un stream sin formato abriendo un archivo en modo binario con el búfer apagado:

    f = open("myfile.jpg", "rb", buffering=0)

El API de streams sin formato está descrito con detalle en la documentación de `RawIOBase`.

## Interfaz de módulo de alto nivel

`io.``DEFAULT_BUFFER_SIZE`

  Un int que contiene el búfer de tamaño predeterminado usado por las clases de tipo E/S. `open()` utiliza el blksize del archivo (obtenido por `os.stat()`) si es posible.

`io.``open`(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

  Esto es un alias para la función incorporada `open()`.

  Lanza un auditing event `open` con los argumentos``path``, `mode`, `flags`.

`io.``open_code`(path)

  Abre el archivo dado con el modo `'rb'`. Esta función debe ser usado cuando la intención es tratar el contenido como código ejecutable.

  `path` debe ser un `str` y una ruta absoluta.

  Se puede anular el comportamiento de esta función haciendo un pedido anterior a `PyFile_SetOpenCodeHook()`. Sin embargo, asumiendo que `path` es un `str` y una ruta absoluta, `open_code(path)` debería manejarse al igual que `open(path, ‘rb')`. El propósito de anular el comportamiento existe para validación adicional o para el preprocesamiento del archivo.

  Nuevo en la versión 3.8.

exception `io.``BlockingIOError`

  Esto es un alias de compatibilidad para la incorporada excepción `BlockingIOError`.

exception `io.``UnsupportedOperation`

  Una excepción heredando `OSError` y `ValueError` que es generado cuando se llama a una operación no admitida en un stream.

Ver también

`sys`

  contiene los streams estándar de IO `sys.stdin`, `sys.stdout`, y `sys.stderr`.

## Jerarquía de clases

La implementación de streams E/S está organizada como una jerarquía de clases. Primero abstract base classes (ABC), que son usados para especificar las varias categorías de streams, luego las clases concretas proveen un stream estándar de implementaciones.

> Nota

> Las clases abstractas base también proveen implementaciones predeterminadas de algunos métodos para ayudar implementar clases de streams concretos. Por ejemplo, `BufferedIOBase` proporciona implementaciones no optimizadas de `readinto()` y `readline()`.

En la parte superior de la jerarquía E/S está la clase abstracta base `IOBase`. Define la interfaz básica del stream. Tenga en cuenta que no hay separación entre streams de lectura y escritura; implementaciones están permitidos lanzar `UnsupportedOperation` si no apoyan la operación.

La clase `RawIOBase` extiende `IOBase`. Maneja la lectura y escritura de bytes a un stream. `FileIO` subclasifica `RawIOBase` para proveer una interfaz a los archivos en el sistema de archivos de la máquina.

The `BufferedIOBase` ABC extends `IOBase`. It deals with buffering on a raw binary stream (`RawIOBase`). Its subclasses, `BufferedWriter`, `BufferedReader`, and `BufferedRWPair` buffer raw binary streams that are readable, writable, and both readable and writable, respectively. `BufferedRandom` provides a buffered interface to seekable streams. Another `BufferedIOBase` subclass, `BytesIO`, is a stream of in-memory bytes.

The `TextIOBase` ABC extends `IOBase`. It deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. `TextIOWrapper`, which extends `TextIOBase`, is a buffered text interface to a buffered raw stream (`BufferedIOBase`). Finally, `StringIO` is an in-memory stream for text.

Los nombres de los argumentos no son parte de la especificación, y solo los argumentos de `open()` están destinados a ser utilizados como argumentos de palabras clave.

La siguiente tabla resume los ABC proporcionado por el módulo `io` module:

ABC | Hereda | Métodos de trozos (Stub) | Métodos Mixin y propiedades
--- | --- | --- | ---
`IOBase` |  | `fileno`, `seek`, and `truncate` | `close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable`, and `writelines`
`RawIOBase` | `IOBase` | `readinto` and `write` | Métodos `IOBase` heredados, `read`, and `readall`
`BufferedIOBase` | `IOBase` | `detach`, `read`, `read1`, and `write` | Métodos `IOBase` heredados, `readinto`, and `readinto1`
`TextIOBase` | `IOBase` | `detach`, `read`, `readline`, and `write` | Métodos `IOBase` heredados, `encoding`, `errors`, and `newlines`

### Clases base E/S

class `io.``IOBase`

  The abstract base class for all I/O classes.

  Esta clase provee implementaciones abstractas vacías para muchos métodos que clases que derivadas pueden anular selectivamente; la implementación predeterminada representa un archivo que no se puede leer, grabar o ser buscado.

  Aunque `IOBase` no declara el método `read()` o `write()` porque sus firmas varían, implementaciones y clientes deberían considerar usar métodos como parte de la interfaz. Las implementaciones también podrían lanzar un `ValueError` (o `UnsupportedOperation`) cuando operaciones que estos no apoyan son usados.

  El tipo básico usado para leer datos binarios o grabar un archivo es `bytes`. Otros bytes-like objects son aceptados como argumentos para métodos también. Clases de tipo E/S funcionan usando datos de tipo `str`.

  Tenga en cuenta que llamando cualquier método (incluso indagaciones) en un stream cerrada es indefinido. En este caso implementaciones podrían lanzar un error `ValueError`.

  `IOBase` (y sus subclasificaciones) apoyan el protocolo iterador, significando que un objeto de clase `IOBase` puede ser iterado sobre el rendimiento de las líneas en un stream de datos. Líneas son definidas un poco diferente dependiendo si el stream es de tipo binario (produciendo bytes), o un stream de texto (produciendo cadenas de caracteres). Ver `readline()` abajo.

  `IOBase` es también un gestor de contexto y por ende apoya la declaración `with`. En este ejemplo, file es cerrado después de que la declaración `with` termina–incluso si alguna excepción ocurre:

      with open('spam.txt', 'w') as file:
          file.write('Spam and eggs!')

  `IOBase` provee los siguientes atributos y métodos:

  `close`()

    Cierra el stream. Este método no tiene efecto si el archivo ya está cerrado. Cuándo está cerrado, cualquier operación que se le haga al archivo (ej. leer or grabar) lanzará el error `ValueError`.

    Como conveniencia, se permite llamar este método más que una vez. Sin embargo, solamente el primer llamado tenderá efecto.

  `closed`

    `True` si está cerrada el stream.

  `fileno`()

    Retorna el descriptor de archivo subyacente (un número de tipo entero) de el stream si existe. Un `OSError` se lanza si el objeto IO no tiene un archivo descriptor.

  `flush`()

    Vacía los buffers de grabación del stream si corresponde. Esto no hace nada para streams que son solamente de lectura o streams sin bloqueo.

  `isatty`()

    Retorna `True` si el stream es interactiva (ej., si está conectado a un terminal o dispositivo tty).

  `readable`()

    Retorna `True` si el stream puede ser leída. Si es `False`, el método `read()` lanzará un `OSError`.

  `readline`(size=-1, /)

    Lee y retorna una línea del stream. Si size (tamaño) es especificado, se capturará un máximo de ése mismo tamaño especificado en bytes.

    El terminador de la línea siempre es `b'\n'` para archivos de tipo binario; para archivos de tipo texto el argumento newline para la función `open()` pueden ser usados para seleccionar las líneas terminadoras reconocidas.

  `readlines`(hint=-1, /)

    Lee y retorna una lista de líneas del stream. hint puede ser especificado para controlar el número de líneas que se lee: no se leerán más líneas si el tamaño total (en bytes / caracteres) de todas las líneas excede hint.

    hint values of `0` or less, as well as `None`, are treated as no hint.

    Tenga en cuenta que ya es posible iterar sobre objetos de archivo usando `for line in file: …` sin llamar `file.readlines()`.

  `seek`(offset, whence=SEEK_SET, /)

    Cambiar la posición del stream al dado byte offset. offset se interpreta en relación con la posición indicada por whence. El valor dado para whence es `SEEK_SET`. Valores para whence son:

    - `SEEK_SET` o `0` – inicio del stream (el dado); offset debería ser cero o positivo

    - `SEEK_CUR` o `1` – posición actual del stream; offset puede ser negativo

    - `SEEK_END` o `2` – fin del stream; offset is usualmente negativo

    Retorna la nueva posición absoluta.

    Nuevo en la versión 3.1: Los constantes``SEEK_*``.

    Nuevo en la versión 3.3: Algunos sistemas operativos pueden apoyar valores adicionales, como `os.SEEK_HOLE` o `os.SEEK_DATA`. Los valores válidos para un archivo podrían depender de que esté abierto en modo texto o binario.

  `seekable`()

    Retorna `True` si el stream apoya acceso aleatorio. Si retorna `False`, `seek()`, `tell()` y `truncate()` lanzarán `OSError`.

  `tell`()

    Retorna la posición actual del stream.

  `truncate`(size=None, /)

    Cambia el tamaño del stream al size dado en bytes (o la posición actual si no se especifica size). La posición actual del stream no se cambia. Este cambio de tamaño puede incrementar o reducir el tamaño actual del archivo. En caso de extensión, los contenidos del área del nuevo archivo depende de la plataforma (en la mayoría de los sistemas bytes adicionales son llenos de cero). Se retorna el nuevo tamaño del archivo.

    Distinto en la versión 3.5: Windows llenará los archivos con cero cuando extienda.

  `writable`()

    Retorna `True` si el stream apoya grabación. Si retorna `False`, `write()` y `truncate()` lanzarán `OSError`.

  `writelines`(lines, /)

    Escribir una lista de líneas al stream. No se agrega separadores de líneas, así que es usual que las líneas tengan separador al final.

  `__del__`()

    Prepara para la destrucción de un objeto. `IOBase` proporciona una implementación dada de este método que ejecuta las instancias del método `close()`.

class `io.``RawIOBase`

  Base class for raw binary streams. It inherits `IOBase`.

  Raw binary streams typically provide low-level access to an underlying OS device or API, and do not try to encapsulate it in high-level primitives (this functionality is done at a higher-level in buffered binary streams and text streams, described later in this page).

  `RawIOBase` provides these methods in addition to those from `IOBase`:

  `read`(size=-1, /)

    Lee hasta el size de los bytes del objeto y los retorna. Como conveniencia si no se especifica size o es -1, se retornan todos los bytes hasta que se retorne el fin del archivo. Sino, se hace solo un llamado al sistema. Se pueden retornar menos de size bytes si la llamada del sistema operativo retorna menos de size bytes.

    Si se retorna 0 bytes y el size no era 0, esto indica que es el fin del archivo. Si el objeto está en modo sin bloqueo y no hay bytes disponibles, se retorna `None`.

    La implementación dada difiera al método `readall()` y `readinto()`.

  `readall`()

    Lee y retorna todos los bytes del stream hasta llegar al fin del archivo, usando, si es necesario, varias llamadas al stream.

  `readinto`(b, /)

    Lee bytes en objeto pre-asignado y grabable bytes-like object b, y retorna el número de bytes leído. Por ejemplo, b puede ser una clase de tipo `bytearray`. Si el objeto está en modo sin bloquear y no hay bytes disponibles, se retorna `None`.

  `write`(b, /)

    Escribe bytes-like object dado, b, al stream subyacente y retorna la cantidad de bytes grabadas. Esto puede ser menos que la longitud de b en bytes, dependiendo de la especificaciones del stream subyacente, especialmente si no está en modo no-bloqueo. `None` se retorna si el stream sin formato está configurado para no bloquear y ningún byte puede ser rápidamente grabada. El llamador puede deshacer o mutar b después que retorne este método, así que la implementación solo debería acceder b durante la ejecución al método.

class `io.``BufferedIOBase`

  Base class for binary streams that support some kind of buffering. It inherits `IOBase`.

  La diferencia principal de `RawIOBase` es que los métodos `read()`, `readinto()` y `write()` intentarán (respectivamente) leer la cantidad de información solicitada o consumir toda la salida dada, a expensas de hacer más de una llamada al sistema.

  Adicionalmente, esos métodos pueden lanzar un `BlockingIOError` si el stream sin formato subyacente está en modo no bloqueo y no puede obtener or dar más datos; a diferencia de sus contrapartes `RawIOBase`, estos nunca retornarán `None`.

  Además, el método `read()` no tiene una implementación dada que difiere al método `readinto()`.

  Una implementación típica de `BufferedIOBase` no debería heredar una implementación de `RawIOBase`, es más, debería envolver como uno, así como hacen las clases `BufferedWriter` y `BufferedReader`.

  `BufferedIOBase` provides or overrides these data attributes and methods in addition to those from `IOBase`:

  `raw`

    El stream sin formato subyacente ( una instancia `RawIOBase`) que `BufferedIOBase` maneja. Esto no es parte de la API `BufferedIOBase` y posiblemente no exista en algunas implementaciones.

  `detach`()

    Separa el stream subyacente del búfer y lo retorna.

    Luego que el stream sin formato ha sido separado, el búfer está en un estado inutilizable.

    Algunos búfer, como `BytesIO`, no tienen el concepto de un stream sin formato singular para retornar de este método. Lanza un `UnsupportedOperation`.

    Nuevo en la versión 3.1.

  `read`(size=-1, /)

    Lee y retorna hasta size en bytes. Si el argumento está omitido, `None`, o es negativo, los datos son leídos y retornados hasta que se alcance el fin del archivo. Un objeto `bytes` vacío se retorna si el stream está al final del archivo.

    Si el argumento es positivo, y el stream subyacente no es interactiva, varias lecturas sin formato pueden ser otorgadas para satisfacer la cantidad de byte (al menos que primero se llegue al fin del archivo). Pero para los streams sin formato interactivas, a lo sumo una lectura sin formato será emitida y un resultado corto no implica que se haya llegado al fin del archivo.

    Un `BlockingIOError` se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

  `read1`(size=-1, /)

    Lee y retorna hasta size en bytes con al menos una llamada al método `read()` (o `readinto()`) del stream subyacente. Esto puede ser útil si estás implementando tu propio búfer por encima de un objeto `BufferedIOBase`.

    Si size es `-1` (el valor dado) se retorna un monto arbitrario de bytes (más que cero al menos que se haya llegado al fin del archivo).

  `readinto`(b, /)

    Lee bytes a un objeto predeterminado y grabable bytes-like object b y retorna el número de bytes leídos. Por ejemplo, b puede ser un `bytearray`.

    Como `read()`, varias lecturas pueden ser otorgadas al stream sin formato subyacente al menos que esto último sea interactivo.

    Un `BlockingIOError` se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

  `readinto1`(b, /)

    Leer bytes a un objeto predeterminado y grabable bytes-like object b usando por lo menos una llamada al método `read()` (o `readinto()`) del stream subyacente. Retorna la cantidad de bytes leídas.

    Un `BlockingIOError` se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

    Nuevo en la versión 3.5.

  `write`(b, /)

    Escribe el bytes-like object dado, b, y retorna el número de bytes grabados (siempre el equivalente en longitud de b en bytes, ya que si falla la grabación se lanza un `OSError`). Dependiendo en la implementación actual estos bytes pueden ser grabados rápidamente al stream subyacente o mantenido en un búfer por razones de rendimiento y latencia.

    Cuando estás en modo no bloqueo, se lanza un `BlockingIOError` si los datos tenían que ser grabadas al stream sin formato pero no pudo aceptar todos los datos sin bloquear.

    El llamador puede otorgar o mutar b después que este método retorne algo, entonces la implementación debería acceder solamente a b durante la llamada al método.

### Archivo sin formato E/S

class `io.``FileIO`(name, mode='r', closefd=True, opener=None)

  A raw binary stream representing an OS-level file containing bytes data. It inherits `RawIOBase`.

  El name puede ser una de dos cosas:

  - una cadena de caracteres u objeto de tipo `bytes` representando la ruta del archivo en la que fue abierto. En este caso closefd es `True` (el valor dado) de otra manera un error será dada.

  - un integer representando el número de descriptores de archivos de nivel OS que resultan dando acceso a través del objeto `FileIO`. Cuando el objeto FileIO está cerrado este fd cerrará también a no ser que closefd esté configurado a `False`.

  El mode puede ser `'r'`, `'w'`, `'x'` o``”a”`` para lectura (el valor dado), grabación, creación exclusiva o anexando. Si no existe el archivo se creará cuando se abra para grabar o anexar; se truncará cuando se abra para grabar. Se lanzará un error `FileExistsError` si ya existe cuando se abra para crear. Abriendo un archivo para crear implica grabar entonces este modo se comporta similarmente a `'w'`. Agrega un `'+'` al modo para permitir lectura y grabación simultáneas.

  Los métodos `read()` (cuando se llama con un argumento positivo), `readinto()` y `write()` en esta clase harán solo una llamada al sistema.

  Un abridor personalizado puede ser usado pasando un llamador como opener. El descriptor de archivo subyacente es obtenido llamando opener con (name, flags). opener debe retornar un descriptor de archivo abierto (pasando `os.open` como opener resulta con funcionamiento similar a pasando `None`).

  El archivo recién creado es non-inheritable.

  Ver la función incorporada `open()` para ejemplos usando el parámetro opener.

  Distinto en la versión 3.3: El parámetro opener fue agregado. El modo `'x'` fue agregado.

  Distinto en la versión 3.4: El archivo ahora no es heredable.

  `FileIO` provides these data attributes in addition to those from `RawIOBase` and `IOBase`:

  `mode`

    El modo dado en el constructor.

  `name`

    El nombre del archivo. Este es el descriptor del archivo cuando no se proporciona ningún nombre en el constructor.

### Streams almacenados (búfer)

Streams E/S almacenadas (búfer) proveen una interfaz de más alto nivel a un dispositivo E/S que a un E/S sin formato.

class `io.``BytesIO`(initial_bytes=b'')

  A binary stream using an in-memory bytes buffer. It inherits `BufferedIOBase`. The buffer is discarded when the `close()` method is called.

  El argumento opcional initial_bytes es un bytes-like object que contiene datos iniciales.

  `BytesIO` provee o anula estos métodos además de los de `BufferedIOBase` y `IOBase`:

  `getbuffer`()

    Retorna una vista legible y grabable acerca de los contenidos del búfer sin copiarlos. Además mutando la vista actualizará de forma transparente los contenidos del búfer:

        >>> b = io.BytesIO(b"abcdef")
        >>> view = b.getbuffer()
        >>> view[2:4] = b"56"
        >>> b.getvalue()
        b'ab56ef'

    Nota

    Mientras exista la vista el objeto `BytesIO` no se le puede cambiar el tamaño o cerrado.

    Nuevo en la versión 3.2.

  `getvalue`()

    Retorna `bytes` que contiene los contenidos enteros del búfer.

  `read1`(size=-1, /)

    En la clase `BytesIO` esto es lo mismo que `read()`.

    Distinto en la versión 3.7: Ahora es opcional el argumento size.

  `readinto1`(b, /)

    En la clase `BytesIO` esto es lo mismo que `readinto()`.

    Nuevo en la versión 3.5.

class `io.``BufferedReader`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a readable, non seekable `RawIOBase` raw binary stream. It inherits `BufferedIOBase`.

  When reading data from this object, a larger amount of data may be requested from the underlying raw stream, and kept in an internal buffer. The buffered data can then be returned directly on subsequent reads.

  El constructor crea un `BufferedReader` para el stream legible sin formato raw y buffer_size. Si se omite buffer_size se usa `DEFAULT_BUFFER_SIZE`.

  `BufferedReader` provee o anula los métodos en adición a los de `BufferedIOBase` y `IOBase`:

  `peek`(size=0, /)

    Retorna bytes del stream sin avanzar la posición. Al menos una lectura se hace al stream sin formato para satisfacer el llamado. El número de bytes retornados puede ser menor o mayor al solicitado.

  `read`(size=-1, /)

    Lee y retorna size bytes o si no se da size, o es negativo, hasta el fin del archivo o si la llamada leída podría bloquear in modo no bloquear.

  `read1`(size=-1, /)

    Lee y retorna hasta el tamaño size en bytes con solo un llamado al stream. Si al menos un byte pasa por el proceso de búfer, solo se retornan buffered bytes. De lo contrario se realiza un llamado de lectura de un stream sin formato.

    Distinto en la versión 3.7: Ahora es opcional el argumento size.

class `io.``BufferedWriter`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a writeable, non seekable `RawIOBase` raw binary stream. It inherits `BufferedIOBase`.

  When writing to this object, data is normally placed into an internal buffer. The buffer will be written out to the underlying `RawIOBase` object under various conditions, including:

  - cuando el búfer se vuelve demasiado pequeño para todos los datos pendientes;

  - cuando se llama `flush()`;

  - cuando se pide un método `seek()` (para objetos `BufferedRandom`);

  - cuando el objeto `BufferedWriter` is cerrado o anulado.

  El constructor crea un `BufferedWriter` para el stream grabable raw. Si no es dado el buffer_size, recurre el valor `DEFAULT_BUFFER_SIZE`.

  `BufferedWriter` provee o anula estos métodos además de los de `BufferedIOBase` y `IOBase`:

  `flush`()

    Forzar bytes retenidos en el búfer al stream sin formato. Un `BlockingIOError` debería ser lanzado si el stream sin formato bloquea.

  `write`(b, /)

    Escribe el bytes-like object, b, y retorna el número de bytes grabados. Cuando estás en modo no-bloqueo, se lanza un `BlockingIOError` si el búfer tiene que ser escrito pero el stream sin formato bloquea.

class `io.``BufferedRandom`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a seekable `RawIOBase` raw binary stream. It inherits `BufferedReader` and `BufferedWriter`.

  El constructor crea un lector y una grabación para un stream sin formato buscable, dado en el primer argumento. Si se omite el buffer_size este recae sobre el valor predeterminado `DEFAULT_BUFFER_SIZE`.

  `BufferedRandom` es capaz de todo lo que puede hacer `BufferedReader` o `BufferedWriter`. Adicionalmente, se garantiza implementar `seek()` y `tell()`.

class `io.``BufferedRWPair`(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

  A buffered binary stream providing higher-level access to two non seekable `RawIOBase` raw binary streams—one readable, the other writeable. It inherits `BufferedIOBase`.

  reader y writer son objetos `RawIOBase` que son respectivamente legibles y escribibles. Si se omite buffer_size este se recae sobre el valor predeterminado `DEFAULT_BUFFER_SIZE`.

  `BufferedRWPair` implementa todos los métodos de `BufferedIOBase` excepto por `detach()`, que lanza un `UnsupportedOperation`.

  Advertencia

  `BufferedRWPair` no intenta sincronizar accesos al stream sin formato subyacente. No debes pasar el mismo objeto como legible y escribible; usa `BufferedRandom` en su lugar.

### E/S Texto

class `io.``TextIOBase`

  Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits `IOBase`.

  `TextIOBase` provee o anula estos atributos y métodos de datos además de los de `IOBase`:

  `encoding`

    El nombre de la codificación utilizada para decodificar los bytes del stream a cadenas de caracteres y para codificar cadenas de caracteres en bytes.

  `errors`

    La configuración de error del decodificador o codificador.

  `newlines`

    Una cadena de caracteres, una tupla de cadena de caracteres, o `None`, indicando las nuevas líneas traducidas hasta ese momento. Dependiendo de la implementación y los indicadores iniciales del constructor, esto puede no estar disponible.

  `buffer`

    El búfer binario subyacente (una instancia `BufferedIOBase`) que maneja `TextIOBase`. Esto no es parte del API de `TextIOBase` y puede no existir en algunas implementaciones.

  `detach`()

    Separa el búfer binario subyacente de `TextIOBase` y lo retorna.

    Una vez que se ha separado el búfer subyacente, la `TextIOBase` está en un estado inutilizable.

    Algunas implementaciones de `TextIOBase`, como `StringIO`, puede no tener el concepto de un búfer subyacente y llamar a este método se lanzará `UnsupportedOperation`.

    Nuevo en la versión 3.1.

  `read`(size=-1, /)

    Lee y retorna como máximo size caracteres del stream como un `str` singular. Si size es negativo o `None`, lee hasta llegar al fin del archivo.

  `readline`(size=-1, /)

    Leer hasta la nueva línea o fin del archivo y retorna un `str` singular. Si el stream está al fin del archivo una cadena de caracteres se retorna.

    Si se especifica size como máximo size de caracteres será leído.

  `seek`(offset, whence=SEEK_SET, /)

    Cambia la posición del stream dada offset. El comportamiento depende del parámetro whence. El valor dado de whence es `SEEK_SET`.

    - `SEEK_SET` o `0`: buscar el inicio del stream (el dado); offset debería ser un número dado por `TextIOBase.tell()`, o cero. Cualquier otro valor offset produce comportamiento indefinido.

    - `SEEK_CUR` o `1`: buscar la posición actual; offset debería ser cero, que es una operación no (no se apoya ningún otro valor).

    - `SEEK_END` o `2`: buscar el fin del stream; offset debería ser cero (cualquier otro valor no es apoyado).

    Retorna la nueva posición absoluta como un número opaco.

    Nuevo en la versión 3.1: Los constantes``SEEK_*``.

  `tell`()

    Retorna la posición actual de la secuencia como un número opaco. El número no suele representar una cantidad de bytes en el almacenamiento binario subyacente.

  `write`(s, /)

    Escribe la cadena de caracteres s al stream y retorna el número de caracteres grabadas.

class `io.``TextIOWrapper`(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

  A buffered text stream providing higher-level access to a `BufferedIOBase` buffered binary stream. It inherits `TextIOBase`.

  encoding da el nombre de la codificación con que el stream será codificada o descodificado. Se da al valor predeterminado `locale.getpreferredencoding(False)`.

  errors es una cadena de caracteres opcional que especifica cómo se manejan los errores codificados y descodificados. Pasa `'strict'` para lanzar una excepción `ValueError` si hay un error codificado (el valor predeterminado `None` tiene el mismo efecto), o pasa `'ignore'` para ignorar errores. (Tenga en cuenta que ignorar errores puede llevar a perder datos). `'replace'` causa un marcador de reemplazo (como `'?'`) para ser insertado donde haya datos mal formados. `'backslashreplace'` reemplaza datos mal formados con una secuencia de escape de tipo barra invertida. Cuando se escribe, `'xmlcharrefreplace'` (reemplazar con la referencia apropiada de XML) o `'namereplace'` (reemplazar con secuencias de caracteres `\N{…}`) pueden ser usadas. Cualquier otro nombre de manejador de errores que hayan sido registrados con `codecs.register_error()` también son validas.

  newline controla cómo finalizar las terminaciones de líneas. Pueden ser `None`, `''`, `'\n'`, `'\r'`, and `'\r\n'`. Funciona de la siguiente manera:

  - When reading input from the stream, if newline is `None`, universal newlines mode is enabled. Lines in the input can end in `'\n'`, `'\r'`, or `'\r\n'`, and these are translated into `'\n'` before being returned to the caller. If newline is `''`, universal newlines mode is enabled, but line endings are returned to the caller untranslated. If newline has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.

  - Al escribir la salida al stream, si newline es `None`, cualquier carácter `'\n'` escrito son traducidos a la línea separador default del sistema, `os.linesep`. Si newline es `''` o `'\n'`, la traducción no ocurre. Si newline es de cualquier de los otros valores legales, cualquier carácter `'\n'` escrito es traducido a la cadena de caracteres dada.

  Si line_buffering es `True`, se implica `flush()` cuando una llamada a grabar contiene un carácter de nueva línea o un retorno.

  Si write_through es `True`, llamadas a `write()` no garantizan ser pasados por el proceso de búfer: cualquier dato grabado en el objeto `TextIOWrapper` es inmediatamente manejado por el buffer binario subyacente.

  Distinto en la versión 3.3: Se ha agregado el argumento write_through.

  Distinto en la versión 3.3: La codificación (encoding) por defecto es ahora `locale.getpreferredencoding(False)` en vez de `locale.getpreferredencoding()`. No cambie temporalmente la codificación local usando `locale.setlocale()`, use la codificación local actual en vez del preferido del usuario.

  `TextIOWrapper` provides these data attributes and methods in addition to those from `TextIOBase` and `IOBase`:

  `line_buffering`

    Si el almacenamiento en línea está habilitado.

  `write_through`

    Si grabaciones son pasadas inmediatamente al búfer binario subyacente.

    Nuevo en la versión 3.7.

  `reconfigure`(*[, encoding][, errors][, newline][, line_buffering][, write_through])

    Reconfigura este stream textual usando las nuevas configuraciones de encoding, errors, newline, line_buffering y write_through.

    Los parámetros que no son especificados mantienen las configuraciones actuales, excepto por `errors='strict'` cuando encoding se especifica pero errors no está especificado.

    No es posible cambiar la codificación o nueva línea si algunos datos han sido captados por el stream. Sin embargo, cambiando la codificación después de grabar es posible.

    Este método hace una nivelación implícita del stream antes de configurar los nuevos parámetros.

    Nuevo en la versión 3.7.

class `io.``StringIO`(initial_value='', newline='\n')

  A text stream using an in-memory text buffer. It inherits `TextIOBase`.

  The text buffer is discarded when the `close()` method is called.

  El valor inicial del búfer puede ser configurado dando initial_value. Si la traducción de la nueva línea es habilitado, nuevas líneas serán codificado como si fuera por `write()`. El stream está posicionado al inicio del búfer.

  The newline argument works like that of `TextIOWrapper`, except that when writing output to the stream, if newline is `None`, newlines are written as `\n` on all platforms.

  `StringIO` provides this method in addition to those from `TextIOBase` and `IOBase`:

  `getvalue`()

    Retorna un `str` que contiene el contenido entero de los búfer. Nuevas lineas son descodificados como si fuera `read()`, aunque la posición de la transmisión no haya cambiado.

  Ejemplos de uso:

      import io

      output = io.StringIO()
      output.write('First line.\n')
      print('Second line.', file=output)

      # Retrieve file contents -- this will be
      # 'First line.\nSecond line.\n'
      contents = output.getvalue()

      # Close object and discard memory buffer --
      # .getvalue() will now raise an exception.
      output.close()

class `io.``IncrementalNewlineDecoder`

  Un códec auxiliar que descodifica nuevas líneas para el modo universal newlines. Hereda `codecs.IncrementalDecoder`.

## Rendimiento

Esta sección discute el rendimiento de las implementaciones concretas de E/S proporcionadas.

### E/S Binaria

Leyendo y grabando solamente grandes porciones de datos incluso cuando el usuario pide para solo un byte, E/S de tipo búfer esconde toda ineficiencia llamando y ejecutando las rutinas E/S del sistema operativo que no ha pasado por el proceso de búfer. La ganancia depende en el OS y el tipo de E/S que se ejecuta. Por ejemplo, en algunos sistemas operativos modernos como Linux, un disco E/S sin búfer puede ser rápido como un E/S búfer. Al final, sin embargo, es que el E/S búfer ofrece rendimiento predecible independientemente de la plataforma y el dispositivo de respaldo. Entonces es siempre preferible user E/S búfer que E/S sin búfer para datos binarios.

### E/S Texto

E/S de tipo texto por sobre un almacenamiento binario (como un archivo) es más lento que un E/S binario sobre el mismo almacenamiento porque requiere conversiones entre unicode y datos binarios usando un códec de caracteres. Esto puede ser notable al manejar datos enormes de texto como archivos de registro. También `TextIOWrapper.tell()` y `TextIOWrapper.seek()` son bastante lentos debido al uso del algoritmo de reconstrucción.

`StringIO`, sin embargo, es un contenedor unicode nativo en memoria y exhibirá una velocidad similar a `BytesIO`.

### Multihilo

objetos `FileIO` son seguros para subprocesos en la medida en que las llamadas al sistema operativo(como `read(2)` en Unix) que envuelven también son seguros para subprocesos.

Objetos binarios búfer (instancias de `BufferedReader`, `BufferedWriter`, `BufferedRandom` y `BufferedRWPair`) protegen sus estructuras internas usando un bloqueo; es seguro, entonces, llamarlos de varios hilos a la vez.

objetos `TextIOWrapper` no son seguros para subprocesos.

### Reentrada

Objetos binarios búfer (instancias de `BufferedReader`, `BufferedWriter`, `BufferedRandom` y `BufferedRWPair`) no son reentrante. Mientras llamadas reentrantes no ocurren en situaciones normales pueden surgir haciendo E/S en un manejador `signal`. Si un hilo trata de entrar de nuevo a un objeto búfer que se está accediendo actualmente, se lanza un `RuntimeError`. Tenga en cuenta que esto no prohíbe un hilo diferente entrando un objeto búfer.

The above implicitly extends to text files, since the `open()` function will wrap a buffered object inside a `TextIOWrapper`. This includes standard streams and therefore affects the built-in `print()` function as well.