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

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

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

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

Возвращает объект объект-читатель, который будет обрабатывать строки из заданного csvfile. csvfile должен быть итерируемым объектом строк, каждая из которых имеет формат CSV, определенный читателем. Обычно csvfile — это объект-подобный файлу или список. Если 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 — это 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 — это контейнерный класс, атрибуты которого содержат информацию о том, как обрабатывать двойные кавычки, пробелы, разделители и т. д. Из-за отсутствия строгого спецификации CSV различные приложения производят слегка отличающиеся данные CSV. Экземпляры Dialect определяют поведение экземпляров reader и writer.

Все доступные имена Dialect возвращаются функцией list_dialects(), и они могут быть зарегистрированы со специфичными классами reader и writer через их инициализаторы (__init__) так:

import csv

with open('students.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, dialect='unix')
                                 ^^^^^^^^^^^^^^

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

has_header(sample)

Проанализируйте образец текста (предполагается, что он имеет формат CSV) и верните True, если первая строка, по-видимому, представляет собой серию заголовков столбцов. При проверке каждого столбца будет рассматриваться один из двух ключевых критериев для оценки, содержит ли образец заголовок:

• строки со второй по n-ю содержат числовые значения
• строки со второй по n-ю содержат строки, где длина по крайней мере одного значения отличается от длины предполагаемого заголовка этого столбца.

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

Изменено в версии 3.11: Пустой escapechar не допускается.

Dialect.lineterminator

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

Примечание

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

Dialect.quotechar

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

Изменено в версии 3.11: Пустой quotechar не допускается.

Dialect.quoting

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

Dialect.skipinitialspace

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

Dialect.strict

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

Объекты чтения

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

csvreader.__next__()

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

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

csvreader.dialect

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

csvreader.line_num

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

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

DictReader.fieldnames

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

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

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

csvwriter.writerow(row)

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

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

csvwriter.writerows(rows)

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

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

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