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

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

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

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

Возвращает объект-чтец, который будет итерироваться по строкам в заданном файле csvfile. csvfile может быть любым объектом, поддерживающим протокол итератор, и возвращающим строку каждый раз, когда вызывается его метод __next__() — объекты файлов и списки подходят. Если csvfile — это объект файла, он должен быть открыт с помощью newline=''. 1 Можно указать необязательный параметр диалект, который используется для определения набора параметров, специфичных для конкретного диалекта 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. Можно указать необязательный параметр диалект, который используется для определения набора параметров, специфичных для конкретного диалекта 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, или с помощью ключевых аргументов fmtparams, или то и другое, причём ключевые аргументы переопределяют параметры диалекта. Более подробную информацию о диалектах и параметрах форматирования см. в разделе Диалекты и параметры форматирования.

csv.unregister_dialect(name)

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

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

Если строка имеет больше полей, чем имён полей, оставшиеся данные помещаются в список и хранятся с именем поля, указанным в restkey (по умолчанию None). Если в непустой строке меньше полей, чем имён полей, пропущенные значения заполняются значением 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 ключей, которые определяют порядок, в котором значения в словаре, переданном методу writerow(), записываются в файл f. Необязательный параметр 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 определяет обычные свойства файла с разделителями ТАБ, сгенерированного 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, отражающий найденные параметры. Если параметр delimiters задан, он интерпретируется как строка, содержащая возможные допустимые разделители.

has_header(sample)

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

Dialect.lineterminator

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

Примечание

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

Dialect.quotechar

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

csvreader.fieldnames

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

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

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

csvwriter.writerow(row)

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

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

csvwriter.writerows(rows)

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

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

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.getpreferredencoding()). Чтобы декодировать файл с использованием другой кодировки, используйте аргумент 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)

Примечания

1(1,2)

Если newline='' не указан, встроенные в поля с кавычками символы новой строки не будут интерпретироваться правильно, а на платформах, использующих \r\n в качестве разделителя строк при записи, будет добавлен дополнительный \r. Указание newline='' всегда безопасно, так как модуль csv выполняет собственное (универсальное) обработку новых строк.