"csv" --- Lectura y escritura de archivos CSV
*********************************************

**Código fuente:** Lib/csv.py

======================================================================

El tan llamado CSV (Valores Separados por Comas) es el formato más
común de importación y exportación de hojas de cálculo y bases de
datos. El formato CSV se utilizó durante muchos años antes de intentar
describir el formato de manera estandarizada en **RFC 4180**. La falta
de un estándar bien definido significa que a veces existen pequeñas
diferencias en la información producida y consumida por diferentes
aplicaciones. Estas diferencias pueden ser molestas al momento de
procesar archivos CSV desde múltiples fuentes. Aún así, aunque los
delimitadores y separadores varíen, el formato general es lo
suficientemente similar como para que sea posible un sólo módulo que
puede manipular tal información eficientemente, escondiendo los
detalles de lectura y escritura de datos del programador.

El módulo "csv" implementa clases para leer y escribir datos tabulares
en formato CSV. Permite a los programadores decir, "escribe estos
datos en el formato preferido por Excel", o "lee datos de este archivo
que fue generado por Excel", sin conocer los detalles precisos del
formato CSV usado por Excel. Los programadores también pueden
describir los formatos CSV entendidos por otras aplicaciones o definir
sus propios formatos CSV para fines particulares.

Los objetos "reader" y "writer" del módulo "csv" leen y escriben
secuencias. Los programadores también pueden leer y escribir datos en
forma de diccionario usando las clases "DictReader" y "DictWriter".

Ver también:

  **PEP 305** - API de archivo CSV
     La Propuesta de Mejora de Python (PEP, por sus siglas en inglés)
     que propone esta adición a Python.


Contenidos del módulo
=====================

El módulo "csv" define las siguientes funciones:

csv.reader(csvfile, dialect='excel', **fmtparams)

   Retorna un objeto *reader* que iterará sobre las líneas del
   *csvfile* proporcionado. *csvfile* puede ser cualquier objeto que
   soporte el protocolo *iterator* y retorna una cadena de caracteres
   siempre que su método "__next__()" sea llamado --- tanto *objetos
   de archivo* como objetos de lista son adecuados. Si *csvfile* es un
   objeto de archivo, debería ser abierto con "newline=''". [1] Se
   puede proporcionar un parámetro opcional *dialect*, el cual se
   utiliza para definir un conjunto de parámetros específicos para un
   dialecto de CSV particular. Puede ser una instancia de una subclase
   de la clase "Dialect" o una de las cadenas retornadas por la
   función "list_dialects()". Los otros argumentos nombrados
   opcionales *fmtparams* pueden ser dados para sustituir parámetros
   de formato individuales del dialecto actual.  Para detalles
   completos sobre el dialecto y los parámetros de formato, vea la
   sección Dialectos y parámetros de formato.

   Cada fila leída del archivo csv es retornada como una lista de
   cadenas. No se realiza conversión automática de tipo de datos a
   menos que la opción de formato "QUOTE_NONNUMERIC" esté especificada
   (en ese caso los campos no citados son transformados en flotantes).

   Un pequeño ejemplo de uso:

      >>> import csv
      >>> with open('eggs.csv', newline='') as csvfile:
      ...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
      ...     for row in spamreader:
      ...         print(', '.join(row))
      Spam, Spam, Spam, Spam, Spam, Baked Beans
      Spam, Lovely Spam, Wonderful Spam

