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.

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

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

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

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

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

Создайте объект, который работает как обычный писатель, но отображает словари в строки вывода. Параметр fieldnames — это sequence ключей, которые определяют порядок, в котором значения в словаре, переданном методу writerow(), записываются в файл f. Необязательный параметр restval задаёт значение, которое должно быть записано, если в словаре отсутствует ключ в fieldnames. Если словарь, переданный методу writerow(), содержит ключ, не найденный в fieldnames, необязательный параметр extrasaction указывает, какое действие предпринять. Если он установлен в значение 'raise', по умолчанию, генерируется ValueError. Если он установлен в значение 'ignore', дополнительные значения в словаре игнорируются. Любые другие необязательные или ключевые параметры передаются в базовый экземпляр writer.

Обратите внимание, что в отличие от класса DictReader, параметр fieldnames класса DictWriter не является необязательным. Поскольку объекты Python dict не упорядочены, нет достаточной информации, чтобы определить порядок записи строки в файл f.

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

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

Пример использования 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

Возникает в любой из функций, когда обнаружена ошибка.

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

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

Dialect.strict

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

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

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

csvreader.__next__()

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

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

csvreader.dialect

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

csvreader.line_num

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

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

csvreader.fieldnames

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

14.1.4. Объекты-писатели

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

csvwriter.writerow(row)

Записывает параметр строка в объект файла писателя, отформатированный в соответствии с текущим диалектом.

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

csvwriter.writerows(rows)

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

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

csvwriter.dialect

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

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

DictWriter.writeheader()

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

Введено в версии 3.2.

14.1.5. Примеры

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

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