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

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

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

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

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

где eggs.csv содержит:

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'])

записывает eggs.csv, содержащий:

Spam Spam Spam Spam Spam |Baked Beans|
Spam |Lovely Spam| |Wonderful Spam|

csv.register_dialect(name, /, dialect='excel', **fmtparams)

Связывает dialect с name. name должен быть строкой. Диалект можно задать, передав подкласс Dialect, именованные аргументы fmtparams или и то и другое; в последнем случае именованные аргументы переопределяют параметры диалекта. Полные сведения о диалектах и параметрах форматирования см. в разделе Диалекты и параметры форматирования.

csv.unregister_dialect(name)

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

csv.get_dialect(name)

Возвращает диалект, связанный с name. Если name не является зарегистрированным именем диалекта, возникает исключение Error. Эта функция возвращает неизменяемый объект Dialect.

csv.list_dialects()

Возвращает имена всех зарегистрированных диалектов.

csv.field_size_limit()

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

Если в строке больше полей, чем имён полей, оставшиеся данные помещаются в список и сохраняются под именем поля, заданным параметром restkey (по умолчанию None). Если непустая строка содержит меньше полей, чем имён полей, отсутствующие значения заполняются значением restval (по умолчанию None).

Все остальные необязательные аргументы и именованные аргументы передаются базовому экземпляру reader.

Если аргумент, переданный в fieldnames, является итератором, он будет преобразован в list.

Изменено в версии 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'}

где names.csv содержит:

first_name,last_name
Eric,Idle
John,Cleese

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

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

Обратите внимание: в отличие от класса DictReader, параметр fieldnames класса DictWriter является обязательным.

Если аргумент, переданный в fieldnames, является итератором, он будет преобразован в list.

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

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'})

записывает names.csv, содержащий:

first_name,last_name
Baked,Beans
Lovely,Spam
Wonderful,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 определяет стандартные свойства файла с разделителями-табуляциями, созданного 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, он интерпретируется как строка, содержащая возможные допустимые символы-разделители.

Если несколько разделителей одинаково хорошо подходят для образца — например, если и ',', и ';' последовательно разделяют каждую строку, — предпочтение отдаётся разделителям, перечисленным в атрибуте preferred, в указанном там порядке, независимо от частоты их появления.

has_header(sample)

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

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

После заголовка анализируются двадцать одна строка; если критериям соответствуют более половины столбцов и строк, возвращается True.

Примечание

Этот метод основан на приблизительной эвристике и может давать как ложноположительные, так и ложноотрицательные результаты.

Класс Sniffer имеет следующий атрибут:

preferred

Список разделителей, используемый для разрешения неоднозначностей, упорядоченный по предпочтительности. Его можно изменить. Начальное значение — [',', '\t', ';', ' ', ':'].

Пример использования 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, '\r', '\n' или любой символ из lineterminator. Если doublequote имеет значение False и задан escapechar, перед quotechar ставится символ экранирования, вместо того чтобы заключать поле в кавычки.

csv.QUOTE_NONNUMERIC

Указывает объектам writer заключать в кавычки все поля, не являющиеся числовыми.

Указывает объектам reader преобразовывать все поля без кавычек к типу float.

Примечание

Некоторые числовые типы, например bool, Fraction или IntEnum, имеют строковое представление, которое нельзя преобразовать в float. Их нельзя прочитать в режимах QUOTE_NONNUMERIC и QUOTE_STRINGS.

csv.QUOTE_NONE

Указывает объектам writer никогда не заключать поля в кавычки. Если в выходных данных встречается текущий delimiter, quotechar, escapechar, '\r', '\n' или любой символ из lineterminator, перед ним ставится текущий символ escapechar. Если escapechar не задан, writer вызовет исключение Error, если встретит символы, требующие экранирования. Задайте для quotechar значение None, чтобы исключить его экранирование.

Указывает объектам reader не выполнять специальную обработку символов кавычек.

csv.QUOTE_NOTNULL

Указывает объектам writer заключать в кавычки все поля, которые не являются None. Это похоже на QUOTE_ALL, за исключением того, что если значение поля равно None, записывается пустая строка без кавычек.

Указывает объектам reader трактовать пустое поле без кавычек как None, а в остальном вести себя как в режиме QUOTE_ALL.

Добавлено в версии 3.12.

csv.QUOTE_STRINGS

Указывает объектам writer всегда заключать в кавычки строковые поля. Это похоже на QUOTE_NONNUMERIC, за исключением того, что если значение поля равно None, записывается пустая строка без кавычек.

Указывает объектам reader трактовать пустую строку без кавычек как None, а в остальном вести себя как в режиме QUOTE_NONNUMERIC.

Добавлено в версии 3.12.

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

exception csv.Error

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

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

Чтобы упростить указание формата входных и выходных записей, соответствующие параметры форматирования объединяются в диалекты. Диалект — это подкласс класса Dialect, содержащий различные атрибуты, описывающие формат CSV-файла. При создании объектов reader или writer программист может указать в качестве параметра диалекта строку или подкласс класса Dialect. Помимо параметра dialect или вместо него программист также может указать отдельные параметры форматирования с теми же именами, что и у атрибутов класса Dialect, описанных ниже.

Диалекты поддерживают следующие атрибуты:

Dialect.delimiter

Односимвольная строка, используемая для разделения полей. По умолчанию — ','.

Dialect.doublequote

Определяет, как следует экранировать символы quotechar, встречающиеся внутри поля. Если значение равно True, символ удваивается. Если значение равно False, перед quotechar ставится escapechar. По умолчанию — True.

При записи, если doublequote имеет значение False и escapechar не задан, при обнаружении quotechar в поле возникает исключение Error.

Dialect.escapechar

Односимвольная строка, используемая writer для экранирования символов, требующих экранирования:

• delimiter, quotechar, '\r', '\n' и любой символ из lineterminator экранируются, если для quoting задано значение QUOTE_NONE;
• quotechar экранируется, если doublequote имеет значение False;
• сам символ escapechar.

При чтении escapechar отменяет специальное значение следующего за ним символа. По умолчанию — None, что отключает экранирование.

Изменено в версии 3.10: Ранее сам символ escapechar не экранировался, из-за чего он терялся при чтении.

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

Dialect.lineterminator

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

Примечание

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

Dialect.quotechar

Односимвольная строка, используемая для заключения в кавычки полей со специальными символами, такими как delimiter или quotechar, а также полей, содержащих символы новой строки ('\r', '\n' или любой символ из lineterminator). По умолчанию — '"'. Можно задать значение None, чтобы запретить экранирование '"', если для quoting установлено значение QUOTE_NONE.

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

Dialect.quoting

Определяет, когда writer должен добавлять кавычки, а reader — распознавать их. Может принимать любое из значений констант QUOTE_*. Если quotechar не равен None, по умолчанию используется QUOTE_MINIMAL, в противном случае — QUOTE_NONE.

Dialect.skipinitialspace

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

Dialect.strict

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

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

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

csvreader.__next__()

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

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

csvreader.dialect

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

csvreader.line_num

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

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

DictReader.fieldnames

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

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

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

csvwriter.writerow(row, /)

Записывает параметр 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)

То же относится к записи с использованием кодировки, отличной от системной по умолчанию: укажите аргумент 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(f'file {filename}, line {reader.line_num}: {e}')

Хотя модуль напрямую не поддерживает разбор строк, это можно легко сделать:

import csv
for row in csv.reader(['one,two,three']):
    print(row)

Сноски