csv.writer(csvfile, dialect='excel', **fmtparams)

   Retorna un objeto escritor responsable de convertir los datos del
   usuario en cadenas delimitadas en el objeto similar a un archivo
   dado. *csvfile* puede ser cualquier objeto con un método "write()".
   Si *csvfile* es un objeto de archivo, debe abrirse con "newline=''"
   [1]. Se puede proporcionar un parámetro *dialect* opcional que se
   usa para definir un conjunto de parámetros específicos para un
   dialecto CSV particular. Puede ser una instancia de una subclase de
   la clase "Dialect" o una de las cadenas retornadas por la función
   "list_dialects()". Los otros argumentos opcionales de la palabra
   clave *fmtparams* se pueden proporcionar para anular los parámetros
   de formato individuales en el dialecto actual. Para obtener
   detalles completos sobre dialectos y parámetros de formato,
   consulte la sección Dialectos y parámetros de formato. Para
   facilitar al máximo la interfaz con módulos que implementan la API
   de base de datos, el valor "None" se escribe como una cadena vacía.
   Si bien esta no es una transformación reversible, facilita el
   volcado de valores de datos SQL NULL en archivos CSV sin
   preprocesar los datos retornados por una llamada "cursor.fetch*".
   Todos los demás datos que no son cadenas se clasifican con "str()"
   antes de escribirse.

   Un pequeño ejemplo de uso:

      import csv
      with open('eggs.csv', 'w', newline='') as csvfile:
          spamwriter = csv.writer(csvfile, delimiter=' ',
                                  quotechar='|', quoting=csv.QUOTE_MINIMAL)
          spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
          spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

csv.register_dialect(name[, dialect[, **fmtparams]])

   Asocie *dialect* con *name*. *name* debe ser una cadena. El
   dialecto se puede especificar pasando una subclase de "Dialect", o
   mediante argumentos de palabra clave *fmtparams*, o ambos, con
   argumentos de palabra clave que anulan los parámetros del dialecto.
   Para obtener detalles completos sobre dialectos y parámetros de
   formato, consulte la sección Dialectos y parámetros de formato.

csv.unregister_dialect(name)

   Borra el dialecto asociado a *name* del registro de dialectos. Un
   "Error" es lanzado si *name* no está registrado como el nombre de
   un dialecto.

csv.get_dialect(name)

   Retorna el dialecto asociado a *name*.  Un "Error" es lanzado si
   *name* no está registrado como el nombre de un dialecto.  Esta
   función retorna un objeto "Dialect" inmutable.

csv.list_dialects()

   Retorna los nombres de todos los dialectos registrados.

csv.field_size_limit([new_limit])

   Retorna el tamaño máximo de campo permitido actualmente por el
   intérprete. Si *new_limit* es dado, este se convierte en el nuevo
   límite.

El módulo "csv" define las siguientes clases:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

   Crea un objeto que opera como un *reader* común, pero mapea la
   información en cada fila a un "dict" cuyas claves son provistas en
   el parámetro opcional *fieldnames*.

   El parámetro *fieldnames* es una *sequence*. Si se omite
   *fieldnames*, los valores en la primera fila del archivo *f* serán
   usados como nombres de campo. Independientemente de como se
   determinen los nombres de campo, el diccionario preserva su orden
   original.

   Si una fila tiene más campos que nombres de campo, los datos
   restantes son colocados en una lista y guardados con el nombre de
   campo especificado por *restkey* (que por defecto es "None"). Si
   una fila que no esta en blanco tiene menos campos que nombres de
   campo, los valores faltantes son rellenados con el valor de
   *restval* (que por defecto es "None").

   Todos los demás argumentos de palabra clave u opcionales son
   pasados a la instancia subyacente de "reader".

   Distinto en la versión 3.6: Las filas retornadas son ahora de tipo
   "OrderedDict".

   Distinto en la versión 3.8: Las filas retornadas son ahora de tipo
   "dict".

   Un pequeño ejemplo de uso:

      >>> import csv
      >>> with open('names.csv', newline='') as csvfile:
      ...     reader = csv.DictReader(csvfile)
      ...     for row in reader:
      ...         print(row['first_name'], row['last_name'])
      ...
      Eric Idle
      John Cleese

      >>> print(row)
      {'first_name': 'John', 'last_name': 'Cleese'}

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

   Crea un objeto que opera como un *writer* común, pero mapea
   diccionarios a filas de salida. El parámetro *fieldnames* es una
   "secuencia" de claves que identifican el orden en el cual los
   valores en el diccionario pasados al método "writerow()" son
   escritos en el archivo *f*. El parámetro opcional *restval*
   especifica el valor a ser escrito si al diccionario le falta una
   clave en *fieldnames*. Si el diccionario pasado al método
   "writerow()" contiene una clave no encontrada en *fieldnames*, el
   parámetro opcional *extrasaction* indica que acción ejecutar. Si
   esta configurado en "'raise'", el valor por defecto, es lanzado un
   "ValueError". Si esta configurado con "'ignore'", los valores extra
   en el diccionario son ignorados. Cualquier otro argumento de
   palabra clave u opcional es pasado a la instancia subyacente de
   "reader".

   Nótese que a diferencia de la clase "DictReader", el parámetro
   *fieldnames* de la clase "DictWriter" no es opcional.

   Un pequeño ejemplo de uso:

      import csv

      with open('names.csv', 'w', newline='') as csvfile:
          fieldnames = ['first_name', 'last_name']
          writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

          writer.writeheader()
          writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
          writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
          writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})

