csv — Чтение и запись CSV-файлов

Содержание модуля

Модуль csv определяет следующие функции:

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

Возвращает объект объекта-чтеца, который будет обрабатывать строки из заданного csvfile. csvfile должен быть итерируемым объектом строк, каждая из которых соответствует определённому формату CSV. Чаще всего csvfile представляет собой объект, подобный файлу, или список. Если csvfile является объектом файла, он должен быть открыт с помощью newline=''. [1] В качестве необязательного параметра можно передать dialect, который используется для определения набора параметров, специфичных для конкретного диалекта CSV. Он может быть экземпляром подкласса класса Dialect или одной из строк, возвращаемых функцией list_dialects(). Другие необязательные ключевые аргументы fmtparams могут быть переданы для переопределения отдельных параметров форматирования в текущем диалекте. Полные сведения о диалектах и параметрах форматирования см. в разделе Диалекты и параметры форматирования.

Каждая строка, считанная из файла CSV, возвращается в виде списка строк. Автоматическое преобразование типов данных не выполняется, если не задан параметр QUOTE_NONNUMERIC (в этом случае нецитируемые поля преобразуются в числа с плавающей точкой).

Пример краткого использования:

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

Возвращает объект-писатель, ответственный за преобразование данных пользователя в разделительные строки в заданном объекте, подобном файлу. csvfile может быть любым объектом с методом write(). Если csvfile является объектом файла, он должен быть открыт с помощью newline='' [1]. Необязательный параметр dialect может быть передан, чтобы определить набор параметров, специфичных для конкретного диалекта CSV. Он может быть экземпляром подкласса класса Dialect или одной из строк, возвращаемых функцией list_dialects(). Другие необязательные ключевые аргументы fmtparams могут быть переданы для переопределения отдельных параметров форматирования в текущем диалекте. Для получения полной информации о диалектах и параметрах форматирования см. раздел Диалекты и параметры форматирования. Чтобы максимально упростить взаимодействие с модулями, которые реализуют API базы данных, значение None записывается как пустая строка. Хотя это не является обратимым преобразованием, это упрощает выгрузку данных SQL NULL в файлы CSV без предварительной обработки данных, возвращаемых вызовом cursor.fetch*. Все другие данные, не являющиеся строками, строятся с помощью str() перед записью.

Пример краткого использования:

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

Связывает dialect со значением name. name должен быть строкой. Диалект может быть задан путём передачи подкласса Dialect, или посредством ключевых аргументов fmtparams, или и тем, и другим, причём ключевые аргументы переопределяют параметры диалекта. Для получения полной информации о диалектах и параметрах форматирования см. раздел Диалекты и параметры форматирования.

csv.unregister_dialect(name)

Удаляет диалект, связанный с name, из реестра диалектов. Возникает ошибка Error, если name не является зарегистрированным именем диалекта.

csv.get_dialect(name)

Возвращает диалект, связанный с name. Возникает ошибка Error, если name не является зарегистрированным именем диалекта. Эта функция возвращает неизменяемый объект Dialect.

csv.list_dialects()

Возвращает имена всех зарегистрированных диалектов.

csv.field_size_limit([new_limit])

Возвращает текущий максимальный размер поля, разрешённый анализатором. Если задан new_limit, этот предел меняется.

Модуль csv определяет следующие классы:

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

Создаёт объект, работающий подобно обычному читателю, но отображает информацию в каждой строке в словарь dict с ключами, заданными необязательным параметром fieldnames.

Параметр fieldnames — это последовательность. Если fieldnames опущен, значения в первой строке файла f будут использованы в качестве имён полей и будут исключены из результатов. Если fieldnames задан, они будут использованы, и первая строка будет включена в результаты. Независимо от того, как определяются имена полей, словарь сохраняет их исходный порядок.

Если строка имеет больше полей, чем имён полей, оставшиеся данные помещаются в список и сохраняются с именем поля, заданным параметром restkey (по умолчанию None). Если непустая строка имеет меньше полей, чем имён полей, отсутствующие значения заполняются значением restval (по умолчанию None).

Все остальные необязательные или ключевые аргументы передаются в базовый объект reader.

Если аргумент, переданный в fieldnames, является итератором, он будет преобразован в list.

Изменено в версии 3.6: Возвращаемые строки теперь имеют тип OrderedDict.

Изменено в версии 3.8: Возвращаемые строки теперь имеют тип dict.

Пример краткого использования:

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

Создаёт объект, работающий подобно обычному писателю, но отображает словари в выходные строки. Параметр fieldnames — это sequence ключей, которые определяют порядок записи значений из словаря, переданного методу writerow(), в файл f. Необязательный параметр restval задаёт значение, которое должно быть записано, если в словаре отсутствует ключ в fieldnames. Если словарь, переданный методу writerow(), содержит ключ, не найденный в fieldnames, необязательный параметр extrasaction указывает, какое действие следует предпринять. Если он установлен в значение 'raise', по умолчанию, возникает ValueError. Если он установлен в значение 'ignore', дополнительные значения в словаре игнорируются. Любые другие необязательные или ключевые аргументы передаются в базовый объект writer.

