"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
   ejecutible.

   "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.

La "BufferedIOBase" ABC maneja el búfer en un *stream* de *bytes* sin
formato ("RawIOBase"). Sus subclasificaciones, "BufferedWriter",
"BufferedReader", y "BufferedRWPair" *streams* de búfer que son
legible, grabable, y ambos legible y grabable.  "BufferedRandom"
provee un interfaz búfer a *streams* de acceso aleatorio. Otra
subclasificación "BufferedIOBase", "BytesIO", es un *stream* de
*bytes* en memoria.

El "TextIOBase" ABC, otra subclasificación de "IOBase", trata con los
*streams* cuyos *bytes* representan texto, y maneja la codificación y
descodificación para cadenas de caracteres y de estos mismos.
"TextIOWrapper", que extiende a este, es un interfaz textual
almacenado un *stream* sin formato amortiguado ("BufferedIOBase").
Finalmente, "StringIO"  es una *stream* en memoria para texto.

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        | Métodos Mixin y propiedades                        |
|                           |                    | (*Stub*)                 |                                                    |
|===========================|====================|==========================|====================================================|
| "IOBase"                  |                    | "fileno", "seek", and    | "close", "closed", "__enter__", "__exit__",        |
|                           |                    | "truncate"               | "flush", "isatty", "__iter__", "__next__",         |
|                           |                    |                          | "readable", "readline", "readlines", "seekable",   |
|                           |                    |                          | "tell", "writable", and "writelines"               |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "RawIOBase"               | "IOBase"           | "readinto" and "write"   | Heredada "IOBase" methods, "read", and "readall"   |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "BufferedIOBase"          | "IOBase"           | "detach", "read",        | Heredada "IOBase" methods, "readinto", and         |
|                           |                    | "read1", and "write"     | "readinto1"                                        |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "TextIOBase"              | "IOBase"           | "detach", "read",        | Heredada "IOBase" methods, "encoding", "errors",   |
|                           |                    | "readline", and "write"  | and "newlines"                                     |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+


Clases base E/S
---------------

class io.IOBase

   La clase base abstracta para todas las clases de tipo E/S, actuando
   sobre *streams* de *bytes*. No hay constructor público.

   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 subcalsificaciones) 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 convenienca, 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*.

      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

   Clase base para binarios de tipo E/S sin formato. Hereda la clase
   "IOBase". No hay constructor público.

   E/S binario sin formato proporciona acceso de nivel bajo a algún
   dispositivo del sistema operativo o API, y no intenta de encapsular
   primitivos de alto nivel (esta función se le deja a E/S de tipo
   búfer y E/S de tipo texto; esto se describe más adelante).

   Además de los atributos y métodos de "IOBase", la clase "RawIOBase"
   proporciona los siguientes métodos:

   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

   Clase base para *streams* binarios que apoyan algún tipo de búfer.
   Hereda "IOBase". No hay constructor público.

   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" provee o anula estos métodos y atributos en
   adición a los de "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])

      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)

   "FileIO" representa un archivo de nivel OS conteniendo datos en
   *bytes*. Implementa la interfaz "RawIOBase" (y por ende también la
   interfaz "IOBase").

   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.

   Además de los atributos y métodos de las clases "IOBase" y
   "RawIOBase", "FileIO", estos proveen los siguientes atributos:

   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])

   Una implementación de *stream* usando búferes de *bytes* en
   memoria. Hereda "BufferedIOBase".  El búfer está descartado cuando
   se llama al método "close()".

   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])

      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)

   Un búfer dando un nivel de alto acceso a un objeto  "RawIOBase"
   legible y secuencial. Hereda "BufferedIOBase". Al leer datos de
   este objeto se puede solicitar una mayor cantidad de datos del
   *stream* sin formato subyacente, y mantener el búfer interno. Los
   datos que han pasado por el proceso de búfer pueden ser retornados
   directamente en lecturas posteriores.

   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])

      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])

      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])

      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)

   Un búfer que proporciona un nivel alto de acceso a un objeto
   "RawIOBase" grabable y secuencial. Hereda "BufferedIOBase". Al
   escribir a este objeto, los datos normalmente se colocan en un
   búfer interno. El búfer se escribirá en el objeto "RawIOBase"
   subyacente bajo varias condiciones, incluyendo:

   * 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 "BufferedRandom"
     objects);

   * 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)

   Una interfaz búfer para *streams* de acceso aleatorio. Hereda
   "BufferedReader" y "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)

   Un objeto búfer E/S combinando dos objetos "RawIOBase"
   unidireccionales -- uno legible y el otro escribible -- a un punto
   final singular bidireccional. Hereda "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

   Clase base para los *streams* de tipo texto. Esta clase proporciona
   una interfaz basada en caracteres y líneas para transmitir E/S.
   Hereda "IOBase". No hay constructor público.

   "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 cracteres, 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)

   Una secuencia de texto almacenado sobre un *stream* binario
   "BufferedIOBase". Hereda "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:

   * Al leer la entrada del *stream*, si *newline* es "None", el modo
     *universal newlines* está habilitada. Líneas en la entrada pueden
     terminar en "'\n'", "'\r'", o "'\r\n'", y estos son traducidos a
     "'\n'" antes de ser retornados al llamador. Si es "''", se
     habilita el modo universal de nuevas líneas, pero las
     terminaciones de líneas son retornados al llamador sin traducir.
     Si tiene cualquiera de los otros valores legales, líneas de
     ingreso son terminadas por la cadena de caracteres dada, y la
     línea final se retorna al llamado sin traducir.

   * 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 usaurio.

   "TextIOWrapper" provee estos miembros además de las de "TextIOBase"
   y sus padres:

   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')

   Un *stream* en memoria para E/S de tipo texto. El búfer de tipo
   texto es descartado cuando se llama al método "close()".

   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.

   El argumento *newline* funciona como "TextIOWrapper". El valor dado
   es considerado solamente como caracteres "\n" al final de las
   lineas y no hacen ninguna traducción de nuevas lineas. Si *newline*
   está configurado con "None", nuevas lineas son escritas como "\n"
   en todas las plataformas, pero descodificación universal de las
   nuevas lineas todavía se realiza cuando se lee.

   "StringIO" provee este método además de los de "TextIOBase" y sus
   padres:

   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.

Lo de arriba de forma implícita extiende a los archivos de tipo texto
ya que la función "open()" envolverá un objeto almacenado en un
"TextIOWrapper". Esto incluye *streams* estándar y por ende afecta la
función "print()" también.
