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

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

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

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

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

См.также

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

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

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

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

Возвращает объект reader, который будет итерироваться по строкам в предоставленном csvfile. csvfile может быть любым объектом, который поддерживает протокол итератор и возвращает строку каждый раз, когда вызывается метод __next__() файлового объекта или объекта списка. Если 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)

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

csv.unregister_dialect(name)

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

csv.get_dialect(name)

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

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

class csv.excel_tab

Класс excel_tab определяет обычные свойства произведенного Excel разделённого TAB’ами файла. Он зарегистрирован с именем диалекта '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, если перая строка, кажется, стокой заголовков колонки.

Пример использования Sniffer:

with open('example.csv', newline='') as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... обработка CSV файла содержащегося здесь ...

Модуль 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 определяет следующее исключение:

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

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

Dialect.lineterminator

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

Примечание

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

Dialect.quotechar

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

Dialect.quoting

Контролирует, когда кавычки должны генерироваться writer и распознаваться reader. Он может принимать любые константы QUOTE_* (см. раздел Содержание модуля) и по умолчанию имеет значение QUOTE_MINIMAL.

Dialect.skipinitialspace

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

Dialect.strict

Когда True, поднимает исключение Error на плохом входном CSV. По умолчанию - False.

Объекты Reader

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

csvreader.__next__()

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

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

csvreader.dialect

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

csvreader.line_num

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

У объектов DictReader есть следующий публичный атрибут:

csvreader.fieldnames

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

Writer объекты

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

csvwriter.writerow(row)

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

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

csvwriter.writerows(rows)

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

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

csvwriter.dialect

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

У объектов 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)

Соответствуюobq простейший пример записи:

import csv
with open('some.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)

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