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

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

Модуль 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, из реестра диалектов. Возникает исключение Error, если name не является зарегистрированным именем диалекта.

csv.get_dialect(name)¶

Возвращает диалект, связанный с name. Возникает исключение Error, если name не является зарегистрированным именем диалекта. Эта функция возвращает неизменяемый 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 ключей, определяющих порядок, в котором значения из словаря, переданного методу writerow(), записываются в файл f. Необязательный параметр 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, он интерпретируется как строка, содержащая возможные допустимые символы-разделители.

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 заключать в кавычки только те поля, которые содержат специальные символы, такие как разделитель, символ кавычек, '\r', '\n' или любой из символов в терминаторе строки.

csv.QUOTE_NONNUMERIC¶

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

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

Примечание

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

csv.QUOTE_NONE¶

Указывает объектам writer никогда не заключать поля в кавычки. Если текущие разделитель, символ кавычек, символ экранирования, '\r', '\n' или любой из символов в терминаторе строки встречаются в выходных данных, они предваряются текущим символом escapechar. Если escapechar не задан, записывающий объект возбудит исключение Error, если будут обнаружены символы, требующие экранирования. Установите символ кавычек в 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¶

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

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

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

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

Dialect.delimiter¶

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

Dialect.doublequote¶

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

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

Dialect.escapechar¶

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

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

• символ quotechar экранируется, если doublequote равен False;

• сам символ escapechar.

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

Изменено в версии 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_* и по умолчанию равен QUOTE_MINIMAL, если quotechar не равен None, иначе QUOTE_NONE.

Dialect.skipinitialspace¶

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

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

Чуть более продвинутое использование 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(f'file {filename}, line {reader.line_num}: {e}')

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

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

Сноски