# `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`

  Cuando es `True`, el espacio en blanco que sigue después del delimiter es ignorado. Por defecto es `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:

`csvreader.``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(1,2)

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