# `csv` — CSV File Reading and Writing

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.

The `csv` module implements classes to read and write tabular data in CSV format. It allows programmers to say, «write this data in the format preferred by Excel,» or «read data from this file which was generated by Excel,» without knowing the precise details of the CSV format used by Excel. Programmers can also describe the CSV formats understood by other applications or define their own special-purpose CSV formats.

The `csv` module’s `reader` and `writer` objects read and write sequences. Programmers can also read and write data in dictionary form using the `DictReader` and `DictWriter` classes.

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

The `csv` module defines the following functions:

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.

  Each row read from the csv file is returned as a list of strings. No automatic data type conversion is performed unless the `QUOTE_NONNUMERIC` format option is specified (in which case unquoted fields are transformed into floats).

  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

  where `eggs.csv` contains:

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

  which writes `eggs.csv` containing:

      Spam Spam Spam Spam Spam |Baked Beans|
      Spam |Lovely Spam| |Wonderful Spam|

csv.register_dialect(name, /, dialect='excel', **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()
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.

The `csv` module defines the following classes:

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.

  The fieldnames parameter is a sequence. If fieldnames is omitted, the values in the first row of file f will be used as the fieldnames and will be omitted from the results. If fieldnames is provided, they will be used and the first row will be included in the results. Regardless of how the fieldnames are determined, the dictionary preserves their original ordering.

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

  where `names.csv` contains:

      first_name,last_name
      Eric,Idle
      John,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'})

  which writes `names.csv` containing:

      first_name,last_name
      Baked,Beans
      Lovely,Spam
      Wonderful,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'`.

  Added in version 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.

    The dialect is deduced by parsing the sample with every plausible combination of parameters and choosing the combination which splits the sample into rows with the most consistent number of fields, so the returned dialect is consistent with how `reader()` will parse the sample. Raise `Error` if no combination fits the sample, in particular if it is a single column, so there is no delimiter to find.

    If several combinations fit the sample equally well — for example if both `','` and `';'` split every row consistently — the delimiters listed in the `preferred` attribute are preferred, in that order, no matter how many times each of them occurs.

    The lineterminator parameter is deduced separately, by a majority vote among the line endings of the sample. A tie is broken in the order `'\r\n'`, `'\n'`, `'\r'`, so a sample without a complete line gives `'\r\n'`.

    Distinto en la versión 3.16.0a0 (unreleased): The dialect is now deduced by trial parsing and the results may differ from those of earlier Python versions. The escapechar and lineterminator parameters can now be detected, and the requested delimiters are not restricted to ASCII.

  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.

    Twenty-one rows after the header are sampled; if more than half of the columns + rows meet the criteria, `True` is returned.

  Nota

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

  The `Sniffer` class has the following attribute:

  preferred

    The list of the delimiters preferred for breaking ties, in the order of preference. It can be modified. Its initial value is `[',', '\t', ';', ' ', ':']`.

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

The `csv` module defines the following constants:

csv.QUOTE_ALL

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

csv.QUOTE_MINIMAL

  Instructs `writer` objects to only quote those fields which contain special characters such as delimiter, quotechar, `'\r'`, `'\n'` or any of the characters in lineterminator. If doublequote is `False` and escapechar is set, the quotechar is escaped instead of causing the field to be quoted.

csv.QUOTE_NONNUMERIC

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

  Instructs `reader` objects to convert all non-quoted fields to type `float`.

  Nota

  Some numeric types, such as `bool`, `Fraction`, or `IntEnum`, have a string representation that cannot be converted to `float`. They cannot be read in the `QUOTE_NONNUMERIC` and `QUOTE_STRINGS` modes.

csv.QUOTE_NONE

  Instructs `writer` objects to never quote fields. When the current delimiter, quotechar, escapechar, `'\r'`, `'\n'` or any of the characters in lineterminator occurs in output data it is preceded by the current escapechar character. If escapechar is not set, the writer will raise `Error` if any characters that require escaping are encountered. Set quotechar to `None` to prevent its escaping.

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

  Instructs `reader` objects to interpret an empty (unquoted) field as `None` and to otherwise behave as `QUOTE_ALL`.

  Added in version 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`.

  Added in version 3.12.

The `csv` module defines the following exception:

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

  A one-character string used by the writer to escape characters that require escaping:

  > - the delimiter, the quotechar, `'\r'`, `'\n'` and any of the characters in lineterminator are escaped if quoting is set to `QUOTE_NONE`;

  > - the quotechar is escaped if doublequote is `False`;

  > - the escapechar itself.

  On reading, the escapechar removes any special meaning from the following character. It defaults to `None`, which disables escaping.

  Distinto en la versión 3.10: Previously the escapechar itself was not escaped, which lost it on reading.

  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

  A one-character string used to quote fields containing special characters, such as the delimiter or the quotechar, or which contain new-line characters (`'\r'`, `'\n'` or any of the characters in lineterminator). It defaults to `'"'`. Can be set to `None` to prevent escaping `'"'` if quoting is set to `QUOTE_NONE`.

  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` if quotechar is not `None`, and `QUOTE_NONE` otherwise.

Dialect.skipinitialspace

  When `True`, spaces immediately following the delimiter are ignored. The default is `False`. When combining `delimiter=' '` with `skipinitialspace=True`, unquoted empty fields are not allowed.

Dialect.strict

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

Dialects support `copy.replace()`, which returns a copy of the dialect with the specified formatting parameters replaced.

Distinto en la versión 3.16.0a0 (unreleased): Added support for `copy.replace()`.

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

  Added in version 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(f'file {filename}, line {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)

If `newline=''` is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use `\r\n` line endings on write an extra `\r` will be added. It should always be safe to specify `newline=''`, since the csv module does its own (universal) newline handling.