Обратите внимание, что в отличие от класса DictReader, параметр fieldnames класса DictWriter не является необязательным.

Если аргумент, переданный в fieldnames, является итератором, он будет преобразован в list.

Пример краткого использования:

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

Класс Dialect — это контейнерный класс, чьи атрибуты содержат информацию о том, как обрабатывать двойные кавычки, пробелы, разделители и т. д. Из-за отсутствия строгого спецификации CSV разные приложения создают несколько отличающиеся данные CSV. Экземпляры Dialect определяют, как ведут себя объекты reader и writer.

Все доступные имена Dialect возвращаются функцией list_dialects(), и их можно зарегистрировать с помощью конкретных классов reader и writer через их инициализаторы (__init__) следующим образом:

import csv

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

class csv.excel

Класс excel определяет обычные свойства файла CSV, сгенерированного из Excel. Он зарегистрирован с именем диалекта 'excel'.

class csv.excel_tab

Класс excel_tab определяет обычные свойства файла с разделителем TAB, сгенерированного из Excel. Он зарегистрирован с именем диалекта 'excel-tab'.

class csv.unix_dialect

Класс unix_dialect определяет обычные свойства файла CSV, сгенерированного на системах UNIX, то есть использующего '\n' в качестве разделителя строк и заключающего все поля в кавычки. Он зарегистрирован с именем диалекта 'unix'.

Добавлен в версии 3.2.

class csv.Sniffer

Класс Sniffer используется для определения формата файла CSV.

Класс Sniffer предоставляет два метода:

sniff(sample, delimiters=None)

Проанализируйте предоставленный образец и верните подкласс Dialect, отражающий обнаруженные параметры. Если параметр разделители указан, он интерпретируется как строка, содержащая возможные допустимые символы разделителей.

has_header(sample)

Проанализируйте образец текста (предполагаемый в формате CSV) и верните True, если первая строка, похоже, представляет собой набор заголовков столбцов. При осмотре каждого столбца будет рассмотрено одно из двух ключевых критериев для оценки, содержит ли образец заголовок:

• строки со второй по n-ю содержат числовые значения
• строки со второй по n-ю содержат строки, где длина по крайней мере одного значения отличается от предполагаемого заголовка этого столбца.

Образцы берутся из двадцати строк после первой строки; если более половины столбцов + строк соответствуют критериям, возвращается True.

Примечание

Этот метод является приблизительным эвристическим методом и может давать как ложноположительные, так и ложноотрицательные результаты.

Пример использования 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 ...

В модуле csv определены следующие константы:

csv.QUOTE_ALL

Указывает объектам writer заключать в кавычки все поля.

csv.QUOTE_MINIMAL

Указывает объектам writer заключать в кавычки только те поля, которые содержат специальные символы, такие как разделитель, quotechar или любые символы в lineterminator.

csv.QUOTE_NONNUMERIC

Указывает объектам writer заключать в кавычки все нечисловые поля.

Указывает объектам reader преобразовывать все нецитируемые поля в тип float.

csv.QUOTE_NONE

Указывает объектам writer никогда не заключать поля в кавычки. Когда текущий разделитель встречается в выходных данных, ему предшествует текущий символ escapechar. Если escapechar не задан, писатель вызовет Error, если встретятся какие-либо символы, требующие экранирования.

Указывает объектам reader не выполнять специальной обработки символов кавычек.

csv.QUOTE_NOTNULL

Указывает объектам writer заключать в кавычки все поля, которые не являются None. Это аналогично QUOTE_ALL, за исключением того, что если значение поля равно None, записывается пустая (нецитируемая) строка.

Указывает объектам reader интерпретировать пустое (нецитируемое) поле как None и в противном случае вести себя как QUOTE_ALL.

Добавлен в версии 3.12.

csv.QUOTE_STRINGS

Указывает объектам writer всегда заключать в кавычки поля, которые являются строками. Это аналогично QUOTE_NONNUMERIC, за исключением того, что если значение поля равно None, записывается пустая (нецитируемая) строка.

Указывает объектам reader интерпретировать пустую (нецитируемую) строку как None и в противном случае вести себя как QUOTE_NONNUMERIC.

Добавлен в версии 3.12.

В модуле csv определена следующая исключительная ситуация:

exception csv.Error

Возникает при обнаружении ошибки в любой из функций.

Диалекты и параметры форматирования

Для упрощения указания формата входных и выходных записей, конкретные параметры форматирования сгруппированы в диалекты. Диалект — это подкласс класса Dialect, содержащий различные атрибуты, описывающие формат файла CSV. При создании объектов reader или writer, программист может указать строку или подкласс класса Dialect в качестве параметра диалекта. В дополнение к или вместо параметра dialect, программист также может указать отдельные параметры форматирования, имеющие те же имена, что и атрибуты, определённые ниже для класса Dialect.

Диалекты поддерживают следующие атрибуты:

Dialect.delimiter

Строка длиной в один символ, используемая для разделения полей. По умолчанию равно ','.

Dialect.doublequote

