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.

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

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

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

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

Возвращает объект-писатель, ответственный за преобразование данных пользователя в разделительные строки в указанном файлоподобном объекте. csvfile может быть любым объектом с методом write(). Если csvfile — это объект файла, он должен быть открыт с помощью newline='' [1]. В качестве необязательного параметра можно указать dialect, который используется для определения набора параметров, специфичных для определённого диалекта 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 с name. name должно быть строкой. Диалект можно указать, передав подкласс 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(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

Создаёт объект, который работает как обычный читатель, но отображает считанную информацию в словарь, ключами которого являются значения, заданные необязательным параметром fieldnames. Параметр fieldnames — это sequence, элементы которого связаны с полями входных данных в порядке. Эти элементы становятся ключами результирующего словаря. Если параметр fieldnames опущен, значения в первой строке csvfile будут использоваться в качестве имён полей. Если прочитанная строка содержит больше полей, чем последовательность имён полей, оставшиеся данные добавляются как последовательность, имеющая ключ, заданный значением restkey. Если прочитанная строка содержит меньше полей, чем последовательность имён полей, оставшиеся ключи принимают значение необязательного параметра restval. Любые другие необязательные или ключевые аргументы передаются в лежащий в основе объект reader.

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

>>> import csv
>>> with open('names.csv') as csvfile:
...     reader = csv.DictReader(csvfile)
...     for row in reader:
...         print(row['first_name'], row['last_name'])
...
Baked Beans
Lovely Spam
Wonderful Spam

class csv.DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

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

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

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

import csv

with open('names.csv', 'w') 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)

Анализирует предоставленный образец и возвращает подкласс Dialect, отражающий найденные параметры. Если задан необязательный параметр delimiters, он интерпретируется как строка, содержащая возможные допустимые разделители.

has_header(sample)

Анализирует образец текста (предполагается, что он в формате CSV) и возвращает True, если первая строка, по-видимому, представляет собой набор заголовков столбцов.

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

with open('example.csv') 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

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

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, пробелы сразу после delimiter игнорируются. По умолчанию False.

Dialect.strict

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

3. Объекты читателя

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

csvreader.__next__()

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

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

csvreader.dialect

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

csvreader.line_num

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

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

csvreader.fieldnames

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

4. Объекты Writer

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

csvwriter.writerow(row)

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

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

csvwriter.writerows(rows)

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

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

csvwriter.dialect

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

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

DictWriter.writeheader()

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

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

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)

Примечания