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

Исходный код: Lib/csv.py

Формат CSV (Comma Separated Values) — это наиболее распространённый формат импорта и экспорта для электронных таблиц и баз данных. Формат CSV использовался на протяжении многих лет до попыток описать его в стандартизированном виде в RFC 4180. Отсутствие хорошо определенного стандарта означает, что часто существуют небольшие различия в данных, производимых и потребляемых различными приложениями. Эти различия могут затруднять обработку файлов CSV из нескольких источников. Тем не менее, хотя разделители и символы кавычек различаются, общий формат достаточно похож, чтобы можно было написать один модуль, который может эффективно обрабатывать такие данные, скрывая от программиста детали чтения и записи данных.

Модуль csv реализует классы для чтения и записи табличных данных в формате CSV. Он позволяет программистам сказать: «запишите эти данные в формате, предпочтительном для Excel», или «прочитайте данные из этого файла, который был сгенерирован в Excel», не зная точных деталей используемого формата CSV в Excel. Программисты также могут описать форматы CSV, понимаемые другими приложениями, или определить свои собственные форматы CSV для специальных целей.

Модуль csv объекты reader и writer читают и записывают последовательности. Программисты также могут читать и записывать данные в виде словарей, используя классы DictReader и DictWriter.

См. также

PEP 305 — API файлов CSV: Предложение по улучшению Python, которое предложило это дополнение к Python.

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

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

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

Возвращает объект reader, который будет перебирать строки в заданном 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)

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

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

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

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

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

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

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

>>> 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)
OrderedDict([('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 не является необязательным.

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

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

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

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

csv.QUOTE_NONNUMERIC

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

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

csv.QUOTE_NONE

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

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

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

exception csv.Error: Выбрасывается любыми функциями при обнаружении ошибки.

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

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

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

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

Dialect.doublequote

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

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

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

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

Примечание

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

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

Dialect.quoting: Управляет тем, когда писатель должен генерировать кавычки, а читатель должен их распознавать. Может принимать любые из констант QUOTE_* (см. раздел Содержание модуля) и по умолчанию имеет значение QUOTE_MINIMAL.

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

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

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

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

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

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

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

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

Объекты DictReader имеют следующие открытые атрибуты:

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

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

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

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

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

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

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

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

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

DictWriter.writeheader(): Записать строку с именами полей (как указано в конструкторе).

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

Примеры

Самый простой пример чтения 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.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)

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

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

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 выполняет свою собственную (универсальную) обработку новых строк.