Código fuente:Lib / csv.py

El formato denominado CSV (valores separados por comas) es el formato de importación y exportación más común para hojas de cálculo y bases de datos. El formato CSV se utilizó durante muchos años antes de los intentos de describir el formato de una manera estandarizada en RFC 4180. La falta de un estándar bien definido significa que a menudo existen diferencias sutiles en los datos producidos y consumidos por diferentes aplicaciones. Estas diferencias pueden hacer que sea molesto procesar archivos CSV de múltiples fuentes. Aún así, aunque los delimitadores y los caracteres entre comillas varían, el formato general es lo suficientemente similar como para que sea posible escribir un solo módulo que pueda manipular de manera eficiente dichos datos, ocultando los detalles de la lectura y escritura de los datos del programador.

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

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

Ver también

PEP 305 – API de archivo CSV

La propuesta de mejora de Python que propuso esta adición a Python.

Contenido del módulo

los csv módulo define las siguientes funciones:

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

Devuelve un objeto lector que iterará sobre las líneas en el csvfile. csvfile puede ser cualquier objeto que admita la iterador protocolo y devuelve una cadena cada vez que su __next__() se llama al método – objetos de archivo y los objetos de lista son adecuados. Si csvfile es un objeto de archivo, debe abrirse con newline=''. 1 opcional dialecto Se puede dar un parámetro que se usa para definir un conjunto de parámetros específicos para un dialecto CSV particular. Puede ser una instancia de una subclase del Dialect clase o una de las cadenas devueltas por el list_dialects() función. El otro opcional fmtparams Se pueden proporcionar argumentos de palabras clave para anular los parámetros de formato individuales en el dialecto actual. Para obtener detalles completos sobre el dialecto y los parámetros de formato, consulte la sección Dialectos y parámetros de formato.

Cada fila leída del archivo csv se devuelve como una lista de cadenas. No se realiza ninguna conversión automática de tipos de datos a menos que QUOTE_NONNUMERIC Se especifica la opción de formato (en cuyo caso los campos sin comillas se transforman en flotantes).

Un breve ejemplo de uso:

