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 — это 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)

Проанализируйте предоставленный пример и верните подкласс 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)
    # ... 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.

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

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, что отключает экранирование.

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), обработанные в соответствии с текущим 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)

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

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

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)

То же самое относится к записи в кодировке, отличной от системной по умолчанию: укажите аргумент 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)

Примечания

1(1,2)

Если newline='' не указано, новые строки, встроенные внутри цитируемых полей, не будут интерпретироваться правильно, и на платформах, использующих \r\n окончания строк при записи, будет добавлена дополнительная \r . Всегда безопасно указывать newline='', так как модуль csv выполняет свою собственную (универсальную) обработку новых строк.