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

Односимвольная строка, используемая писателем для экранирования разделителя, если цитирование установлено в 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)

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

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