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 можно использовать для переопределения отдельных параметров форматирования текущего диалекта. Полное описание диалектов и параметров форматирования приведено в разделе Диалекты и параметры форматирования. Чтобы упростить взаимодействие с модулями, реализующими 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)

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

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

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

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

Изменено в версии 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 ключей, определяющих порядок записи в файл f значений из словаря, переданного методу writerow(). Необязательный параметр restval задаёт значение, записываемое в случае, если в словаре отсутствует ключ из fieldnames. Если словарь, переданный методу writerow(), содержит ключ, отсутствующий в fieldnames, необязательный параметр extrasaction определяет дальнейшее действие. Если задано значение 'raise' (по умолчанию), возникает исключение ValueError. Если задано значение 'ignore', лишние значения в словаре игнорируются. Все остальные необязательные или именованные аргументы передаются базовому экземпляру writer.

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

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

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)

Анализирует указанный 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 заключать в кавычки все нечисловые поля.

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

csv.QUOTE_NONE

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

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

Модуль 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

Односимвольная строка, используемая объектом записи для экранирования 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, при некорректных входных данных CSV возникает исключение Error. По умолчанию задано значение 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)

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

Несколько более сложный пример использования reader — перехват ошибок и вывод сообщений о них:

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)

Сноски