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)

Return a reader object that will process lines from the given csvfile. A csvfile must be an iterable of strings, each in the reader’s defined csv format. A csvfile is most commonly a file-like object or list. If csvfile is a file object, it should be opened with newline=''. [1] An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the Dialect class or one of the strings returned by the list_dialects() function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see section 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)

Return a writer object responsible for converting the user’s data into delimited strings on the given file-like object. csvfile can be any object with a write() method. If csvfile is a file object, it should be opened with newline='' [1]. An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the Dialect class or one of the strings returned by the list_dialects() function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about dialects and formatting parameters, see the Dialectos y parámetros de formato section. To make it as easy as possible to interface with modules which implement the DB API, the value None is written as the empty string. While this isn’t a reversible transformation, it makes it easier to dump SQL NULL data values to CSV files without preprocessing the data returned from a cursor.fetch* call. All other non-string data are stringified with str() before being written.

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.

Si el argumento pasado a fieldnames es un iterador, sera forzado a una list.

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)

Create an object which operates like a regular writer but maps dictionaries onto output rows. The fieldnames parameter is a sequence of keys that identify the order in which values in the dictionary passed to the writerow() method are written to file f. The optional restval parameter specifies the value to be written if the dictionary is missing a key in fieldnames. If the dictionary passed to the writerow() method contains a key not found in fieldnames, the optional extrasaction parameter indicates what action to take. If it is set to 'raise', the default value, a ValueError is raised. If it is set to 'ignore', extra values in the dictionary are ignored. Any other optional or keyword arguments are passed to the underlying writer instance.

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

Si el argumento pasado a fieldnames es un iterador, sera forzado a una list.

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 a los objetos reader convertir todos los campos no entre comillas 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 los objetos reader no ejecutar un procesamiento especial de caracteres comillas.

csv.QUOTE_NOTNULL

Ordena a los objetos writer poner entre comillas todos los campos que no sean None. Esto es similar a QUOTE_ALL, con la excepción que si un campo es None se escribe una cadena de caracteres vacía (sin comillas).

Ordena a los objetos reader interpretar un campo vacío (sin comillas) como None y en caso contrario comportarse como QUOTE_ALL.

Nuevo en la versión 3.12.

csv.QUOTE_STRINGS

Ordena a los objetos writer siempre poner comillas alrededor de campos que sean cadenas de caracteres. Esto es similar a QUOTE_NONNUMERIC, con la excepción que si el valor de un campo es None se escribe una cadena de caracteres vacía (sin comillas).

Ordena a los objetos reader interpretar una cadena de caracteres vacía (sin comillas) como None y en caso contrario comportarse como QUOTE_NONNUMERIC.

Nuevo en la versión 3.12.

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

To make it easier to specify the format of input and output records, specific formatting parameters are grouped together into dialects. A dialect is a subclass of the Dialect class containing various attributes describing the format of the CSV file. When creating reader or writer objects, the programmer can specify a string or a subclass of the Dialect class as the dialect parameter. In addition to, or instead of, the dialect parameter, the programmer can also specify individual formatting parameters, which have the same names as the attributes defined below for the Dialect class.

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.

Distinto en la versión 3.11: No se permite un quotechar vacío.

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

Distinto en la versión 3.11: No se permite un quotechar vacío.

Dialect.quoting

Controls when quotes should be generated by the writer and recognised by the reader. It can take on any of the QUOTE_* constants and defaults to 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:

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

writer objects (DictWriter instances and objects returned by the writer() function) have the following public methods. A row must be an iterable of strings or numbers for writer objects and a dictionary mapping fieldnames to strings or numbers (by passing them through str() first) for DictWriter objects. Note that complex numbers are written out surrounded by parens. This may cause some problems for other programs which read CSV files (assuming they support complex numbers at all).

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)

Cuando se usa open() para abrir un archivo CSV en modo 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