Управляет тем, как экземпляры quotechar, появляющиеся внутри поля, должны быть сами обрамлены кавычками. Если значение равно True, символ дублируется. Если значение равно False, используется escapechar как префикс к quotechar. По умолчанию равно True.

При выводе, если doublequote равно False, а escapechar не задан, возникает ошибка Error, если quotechar найден в поле.

Dialect.escapechar

Односимвольная строка, используемая записывателем для экранирования разделителя delimiter, если quoting установлено в QUOTE_NONE, и quotechar, если doublequote равно False. При чтении escapechar удаляет любое специальное значение из последующего символа. По умолчанию равно None, что отключает экранирование.

Изменено в версии 3.11: Пустой escapechar не допускается.

Dialect.lineterminator

Строка, используемая для завершения строк, создаваемых объектом writer. По умолчанию равно '\r\n'.

Примечание

Объект reader жёстко запрограммирован для распознавания '\r' или '\n' как конца строки и игнорирует lineterminator. Это поведение может измениться в будущем.

Dialect.quotechar

Односимвольная строка, используемая для кавычек полей, содержащих специальные символы, такие как разделитель delimiter или quotechar, или содержащие символы новой строки. По умолчанию равно '"'.

Изменено в версии 3.11: Пустой quotechar не допускается.

Dialect.quoting

Управляет тем, когда кавычки должны генерироваться записывателем и распознаваться читателем. Может принимать любое из значений констант QUOTE_* и по умолчанию равно QUOTE_MINIMAL.

Dialect.skipinitialspace

Если равно True, пробелы непосредственно после разделителя delimiter игнорируются. По умолчанию равно False.

Dialect.strict

Если равно True, генерирует исключение Error при некорректном входном CSV. По умолчанию равно False.

Объекты-читатели

Объекты-читатели (DictReader экземпляры и объекты, возвращаемые функцией reader()) имеют следующие публичные методы:

csvreader.__next__()

Возвращает следующую строку итерируемого объекта-читателя в виде списка (если объект возвращён функцией reader()) или словаря (если это экземпляр DictReader), разобранных в соответствии с текущим диалектом Dialect. Обычно вы должны вызывать это как next(reader).

Объекты-читатели имеют следующие публичные атрибуты:

csvreader.dialect

Только для чтения описание диалекта, используемого парсером.

csvreader.line_num

Количество строк, прочитанных из источника-итератора. Это не то же самое, что количество записей, возвращённых, так как записи могут охватывать несколько строк.

Объекты DictReader имеют следующий публичный атрибут:

DictReader.fieldnames

Если не был передан в качестве параметра при создании объекта, этот атрибут инициализируется при первом обращении к нему или при первом чтении записи из файла.

Объекты-записыватели

Объекты writer (DictWriter экземпляры и объекты, возвращаемые функцией writer()) имеют следующие публичные методы. row должен быть итерируемым объектом строк или чисел для объектов writer и словарем, сопоставляющим имена полей со строками или числами (сначала передавая их через str()) для объектов DictWriter. Обратите внимание, что комплексные числа выводятся в скобках. Это может вызвать некоторые проблемы для других программ, которые читают файлы CSV (если они вообще поддерживают комплексные числа).

csvwriter.writerow(row)

Записывает параметр row в файл-объект записывателя, отформатированный в соответствии с текущим диалектом Dialect. Возвращает значение, возвращённое методом write базового объекта файла.

Изменено в версии 3.5: Добавлена поддержка произвольных итерируемых объектов.

csvwriter.writerows(rows)

Записывает все элементы в rows (итерируемый объект объектов row, как описано выше) в файл-объект записывателя, отформатированный в соответствии с текущим диалектом.

Объекты-записыватели имеют следующий публичный атрибут:

csvwriter.dialect

Только для чтения описание диалекта, используемого записывателем.

Объекты DictWriter имеют следующий публичный метод:

DictWriter.writeheader()

Записывает строку с именами полей (как указано в конструкторе) в файл-объект записывателя, отформатированный в соответствии с текущим диалектом. Возвращает значение, возвращённое вызовом csvwriter.writerow(), используемым внутри.

Добавлен в версии 3.2.

Изменено в версии 3.8: writeheader() теперь также возвращает значение, возвращённое методом csvwriter.writerow(), который он использует внутри.

Примеры

Простейший пример чтения файла CSV:

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

Чтение файла с альтернативным форматом:

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

Соответствующий простейший пример записи:

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

Поскольку open() используется для открытия файла CSV для чтения, файл по умолчанию будет декодирован в unicode с использованием кодировки по умолчанию системы (см. locale.getencoding()). Чтобы декодировать файл с использованием другой кодировки, используйте аргумент encoding функции open:

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

То же самое относится к записи, если нужно использовать кодировку, отличную от системной по умолчанию: укажите аргумент encoding при открытии выходного файла.

Регистрация нового диалекта:

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

Несколько более продвинутое использование чтения — перехват и обработка ошибок:

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

И хотя модуль напрямую не поддерживает парсинг строк, это легко сделать:

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

Примечания