csv – чтение и запись CSV-файлов¶csv – CSV File Reading and Writing

Содержимое модуля¶Module Contents

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

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

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

Возвращает объект 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'])

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(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)¶

Создает объект, который работает как обычный reader, но сопоставляет информацию из каждой строки с 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)¶

Создаёт объект, который работает как обычный writer, но отображает словари на выходные строки. Параметр 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 определяет обычные свойства файла с разделителями табуляции, созданного в 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, если первая строка выглядит как набор заголовков столбцов. При проверке каждого столбца учитывается один из двух ключевых критериев для оценки, содержит ли образец заголовок:

• со второй по 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)
    # ... здесь обрабатывается содержимое CSV-файла ...

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

csv.QUOTE_ALL¶

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

csv.QUOTE_MINIMAL¶

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

csv.QUOTE_NONNUMERIC¶

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

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

csv.QUOTE_NONE¶

Указывает объектам writer никогда не заключать поля в кавычки. Если текущий разделитель встречается в выходных данных, перед ним ставится текущий символ escapechar. Если escapechar не задан, объект writer вызовет Error, если встретятся символы, требующие экранирования.

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

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

exception csv.Error¶

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

Диалекты и параметры форматирования¶Dialects and Formatting Parameters

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

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

Dialect.delimiter¶

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

Dialect.doublequote¶

Управляет тем, как должны заключаться в кавычки экземпляры quotechar, встречающиеся внутри поля. Когда True, символ удваивается. Когда False, escapechar используется в качестве префикса для quotechar. По умолчанию True.

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

Dialect.escapechar¶

Односимвольная строка, используемая объектом writer для экранирования разделителя, если для quoting установлено значение QUOTE_NONE, и quotechar, если doublequote равно False. При чтении escapechar снимает особое значение со следующего символа. По умолчанию None, что отключает экранирование.

Dialect.lineterminator¶

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

Примечание

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

Dialect.quotechar¶

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

Dialect.quoting¶

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

Dialect.skipinitialspace¶

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

Dialect.strict¶

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

Объекты Reader¶Reader Objects

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

csvreader.__next__()¶

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

Объекты reader имеют следующие открытые атрибуты:

csvreader.dialect¶

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

csvreader.line_num¶

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

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

DictReader.fieldnames¶

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

Объекты Writer¶Writer Objects

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

csvwriter.writerow(row)¶

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

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

csvwriter.writerows(rows)¶

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

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

csvwriter.dialect¶

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

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

DictWriter.writeheader()¶

Записывает строку с именами полей (как указано в конструкторе) в файловый объекта средства записи, форматируя в соответствии с текущим диалектом. Возвращает значение, возвращённое внутренним вызовом csvwriter.writerow().

Новое в версии 3.2.

Изменено в версии 3.8: writeheader() теперь также возвращает значение, возвращаемое используемым внутренне методом csvwriter.writerow().

Примеры¶Examples

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

Поскольку open() используется для открытия CSV-файла для чтения, файл по умолчанию будет декодирован в 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')

Чуть более продвинутое использование reader – перехват и сообщение об ошибках:

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