class csv.Dialect

   La clase "Dialect" es una clase contenedora cuyos atributos
   contienen información sobre cómo manejar las comillas dobles, los
   espacios en blanco, los delimitadores, etc. Debido a la falta de
   una especificación estricta de CSV, diferentes aplicaciones
   producen datos CSV sutilmente diferentes. Las instancias de
   "Dialect" definen cómo se comportan las instancias de "reader" y
   "writer".

   Todos los nombres disponibles de "Dialect" son retornados por
   "list_dialects()", y pueden ser registrados con clases específicas
   de "reader" y "writer" a través de sus funciones que inician
   ("__init__") así:

      import csv

      with open('students.csv', 'w', newline='') as csvfile:
          writer = csv.writer(csvfile, dialect='unix')
                                       ^^^^^^^^^^^^^^

class csv.excel

   La clase "excel" define las propiedades usuales de un archivo CSV
   generado por Excel. Esta registrada con el nombre de dialecto
   "'excel'".

class csv.excel_tab

   La clase "excel_tab" define las propiedades usuales de un archivo
   delimitado por tabulaciones generado por Excel. Esta registrada con
   el nombre de dialecto "'excel-tab'".

class csv.unix_dialect

   La clase "unix_dialect" define las propiedades usuales de un
   archivo CSV generado en sistemas UNIX, es decir, usando "'\n'" como
   terminador de línea y citando todos los campos. Esta registrada con
   el nombre de dialecto "'unix'".

   Nuevo en la versión 3.2.

class csv.Sniffer

   La clase "Sniffer" es usada para deducir el formato de un archivo
   CSV.

   La clase "Sniffer" provee 2 métodos:

   sniff(sample, delimiters=None)

      Analiza la muestra dada y retorna una subclase "Dialect"
      reflejando los parámetros encontrados. Si el parámetro opcional
      *delimiters* es dado, este será interpretado como una cadena que
      contiene posibles caracteres delimitadores válidos.

   has_header(sample)

      Analiza el texto de muestra (se supone que está en formato CSV)
      y retorna "True" si la primera fila parece ser una serie de
      encabezados de columna. Al inspeccionar cada columna, se
      considerará uno de dos criterios clave para estimar si la
      muestra contiene un encabezado:

         * las filas segunda n-th contienen valores numéricos

         * las segundas filas n-th contienen cadenas en las que la
           longitud de al menos un valor difiere de la de la supuesta
           cabecera de esa columna.

      Se muestran veinte filas después de la primera; si más de la
      mitad de las columnas + filas cumplen los criterios, se retorna
      "True".

   Nota:

     Este método es una heurística aproximada y puede producir tanto
     falsos positivos como negativos.

Un ejemplo para el uso de "Sniffer":

   with open('example.csv', newline='') as csvfile:
       dialect = csv.Sniffer().sniff(csvfile.read(1024))
       csvfile.seek(0)
       reader = csv.reader(csvfile, dialect)
       # ... process CSV file contents here ...

El módulo "csv" define las siguientes constantes:

csv.QUOTE_ALL

   Ordena a los objetos "writer" citar todos los campos.

csv.QUOTE_MINIMAL

   Ordena a los objetos "writer" citar solo aquellos campos que
   contengan caracteres especiales como por ejemplo *delimiter,
   *quotechar* o cualquiera de los caracteres en *lineterminator*.

csv.QUOTE_NONNUMERIC

   Ordena a los objetos "writer" citar todos los campos no numéricos.

   Ordena al *reader* a convertir todos los campos no citados al tipo
   *float*.