>>>import csv
>>>withopen('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)

Devuelve 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 write() método. Si csvfile es un objeto de archivo, debe abrirse con newline=''1. Opcional dialecto Se puede dar un parámetro que se usa para definir un conjunto de parámetros específicos para un dialecto CSV particular. Puede ser una instancia de una subclase del Dialect clase o una de las cadenas devueltas por el list_dialects() función. El otro opcional fmtparams Se pueden proporcionar argumentos de palabras clave para anular los parámetros de formato individuales en el dialecto actual. Para obtener detalles completos sobre el dialecto y los parámetros de formato, consulte la sección Dialectos y parámetros de formato. Para que sea lo más fácil posible la interfaz con módulos que implementan la API de base de datos, el valor None se escribe como la 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 devueltos por un cursor.fetch* llama. Todos los demás datos que no son cadenas se encuentran en cadenas con str() antes de ser escrito.

Un breve ejemplo de uso:

import csv
withopen('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]])

Asociar dialecto con nombre. nombre debe ser una cadena. El dialecto se puede especificar pasando una subclase de Dialect, o por fmtparams argumentos de palabras clave, o ambos, con argumentos de palabras clave que anulan los parámetros del dialecto. Para obtener detalles completos sobre el dialecto y los parámetros de formato, consulte la sección Dialectos y parámetros de formato.

csv.unregister_dialect(name)

Eliminar el dialecto asociado con nombre del registro de dialectos. Un Error se eleva si nombre no es un nombre de dialecto registrado.

csv.get_dialect(name)

Devuelve el dialecto asociado con nombre. Un Error se eleva si nombre no es un nombre de dialecto registrado. Esta función devuelve un inmutable Dialect.

csv.list_dialects()

Devuelve los nombres de todos los dialectos registrados.

csv.field_size_limit([new_limit])

Devuelve el tamaño de campo máximo actual permitido por el analizador. Si new_limit se da, esto se convierte en el nuevo límite.

los csv módulo define las siguientes clases:

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

Cree un objeto que funcione como un lector normal pero mapee la información en cada fila a un dict cuyas claves son dadas por el opcional nombres de campo parámetro.

los nombres de campo el parámetro es un secuencia. Si nombres de campo se omite, los valores de la primera fila del archivo F se utilizará como nombres de campo. Independientemente de cómo se determinen los nombres de campo, el diccionario conserva su orden original.

Si una fila tiene más campos que nombres de campo, los datos restantes se colocan en una lista y se almacenan con el nombre de campo especificado por tecla de reposo (que por defecto es None). Si una fila que no está en blanco tiene menos campos que nombres de campo, los valores faltantes se completan con el valor de descanso (que por defecto es None).

Todos los demás argumentos opcionales o de palabra clave se pasan al subyacente reader ejemplo.

Modificado en la versión 3.6: Las filas devueltas ahora son de tipo OrderedDict.

Modificado en la versión 3.8: Las filas devueltas ahora son de tipo dict.

Un breve ejemplo de uso:

>>>import csv
>>>withopen('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)

Cree un objeto que funcione como un escritor normal pero que asigne diccionarios a filas de salida. los nombres de campo el parámetro es un sequence de claves que identifican el orden en el que los valores del diccionario pasaron al writerow() el método se escribe en el archivo F. El opcional descanso parámetro especifica el valor que se escribirá si al diccionario le falta una clave en nombres de campo. Si el diccionario pasa al writerow() El método contiene una clave que no se encuentra en nombres de campo, el opcional extraccion El parámetro indica qué acción tomar. Si está configurado en 'raise', el valor predeterminado, a ValueError es elevado. Si está configurado en 'ignore', se ignoran los valores adicionales del diccionario. Cualquier otro argumento opcional o de palabra clave se pasa al subyacente writer ejemplo.

Tenga en cuenta que a diferencia del DictReader clase, la nombres de campo parámetro de la DictWriter la clase no es opcional.

Un breve ejemplo de uso:

import csv

withopen('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

los Dialect La clase es una clase contenedora en la que se confía principalmente por sus atributos, que se utilizan para definir los parámetros para un reader o writer ejemplo.

class csv.excel

los excel La clase define las propiedades habituales de un archivo CSV generado por Excel. Está registrado con el nombre del dialecto. 'excel'.

class csv.excel_tab

los excel_tab La clase define las propiedades habituales de un archivo delimitado por TAB generado por Excel. Está registrado con el nombre del dialecto. 'excel-tab'.

class csv.unix_dialect

los unix_dialect La clase define las propiedades habituales de un archivo CSV generado en sistemas UNIX, es decir, utilizando 'n' como terminador de línea y citando todos los campos. Está registrado con el nombre del dialecto. 'unix'.

Nuevo en la versión 3.2.

class csv.Sniffer

los Sniffer La clase se usa para deducir el formato de un archivo CSV.

los Sniffer La clase proporciona dos métodos:

sniff(sample, delimiters=None)

Analizar lo dado muestra y devolver un Dialect subclase que refleja los parámetros encontrados. Si el opcional delimitadores se proporciona un parámetro, se interpreta como una cadena que contiene posibles caracteres delimitadores válidos.

has_header(sample)

Analice el texto de muestra (se supone que está en formato CSV) y regrese True si la primera fila parece ser una serie de encabezados de columna.

Un ejemplo de Sniffer usar:

withopen('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 ...

los csv módulo define las siguientes constantes:

csv.QUOTE_ALL

Instruye writer objetos para citar todos los campos.

csv.QUOTE_MINIMAL

Instruye writer objetos para citar solo aquellos campos que contienen caracteres especiales como delimitador, citachar o cualquiera de los personajes de terminador de linea.

csv.QUOTE_NONNUMERIC

Instruye writer objetos para citar todos los campos no numéricos.

Indica al lector que convierta todos los campos no citados a tipo flotador.

csv.QUOTE_NONE

Instruye writer objetos para nunca citar campos. Cuando la corriente delimitador ocurre en los datos de salida está precedido por la corriente escaparchar personaje. Si escaparchar no está configurado, el escritor levantará Error si se encuentra algún personaje que requiera escapar.

Instruye reader para no realizar ningún procesamiento especial de caracteres de comillas.

los csv módulo define la siguiente excepción:

exception csv.Error

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

Dialectos y parámetros de formato

Para facilitar la especificación del formato de los registros de entrada y salida, los parámetros de formato específicos se agrupan en dialectos. Un dialecto es una subclase del Dialect clase que tiene un conjunto de métodos específicos y un solo validate() método. Al crear reader o writer objetos, el programador puede especificar una cadena o una subclase del Dialect class como parámetro de dialecto. Además de, o en lugar de, el dialecto parámetro, el programador también puede especificar parámetros de formato individuales, que tienen los mismos nombres que los atributos definidos a continuación para el Dialect clase.

Los dialectos admiten los siguientes atributos:

Dialect.delimiter

Una cadena de un carácter que se utiliza para separar campos. Por defecto es ','.

Dialect.doublequote

Controla cómo instancias de citachar que aparecen dentro de un campo se deben citar. Cuando True, el carácter se duplica. Cuando False, los escaparchar se utiliza como prefijo del citachar. Por defecto es True.

En salida, si doble cita es False y no escaparchar Está establecido, Error se eleva si un citachar se encuentra en un campo.

Dialect.escapechar

Una cadena de un carácter utilizada por el escritor para escapar del delimitador si citando se establece en QUOTE_NONE y el citachar si doble cita es False. Al leer, el escaparchar elimina cualquier significado especial del siguiente carácter. Por defecto es None, que desactiva el escape.

Dialect.lineterminator

La cadena utilizada para terminar las líneas producidas por el writer. Por defecto es 'rn'.

Nota

los reader está codificado para reconocer 'r' o 'n' como final de línea e ignora terminador de linea. Este comportamiento puede cambiar en el futuro.

Dialect.quotechar

Una cadena de un carácter que se utiliza para citar campos que contienen caracteres especiales, como delimitador o citacharo que contengan caracteres de nueva línea. Por defecto es '"'.

Dialect.quoting

Controla cuándo las citas deben ser generadas por el escritor y reconocidas por el lector. Puede asumir cualquiera de los QUOTE_* constantes (ver sección Contenido del módulo) y por defecto es QUOTE_MINIMAL.

Dialect.skipinitialspace

Cuando True, espacio en blanco inmediatamente después del delimitador se ignora. El valor predeterminado es False.

Dialect.strict

Cuando True, levante una excepción Error en una mala entrada de CSV. El valor predeterminado es False.

Objetos del lector

Objetos del lector (DictReader instancias y objetos devueltos por el reader() function) tienen los siguientes métodos públicos:

csvreader.__next__()

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

Los objetos de lector tienen los siguientes atributos públicos:

csvreader.dialect

Una descripción de solo lectura del dialecto que usa el analizador.

csvreader.line_num

El número de líneas leídas del iterador de origen. No es lo mismo que el número de registros devueltos, ya que los registros pueden abarcar varias líneas.

Los objetos DictReader tienen el siguiente atributo público:

csvreader.fieldnames

Si no se pasa como parámetro al crear el objeto, este atributo se inicializa en el primer acceso o cuando se lee el primer registro del archivo.

Objetos del escritor

Writer objetos (DictWriter instancias y objetos devueltos por el writer() function) tienen los siguientes métodos públicos. A hilera debe ser un iterable de cadenas o números para Writer objetos y un diccionario mapeando nombres de campo a cadenas o números (pasándolos a través de str() primero) para DictWriter objetos. Tenga en cuenta que los números complejos se escriben entre paréntesis. Esto puede causar algunos problemas para otros programas que leen archivos CSV (suponiendo que admitan números complejos).

csvwriter.writerow(row)

Escribe el hilera parámetro al objeto de archivo del escritor, formateado de acuerdo con el dialecto actual. Devuelve el valor de retorno de la llamada al escribir método del objeto de archivo subyacente.

Modificado en la versión 3.5: Soporte agregado de iterables arbitrarios.

csvwriter.writerows(rows)

Escriba todos los elementos en filas (un iterable de hilera objetos como se describe arriba) al objeto de archivo del escritor, formateado de acuerdo con el dialecto actual.

Los objetos Writer tienen el siguiente atributo público:

csvwriter.dialect

Una descripción de solo lectura del dialecto que usa el escritor.

Los objetos DictWriter tienen el siguiente método público:

DictWriter.writeheader()

Escriba una fila con los nombres de los campos (como se especifica en el constructor) en el objeto de archivo del escritor, formateado de acuerdo con el dialecto actual. Devuelve el valor de retorno del csvwriter.writerow() llamada utilizada internamente.

Nuevo en la versión 3.2.

Modificado en la versión 3.8: writeheader() ahora también devuelve el valor devuelto por el csvwriter.writerow() método que utiliza internamente.

Ejemplos de

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

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

Leer un archivo con un formato alternativo:

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

El ejemplo de escritura más simple posible correspondiente es:

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

Ya que open() se utiliza para abrir un archivo CSV para su lectura, el archivo se decodificará de forma predeterminada en Unicode utilizando la codificación predeterminada del sistema (consulte locale.getpreferredencoding()). Para decodificar un archivo usando una codificación diferente, use el encoding argumento de abierto:

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

Lo mismo se aplica a la escritura en algo que no sea la codificación predeterminada del sistema: especifique el argumento de codificación al abrir el archivo de salida.

Registro de un nuevo dialecto:

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

Un uso un poco más avanzado del lector: detección y notificación de errores:

import csv, sys
filename ='some.csv'withopen(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 aunque el módulo no admite directamente el análisis de cadenas, se puede hacer fácilmente:

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

Notas al pie

1(1,2)

Si newline='' no se especifica, las nuevas líneas incrustadas dentro de los campos entre comillas no se interpretarán correctamente y en las plataformas que utilizan rn ropa en escribir un extra r será añadido. Siempre debe ser seguro especificar newline='', ya que el módulo csv hace lo suyo (universal) manejo de nueva línea.