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

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

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

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

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

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

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

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

Возвращает объект writer, который преобразует данные пользователя в строки с разделителями и записывает их в заданный файловый объект. csvfile может быть любым объектом с методом write(). Если csvfile является файловым объектом, его следует открыть с помощью newline='' [1]. Необязательный параметр dialect позволяет задать набор параметров, характерных для определённого диалекта CSV. Это может быть экземпляр подкласса класса Dialect или одна из строк, возвращаемых функцией list_dialects(). Другие необязательные именованные аргументы fmtparams позволяют переопределить отдельные параметры форматирования текущего диалекта. Полное описание диалектов и параметров форматирования см. в разделе Диалекты и параметры форматирования. Чтобы упростить взаимодействие с модулями, реализующими DB 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. Если name не является зарегистрированным именем диалекта, возникает исключение Error.

csv.get_dialect(name)

Возвращает диалект, связанный с именем name. Если name не является зарегистрированным именем диалекта, возникает исключение Error. Эта функция возвращает неизменяемый экземпляр 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)

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

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

Если в строке больше полей, чем имён в fieldnames, оставшиеся данные помещаются в список и сохраняются под именем поля, заданным параметром restkey (по умолчанию None). Если в непустой строке меньше полей, чем имён в fieldnames, отсутствующие значения заполняются значением 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)

Создаёт объект, работающий как обычный writer, но преобразующий словари в выходные строки. Параметр 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 определяет обычные свойства файла с разделителями-табуляциями, созданного 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)

Анализирует заданный sample и возвращает подкласс Dialect, отражающий обнаруженные параметры. Если задан необязательный параметр delimiters, он интерпретируется как строка, содержащая возможные допустимые символы-разделители.

has_header(sample)

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

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

Проверяются двадцать строк после первой; если критериям соответствуют более половины столбцов и строк, возвращается 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 заключать в кавычки только поля, содержащие специальные символы, такие как delimiter, quotechar или любой из символов в lineterminator.

csv.QUOTE_NONNUMERIC

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

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

csv.QUOTE_NONE

Указывает объектам writer никогда не заключать поля в кавычки. Если текущий delimiter встречается в выходных данных, перед ним добавляется текущий символ escapechar. Если escapechar не задан, writer вызовет исключение 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, перед quotechar ставится escapechar. По умолчанию True.

При выводе, если doublequote равен False и escapechar не задан, при обнаружении в поле символа quotechar возникает исключение Error.

Dialect.escapechar

Односимвольная строка, используемая writer для экранирования 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

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

Dialect.skipinitialspace

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

Dialect.strict

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

Объекты reader

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

csvreader.__next__()

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

Объекты 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)

Поскольку для открытия CSV-файла на чтение используется open(), по умолчанию файл будет декодирован в Юникод с использованием системной кодировки (см. 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)

Сноски