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='excel', **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()

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 указан, будут использованы заданные имена, а первая строка войдёт в результаты. Независимо от того, как определены имена полей, словарь сохраняет их исходный порядок.

Если в строке больше полей, чем указано в 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)

Создаёт объект, работающий подобно обычному средству записи, но преобразующий словари в выходные строки. Параметр 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, '\r', '\n' или любой из символов в lineterminator.

csv.QUOTE_NONNUMERIC

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

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

Примечание

Некоторые числовые типы, например bool, Fraction или IntEnum, имеют строковое представление, которое нельзя преобразовать в float. Их нельзя прочитать в режимах QUOTE_NONNUMERIC и QUOTE_STRINGS.

csv.QUOTE_NONE

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

Указывает объектам 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

Односимвольная строка, используемая средством записи для экранирования символов, которые требуют экранирования:

• delimiter, quotechar, '\r', '\n' и все символы в lineterminator экранируются, если для quoting задано значение QUOTE_NONE;
• quotechar экранируется, если doublequote равно False;
• сам escapechar.

При чтении escapechar отменяет специальное значение следующего за ним символа. По умолчанию задано значение None, отключающее экранирование.

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

Dialect.lineterminator

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

Примечание

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

Dialect.quotechar

Односимвольная строка, используемая для заключения в кавычки полей, содержащих специальные символы, например delimiter или quotechar, либо символы новой строки ('\r', '\n' или любой из символов в lineterminator). По умолчанию '"'. Может быть задано значение None, чтобы отключить экранирование '"', если для quoting задано значение QUOTE_NONE.

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

Dialect.quoting

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

Dialect.skipinitialspace

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

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

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

csvwriter.writerow(row, /)

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

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

csvwriter.writerows(rows, /)

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

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

csvwriter.dialect

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

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

DictWriter.writeheader()

Записывает строку с именами полей (указанными в конструкторе) в файловый объект writer, форматируя её в соответствии с текущим диалектом. Возвращает значение, полученное при внутреннем вызове 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(f'file {filename}, line {reader.line_num}: {e}')

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

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

Сноски