csv.QUOTE_NONE

   Ordena a los objetos "writer" nunca citar campos. Cuando el
   *delimiter* actual aparece en los datos de salida es precedido por
   el carácter *escapechar* actual. Si *escapechar* no esta definido,
   el *writer* lanzará "Error" si cualquier carácter que requiere
   escaparse es encontrado.

   Ordena a "reader" no ejecutar un procesamiento especial de
   caracteres citados.

El módulo "csv" define la siguiente excepción:

exception csv.Error

   Lanzada por cualquiera de las funciones cuando se detecta un error.


Dialectos y parámetros de formato
=================================

Para facilitar la especificación del formato de registros de entrada y
salida, los parámetros específicos de formateo son agrupados en
dialectos. Un dialecto es una subclase de la clase "Dialect" con un
conjunto de métodos específicos y un solo método "validate()". Cuando
se crean objetos "reader" o "writer", el programador puede especificar
una cadena de caracteres o una subclase de la clase "Dialect" como el
parámetro de dialecto. Además de, o en vez de, el parámetro *dialect*,
el programador también puede especificar parámetros de formateo
individuales, con los mismos nombres que los atributos definidos
debajo para la clase "Dialect".

Los dialectos soportan los siguientes atributos:

Dialect.delimiter

   Una cadena de un solo carácter usada para separar campos. Por
   defecto es "','".

Dialect.doublequote

   Controla como las instancias de *quotechar* que aparecen dentro de
   un campo deben estar citadas. Cuando es "True", el carácter es
   duplicado. Cuando es "False", el *escapechar* es usado como un
   prefijo el *quotechar*. Por defecto es "True".

   En la salida, si el *doublequote* es "False" y el *escapechar* no
   está configurado, un "Error" es lanzado si se encuentra un
   *quotechar* en algún campo.

Dialect.escapechar

   Una cadena de un solo carácter usada por el *writer* para escapar
   al *delimiter* si *quoting* está configurado como "QUOTE_NONE" y al
   *quotechar* si *doublequote* es "False". En la lectura, el
   *escapechar* elimina cualquier significado especial del siguiente
   carácter. Por defecto es "None", lo que deshabilita el escape.

Dialect.lineterminator

   La cadena de caracteres usada para terminar las líneas producidas
   por "writer". Por defecto es "'\r\n'".

   Nota:

     El "reader" esta codificado para reconocer tanto "'\r'" o "'\n'"
     como final de línea, e ignora *lineterminator*. Este
     comportamiento puede cambiar en el futuro.

Dialect.quotechar

   Una cadena de un solo carácter usada para citar campos que
   contienen caracteres especiales, como lo son *delimiter* o
   *quotechar*, o que contienen caracteres de nueva línea. Por defecto
   es  "'"'".

Dialect.quoting

   Controla cuando las comillas deberían ser generadas por el *writer*
   y ser reconocidas por el *reader*. Puede tomar cualquiera de las
   constantes "QUOTE_*" (ver sección Contenidos del módulo) y por
   defecto es "QUOTE_MINIMAL".

Dialect.skipinitialspace

   When "True", spaces immediately following the *delimiter* are
   ignored. The default is "False".

Dialect.strict

   Cuando es "True", lanza una excepción "Error" sobre una mala
   entrada CSV. Por defecto es "False".


Objetos *Reader*
================

Los objetos *reader* (instancias de "DictReader" y objetos retornados
por la función "reader()") contienen los siguientes métodos públicos:

csvreader.__next__()

   Retorna la siguiente fila del objeto iterable del lector como una
   lista (si el objeto retornó desde "reader()") o un dict (si es una
   instancia de "DictReader"), analizado de acuerdo con el "Dialect"
   actual. Por lo general, debería llamar a esto como "next(reader)".

Los objetos *reader* contienen los siguientes atributos públicos:

csvreader.dialect

   Una descripción de sólo lectura del dialecto en uso por el
   intérprete.

csvreader.line_num

   El número de líneas leídas del iterador fuente. Esto no es lo mismo
   que el número de registros retornado, ya que los registros pueden
   abarcar múltiples líneas.

Los objetos *DictReader* tienen los siguientes atributos públicos:

