csv.md
1> **Источник:** https://python-all.ru/3.4/library/csv.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 14.1. [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) – чтение и запись CSV-файлов89Так называемый формат CSV (Comma Separated Values) – самый распространенный формат импорта и экспорта для электронных таблиц и баз данных. Формат CSV использовался много лет до попыток дать ему стандартизированное описание в [**RFC 4180**](https://python-all.ru/3.4/library/csv.html). Отсутствие четкого стандарта приводит к тому, что в данных, создаваемых и используемых разными приложениями, часто встречаются незначительные различия. Из-за этих различий обработка CSV-файлов из разных источников может быть утомительной. Тем не менее, хотя разделители и символы кавычек различаются, общий формат достаточно схож, чтобы можно было написать один модуль, способный эффективно работать с такими данными, скрывая от программиста детали чтения и записи.1011Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) реализует классы для чтения и записи табличных данных в формате CSV. Он позволяет программистам сказать: «записать эти данные в формате, предпочитаемом Excel» или «прочитать данные из этого файла, созданного Excel», не зная точных деталей формата CSV, используемого Excel. Программисты также могут описывать форматы CSV, понятные другим приложениям, или определять свои собственные специализированные форматы CSV.1213Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) предоставляет объекты [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader) и [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer), которые читают и записывают последовательности. Программисты также могут читать и записывать данные в виде словарей, используя классы [`DictReader`](https://python-all.ru/3.4/library/csv.html#csv.DictReader) и [`DictWriter`](https://python-all.ru/3.4/library/csv.html#csv.DictWriter).1415> **См. также**16>17> **[**PEP 305**](https://python-all.ru/3.4/library/csv.html) - API для CSV-файлов**18>19> Предложение по улучшению Python, в котором было предложено это дополнение.2021## 14.1.1. Содержание модуля2223Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) определяет следующие функции:2425#### `csv.reader(csvfile, dialect='excel', **fmtparams)`2627Возвращает объект чтения, который перебирает строки в заданном *csvfile*. *csvfile* может быть любым объектом, поддерживающим протокол [*итератора*](https://python-all.ru/3.4/glossary.html#term-iterator) и возвращающим строку при каждом вызове метода `__next__()` – подходят как [*файловые объекты*](https://python-all.ru/3.4/glossary.html#term-file-object), так и списки. Если *csvfile* является файловым объектом, его следует открывать с `newline=''`. [\[1\]](https://python-all.ru/3.4/library/csv.html#id3) Можно передать необязательный параметр *dialect*, который задаёт набор параметров для конкретного диалекта CSV. Это может быть экземпляр подкласса класса [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect) или одна из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.4/library/csv.html#csv.list_dialects). Другие необязательные именованные аргументы *fmtparams* позволяют переопределить отдельные параметры форматирования текущего диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе [*Диалекты и параметры форматирования*](https://python-all.ru/3.4/library/csv.html#csv-fmt-params).2829Каждая строка, прочитанная из CSV-файла, возвращается в виде списка строк. Автоматическое преобразование типов данных не выполняется, если только не указана опция форматирования `QUOTE_NONNUMERIC` (в этом случае незаключенные в кавычки поля преобразуются в числа с плавающей запятой).3031Краткий пример использования:3233```python34>>> import csv35>>> with open('eggs.csv', newline='') as csvfile:36... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')37... for row in spamreader:38... print(', '.join(row))39Spam, Spam, Spam, Spam, Spam, Baked Beans40Spam, Lovely Spam, Wonderful Spam41```4243#### `csv.writer(csvfile, dialect='excel', **fmtparams)`4445Возвращает объект записи, который преобразует пользовательские данные в строки с разделителями для указанного файлоподобного объекта. *csvfile* может быть любым объектом с методом `write()`. Если *csvfile* является файловым объектом, его следует открывать с `newline=''` [\[1\]](https://python-all.ru/3.4/library/csv.html#id3). Можно передать необязательный параметр *dialect*, задающий набор параметров для конкретного диалекта CSV. Это может быть экземпляр подкласса класса [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect) или одна из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.4/library/csv.html#csv.list_dialects). Другие необязательные именованные аргументы *fmtparams* позволяют переопределить отдельные параметры форматирования текущего диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе [*Диалекты и параметры форматирования*](https://python-all.ru/3.4/library/csv.html#csv-fmt-params). Чтобы упростить взаимодействие с модулями, реализующими DB API, значение [`None`](https://python-all.ru/3.4/library/constants.html#None) записывается как пустая строка. Хотя это преобразование необратимо, оно упрощает выгрузку значений SQL NULL в CSV-файлы без предварительной обработки данных, возвращаемых вызовом `cursor.fetch*`. Все остальные нестроковые данные перед записью преобразуются в строки с помощью [`str()`](https://python-all.ru/3.4/library/stdtypes.html#str).4647Краткий пример использования:4849```python50import csv51with open('eggs.csv', 'w', newline='') as csvfile:52 spamwriter = csv.writer(csvfile, delimiter=' ',53 quotechar='|', quoting=csv.QUOTE_MINIMAL)54 spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])55 spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])56```5758#### `csv.register_dialect(name[, dialect[, **fmtparams]])`5960Связывает *dialect* с именем *name*. *name* должен быть строкой. Диалект можно задать, передав подкласс [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect), или с помощью именованных аргументов *fmtparams*, или обоими способами; при этом именованные аргументы переопределяют параметры диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе [*Диалекты и параметры форматирования*](https://python-all.ru/3.4/library/csv.html#csv-fmt-params).6162#### `csv.unregister_dialect(name)`6364Удаляет диалект, связанный с *name*, из реестра диалектов. Исключение [`Error`](https://python-all.ru/3.4/library/csv.html#csv.Error) возбуждается, если *name* не является зарегистрированным именем диалекта.6566#### `csv.get_dialect(name)`6768Возвращает диалект, связанный с *name*. Исключение [`Error`](https://python-all.ru/3.4/library/csv.html#csv.Error) возбуждается, если *name* не является зарегистрированным именем диалекта. Эта функция возвращает неизменяемый [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect).6970#### `csv.list_dialects()`7172Возвращает имена всех зарегистрированных диалектов.7374#### `csv.field_size_limit([new_limit])`7576Возвращает текущий максимальный размер поля, разрешенный парсером. Если задан *new\_limit*, он становится новым лимитом.7778Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) определяет следующие классы:7980#### `class csv.DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)`8182Создаёт объект, который работает как обычный читатель, но сопоставляет прочитанную информацию со словарём, ключи которого задаются необязательным параметром *fieldnames*. Параметр *fieldnames* представляет собой [`последовательность`](https://python-all.ru/3.4/library/collections.abc.html#module-collections.abc), элементы которой последовательно сопоставляются с полями входных данных. Эти элементы становятся ключами результирующего словаря. Если параметр *fieldnames* опущен, в качестве имён полей используются значения первой строки *csvfile*. Если прочитанная строка содержит больше полей, чем последовательность fieldnames, оставшиеся данные добавляются в виде последовательности, ключом которой служит значение *restkey*. Если прочитанная строка содержит меньше полей, чем последовательность fieldnames, оставшимся ключам присваивается значение необязательного параметра *restval*. Любые другие необязательные или именованные аргументы передаются базовому экземпляру [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader).8384Краткий пример использования:8586```python87>>> import csv88>>> with open('names.csv') as csvfile:89... reader = csv.DictReader(csvfile)90... for row in reader:91... print(row['first_name'], row['last_name'])92...93Baked Beans94Lovely Spam95Wonderful Spam96```9798#### `class csv.DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)`99100Создаёт объект, который работает как обычный записыватель, но преобразует словари в выходные строки. Параметр *fieldnames* – это [`последовательность`](https://python-all.ru/3.4/library/collections.abc.html#module-collections.abc) ключей, определяющая порядок, в котором значения словаря, передаваемого методу `writerow()`, записываются в *csvfile*. Необязательный параметр *restval* задаёт значение, которое будет записано, если в словаре отсутствует ключ из *fieldnames*. Если словарь, переданный методу `writerow()`, содержит ключ, отсутствующий в *fieldnames*, необязательный параметр *extrasaction* определяет, какое действие предпринять. Если он установлен в `'raise'`, возбуждается исключение [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError). Если он установлен в `'ignore'`, дополнительные значения в словаре игнорируются. Любые другие необязательные или именованные аргументы передаются базовому экземпляру [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer).101102Обратите внимание: в отличие от класса [`DictReader`](https://python-all.ru/3.4/library/csv.html#csv.DictReader), параметр *fieldnames* класса [`DictWriter`](https://python-all.ru/3.4/library/csv.html#csv.DictWriter) является обязательным. Поскольку объекты [`dict`](https://python-all.ru/3.4/library/stdtypes.html#dict) в Python не упорядочены, недостаточно информации, чтобы определить порядок, в котором строка должна быть записана в *csvfile*.103104Краткий пример использования:105106```python107import csv108109with open('names.csv', 'w') as csvfile:110 fieldnames = ['first_name', 'last_name']111 writer = csv.DictWriter(csvfile, fieldnames=fieldnames)112113 writer.writeheader()114 writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})115 writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})116 writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})117```118119#### `class csv.Dialect`120121Класс [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect) – это класс-контейнер, используемый в основном для своих атрибутов, которые определяют параметры для конкретного экземпляра [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader) или [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer).122123#### `class csv.excel`124125Класс [`excel`](https://python-all.ru/3.4/library/csv.html#csv.excel) определяет обычные свойства CSV-файла, созданного Excel. Он зарегистрирован под именем диалекта `'excel'`.126127#### `class csv.excel_tab`128129Класс [`excel_tab`](https://python-all.ru/3.4/library/csv.html#csv.excel_tab) определяет обычные свойства файла с разделителями-табуляцией, созданного Excel. Он зарегистрирован под именем диалекта `'excel-tab'`.130131#### `class csv.unix_dialect`132133Класс [`unix_dialect`](https://python-all.ru/3.4/library/csv.html#csv.unix_dialect) определяет обычные свойства CSV-файла, созданного в UNIX-системах, т.е. использующего `'\n'` в качестве завершителя строки и заключающего все поля в кавычки. Он зарегистрирован под именем диалекта `'unix'`.134135Новое в версии 3.2.136137#### `class csv.Sniffer`138139Класс [`Sniffer`](https://python-all.ru/3.4/library/csv.html#csv.Sniffer) используется для определения формата CSV-файла.140141Класс [`Sniffer`](https://python-all.ru/3.4/library/csv.html#csv.Sniffer) предоставляет два метода:142143#### `sniff(sample, delimiters=None)`144145Анализирует заданный образец *sample* и возвращает подкласс [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect), отражающий найденные параметры. Если задан необязательный параметр *delimiters*, он интерпретируется как строка, содержащая возможные допустимые символы-разделители.146147#### `has_header(sample)`148149Анализирует образец текста (предположительно в формате CSV) и возвращает [`True`](https://python-all.ru/3.4/library/constants.html#True), если первая строка выглядит как набор заголовков столбцов.150151Пример использования [`Sniffer`](https://python-all.ru/3.4/library/csv.html#csv.Sniffer):152153```python154with open('example.csv') as csvfile:155 dialect = csv.Sniffer().sniff(csvfile.read(1024))156 csvfile.seek(0)157 reader = csv.reader(csvfile, dialect)158 # ... здесь обрабатывается содержимое CSV-файла ...159```160161Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) определяет следующие константы:162163#### `csv.QUOTE_ALL`164165Указывает объектам [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer) заключать все поля в кавычки.166167#### `csv.QUOTE_MINIMAL`168169Указывает объектам [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer) заключать в кавычки только те поля, которые содержат специальные символы, такие как *delimiter*, *quotechar* или любые символы из *lineterminator*.170171#### `csv.QUOTE_NONNUMERIC`172173Указывает объектам [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer) заключать в кавычки все нечисловые поля.174175Указывает объекту чтения преобразовывать все нецитируемые поля в тип *float*.176177#### `csv.QUOTE_NONE`178179Указывает объектам [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer) никогда не заключать поля в кавычки. Когда текущий *delimiter* встречается в выходных данных, перед ним ставится текущий символ *escapechar*. Если *escapechar* не задан, writer вызовет [`Error`](https://python-all.ru/3.4/library/csv.html#csv.Error), если будут встречены символы, требующие экранирования.180181Указывает объектам [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader) не выполнять никакой специальной обработки символов кавычек.182183Модуль [`csv`](https://python-all.ru/3.4/library/csv.html#module-csv) определяет следующее исключение:184185#### `exception csv.Error`186187Возбуждается любой из функций при обнаружении ошибки.188189## 14.1.2. Диалекты и параметры форматирования190191Чтобы упростить задание формата входных и выходных записей, конкретные параметры форматирования группируются в диалекты. Диалект – это подкласс класса [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect), имеющий набор определённых методов и единственный метод `validate()`. При создании объектов [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader) или [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer) программист может указать строку или подкласс класса [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect) в качестве параметра диалекта. В дополнение к параметру *dialect* или вместо него программист может также указать отдельные параметры форматирования, которые имеют те же имена, что и атрибуты, определённые ниже для класса [`Dialect`](https://python-all.ru/3.4/library/csv.html#csv.Dialect).192193Диалекты поддерживают следующие атрибуты:194195#### `Dialect.delimiter`196197Односимвольная строка, используемая для разделения полей. По умолчанию равна `','`.198199#### `Dialect.doublequote`200201Управляет тем, как экземпляры *quotechar*, встречающиеся внутри поля, должны сами заключаться в кавычки. Если [`True`](https://python-all.ru/3.4/library/constants.html#True), символ удваивается. Если [`False`](https://python-all.ru/3.4/library/constants.html#False), *escapechar* используется как префикс перед *quotechar*. По умолчанию равно [`True`](https://python-all.ru/3.4/library/constants.html#True).202203При выводе, если *doublequote* равно [`False`](https://python-all.ru/3.4/library/constants.html#False) и не задан *escapechar*, возникает [`Error`](https://python-all.ru/3.4/library/csv.html#csv.Error), если в поле обнаружен *quotechar*.204205#### `Dialect.escapechar`206207Односимвольная строка, используемая writer для экранирования *delimiter*, если *quoting* установлен в [`QUOTE_NONE`](https://python-all.ru/3.4/library/csv.html#csv.QUOTE_NONE), и *quotechar*, если *doublequote* равно [`False`](https://python-all.ru/3.4/library/constants.html#False). При чтении *escapechar* удаляет любое специальное значение из следующего символа. По умолчанию [`None`](https://python-all.ru/3.4/library/constants.html#None), что отключает экранирование.208209#### `Dialect.lineterminator`210211Строка, используемая для завершения строк, создаваемых [`writer`](https://python-all.ru/3.4/library/csv.html#csv.writer). По умолчанию равна `'\r\n'`.212213> **Примечание**214>215> [`reader`](https://python-all.ru/3.4/library/csv.html#csv.reader) жёстко запрограммирован распознавать `'\r'` или `'\n'` как конец строки и игнорирует *lineterminator*. Это поведение может измениться в будущем.216217#### `Dialect.quotechar`218219Односимвольная строка, используемая для заключения в кавычки полей, содержащих специальные символы, такие как *разделитель* или *quotechar*, или содержащих символы новой строки. По умолчанию `'"'`.220221#### `Dialect.quoting`222223Управляет тем, когда кавычки должны генерироваться писателем и распознаваться читателем. Он может принимать любую из констант `QUOTE_*` (см. раздел [*Содержание модуля*](https://python-all.ru/3.4/library/csv.html#csv-contents)) и по умолчанию равен [`QUOTE_MINIMAL`](https://python-all.ru/3.4/library/csv.html#csv.QUOTE_MINIMAL).224225#### `Dialect.skipinitialspace`226227Если [`True`](https://python-all.ru/3.4/library/constants.html#True), пробелы, непосредственно следующие за *разделителем*, игнорируются. Значение по умолчанию – [`False`](https://python-all.ru/3.4/library/constants.html#False).228229#### `Dialect.strict`230231Если `True`, при некорректном CSV-вводе возбуждается исключение [`Error`](https://python-all.ru/3.4/library/csv.html#csv.Error). Значение по умолчанию – `False`.232233## 14.1.3. Объекты Reader234235Объекты-читатели (экземпляры [`DictReader`](https://python-all.ru/3.4/library/csv.html#csv.DictReader) и объекты, возвращаемые функцией [`reader()`](https://python-all.ru/3.4/library/csv.html#csv.reader)) имеют следующие открытые методы:236237#### `csvreader.__next__()`238239Возвращает следующую строку итерируемого объекта читателя в виде списка, разобранную в соответствии с текущим диалектом. Обычно следует вызывать это как `next(reader)`.240241Объекты reader имеют следующие открытые атрибуты:242243#### `csvreader.dialect`244245Доступное только для чтения описание диалекта, используемого синтаксическим анализатором.246247#### `csvreader.line_num`248249Количество строк, прочитанных из итератора-источника. Это число не совпадает с количеством возвращённых записей, так как записи могут занимать несколько строк.250251Объекты DictReader имеют следующий открытый атрибут:252253#### `csvreader.fieldnames`254255Если этот атрибут не был передан в качестве параметра при создании объекта, он инициализируется при первом обращении или при чтении первой записи из файла.256257## 14.1.4. Объекты Writer258259Объекты-писатели (`Writer`) (экземпляры [`DictWriter`](https://python-all.ru/3.4/library/csv.html#csv.DictWriter) и объекты, возвращаемые функцией [`writer()`](https://python-all.ru/3.4/library/csv.html#csv.writer)) имеют следующие открытые методы. *Строка* должна быть последовательностью строк или чисел для объектов `Writer` и словарём, отображающим имена полей на строки или числа (предварительно пропуская их через [`str()`](https://python-all.ru/3.4/library/stdtypes.html#str)) для объектов [`DictWriter`](https://python-all.ru/3.4/library/csv.html#csv.DictWriter). Обратите внимание, что комплексные числа записываются в скобках. Это может вызвать проблемы у других программ, читающих CSV-файлы (если они вообще поддерживают комплексные числа).260261#### `csvwriter.writerow(row)`262263Записывает параметр *row* в файловый объект writer, отформатировав в соответствии с текущим диалектом.264265#### `csvwriter.writerows(rows)`266267Записывает все параметры *rows* (список объектов *row*, как описано выше) в файловый объект writer, форматируя в соответствии с текущим диалектом.268269Объекты Writer имеют следующий открытый атрибут:270271#### `csvwriter.dialect`272273Описание диалекта, используемого средством записи, доступное только для чтения.274275Объекты DictWriter имеют следующий открытый метод:276277#### `DictWriter.writeheader()`278279Записывает строку с названиями полей (как указано в конструкторе).280281Новое в версии 3.2.282283## 14.1.5. Примеры284285Простейший пример чтения CSV-файла:286287```python288import csv289with open('some.csv', newline='') as f:290 reader = csv.reader(f)291 for row in reader:292 print(row)293```294295Чтение файла в альтернативном формате:296297```python298import csv299with open('passwd', newline='') as f:300 reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)301 for row in reader:302 print(row)303```304305Соответствующий простейший пример записи:306307```python308import csv309with open('some.csv', 'w', newline='') as f:310 writer = csv.writer(f)311 writer.writerows(someiterable)312```313314Поскольку [`open()`](https://python-all.ru/3.4/library/functions.html#open) используется для открытия CSV-файла для чтения, файл по умолчанию будет декодирован в Unicode с использованием системной кодировки по умолчанию (см. [`locale.getpreferredencoding()`](https://python-all.ru/3.4/library/locale.html#locale.getpreferredencoding)). Чтобы декодировать файл с другой кодировкой, используйте аргумент `encoding` функции open:315316```python317import csv318with open('some.csv', newline='', encoding='utf-8') as f:319 reader = csv.reader(f)320 for row in reader:321 print(row)322```323324То же самое относится к записи в кодировке, отличной от системной: укажите аргумент encoding при открытии выходного файла.325326Регистрация нового диалекта:327328```python329import csv330csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)331with open('passwd', newline='') as f:332 reader = csv.reader(f, 'unixpwd')333```334335Чуть более продвинутое использование reader – перехват и сообщение об ошибках:336337```python338import csv, sys339filename = 'some.csv'340with open(filename, newline='') as f:341 reader = csv.reader(f)342 try:343 for row in reader:344 print(row)345 except csv.Error as e:346 sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))347```348349И хотя модуль напрямую не поддерживает разбор строк, это можно легко сделать:350351```python352import csv353for row in csv.reader(['one,two,three']):354 print(row)355```356357Сноски358359| \[1\] | *([1](https://python-all.ru/3.4/library/csv.html#id1), [2](https://python-all.ru/3.4/library/csv.html#id2))* Если `newline=''` не указан, символы новой строки, встроенные в поля в кавычках, не будут интерпретироваться правильно, а на платформах, использующих `\r\n` в качестве окончания строки, при записи будет добавлен лишний `\r`. Указывать `newline=''` всегда должно быть безопасно, поскольку модуль csv выполняет собственную обработку символов новой строки ([*универсальную*](https://python-all.ru/3.4/glossary.html#term-universal-newlines)). |360| --- | --- |361