DictReader.fieldnames

   Si no son pasados como parámetros cuando se crea el objeto, este
   atributo es inicializado en el primer acceso o cuando es leído el
   primer registro del archivo.


Objetos *Writer*
================

Los objetos "Writer" (instancias de "DictWriter" y objetos retornados
por la función "writer()") contienen los siguientes métodos públicos.
Una *row* debe ser un iterable de cadenas de caracteres o números para
objetos "Writer" y un diccionario que mapea nombres de campo a cadenas
de caracteres o números (pasándolos primero a través de "str()") para
objetos "DictWriter". Note que los números complejos se escriben
rodeados de paréntesis. Esto puede causar algunos problemas para otros
programas que leen archivos CSV (asumiendo que soportan números
complejos).

csvwriter.writerow(row)

   Escriba el parámetro *row* en el objeto de archivo del escritor,
   formateado de acuerdo con el "Dialect" actual. Retorna el valor de
   retorno de la llamada al método *write* del objeto de archivo
   subyacente.

   Distinto en la versión 3.5: Agregado soporte para iterables.

csvwriter.writerows(rows)

   Escribe todos los elementos en *rows* (un iterable de objetos *row*
   como se describe anteriormente) al objeto de archivo del *writer*,
   formateados según el dialecto actual.

Los objetos *writer* contienen los siguientes atributos públicos:

csvwriter.dialect

   Una descripción de solo lectura del dialecto en uso por el
   *writer*.

Los objetos *DictWriter* contienen los siguientes métodos públicos:

DictWriter.writeheader()

   Escribe una fila con los nombres de los campos (como se especifica
   en el constructor) al objeto de archivo del *writer*, formateada
   según el dialecto actual. Retorna el valor de retorno de la llamada
   a "csvwriter.writerow()" usada internamente.

   Nuevo en la versión 3.2.

   Distinto en la versión 3.8: "writeheader()" ahora también retorna
   el valor retornado por el método "csvwriter.writerow()" que usa
   internamente.


Ejemplos
========

El ejemplo más simple de lectura de un archivo CSV:

   import csv
   with open('some.csv', newline='') as f:
       reader = csv.reader(f)
       for row in reader:
           print(row)

Lectura de un archivo con un formato alternativo:

   import csv
   with open('passwd', newline='') as f:
       reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
       for row in reader:
           print(row)

El correspondiente ejemplo de escritura más simple es:

   import csv
   with open('some.csv', 'w', newline='') as f:
       writer = csv.writer(f)
       writer.writerows(someiterable)

Ya que "open()" es usado para abrir un archivo CSV para lectura, el
archivo será decodificado por defecto en unicode usando la
codificación por defecto del sistema (ver
"locale.getpreferredencoding()"). Para decodificar un archivo usando
una codificación diferente, usa el argumento "encoding" de open:

   import csv
   with open('some.csv', newline='', encoding='utf-8') as f:
       reader = csv.reader(f)
       for row in reader:
           print(row)

Lo mismo aplica a escribir en algo diferente a la codificación por
defecto del sistema: especifique el argumento de codificación cuando
abra el archivo de salida.

Registrando un nuevo dialecto:

   import csv
   csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
   with open('passwd', newline='') as f:
       reader = csv.reader(f, 'unixpwd')

Un uso ligeramente más avanzado del *reader* --- captura y reporte de
errores:

   import csv, sys
   filename = 'some.csv'
   with open(filename, newline='') as f:
       reader = csv.reader(f)
       try:
           for row in reader:
               print(row)
       except csv.Error as e:
           sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))

Y a pesar de que el módulo no soporta el análisis de cadenas de
caracteres directamente, puede ser realizado fácilmente:

   import csv
   for row in csv.reader(['one,two,three']):
       print(row)

-[ Notas al pie ]-

[1] Si "newline=''" no es especificado, las nuevas líneas dentro de
    los campos citados no serán interpretadas correctamente y, en
    plataformas que utilicen finales de línea "\r\n" en la escritura,
    se añadirá un "\r" extra. Siempre debería ser seguro especificar
    "newline=''", ya que el módulo csv realiza su propio manejo de
    nuevas líneas (*universal*).
