csv.md
1> **Источник:** https://python-all.ru/3.1/library/csv.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.1. `csv` – Чтение и запись CSV-файлов89Так называемый формат CSV (Comma Separated Values – значения, разделённые запятыми) – наиболее распространённый формат импорта и экспорта электронных таблиц и баз данных. Не существует «стандарта CSV», поэтому формат определяется операционно, на основе множества приложений, которые его читают и записывают. Отсутствие стандарта означает, что в данных, создаваемых и потребляемых разными приложениями, часто существуют тонкие различия. Эти различия могут затруднять обработку CSV-файлов из нескольких источников. Тем не менее, хотя разделители и символы кавычек различаются, общий формат достаточно схож, чтобы можно было написать единый модуль, способный эффективно манипулировать такими данными, скрывая от программиста детали чтения и записи.1011Модуль `csv` предоставляет классы для чтения и записи табличных данных в формате CSV. Он позволяет программистам сказать: «записать эти данные в формате, предпочтительном для Excel» или «прочитать данные из этого файла, который был создан Excel», не вдаваясь в точные детали формата CSV, используемого Excel. Программисты также могут описывать форматы CSV, понятные другим приложениям, или определять собственные форматы CSV специального назначения.1213Объекты [`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader) и [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer) модуля `csv` читают и записывают последовательности. Программисты также могут читать и записывать данные в виде словаря, используя классы [`DictReader`](https://python-all.ru/3.1/library/csv.html#csv.DictReader) и [`DictWriter`](https://python-all.ru/3.1/library/csv.html#csv.DictWriter).1415> **См. также**16>17> **[**PEP 305**](https://python-all.ru/3.1/library/csv.html) - API для CSV-файлов**18>19> Предложение по улучшению Python, в котором было предложено это дополнение.2021## 13.1.1. Содержание модуля2223Модуль `csv` определяет следующие функции:2425#### `csv.reader(csvfile, dialect='excel', **fmtparams)`2627Возвращает объект чтения, который перебирает строки в заданном *csvfile*. *csvfile* может быть любым объектом, поддерживающим протокол [*итератора*](https://python-all.ru/3.1/glossary.html#term-iterator) и возвращающим строку при каждом вызове метода `__next__()` – подходят как [*файловые объекты*](https://python-all.ru/3.1/glossary.html#term-file-object), так и списки. Если *csvfile* является файловым объектом, его следует открывать с `newline=''`. [\[1\]](https://python-all.ru/3.1/library/csv.html#id3) Можно передать необязательный параметр *dialect*, который задаёт набор параметров для конкретного диалекта CSV. Это может быть экземпляр подкласса класса [`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect) или одна из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.1/library/csv.html#csv.list_dialects). Другие необязательные именованные аргументы *fmtparams* позволяют переопределить отдельные параметры форматирования текущего диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе [*Диалекты и параметры форматирования*](https://python-all.ru/3.1/library/csv.html#csv-fmt-params).2829Каждая строка, прочитанная из CSV-файла, возвращается в виде списка строк. Автоматическое преобразование типов данных не выполняется, если только не указана опция форматирования `QUOTE_NONNUMERIC` (в этом случае незаключенные в кавычки поля преобразуются в числа с плавающей запятой).3031Краткий пример использования:3233```python34>>> import csv35>>> spamReader = csv.reader(open('eggs.csv', newline=''), delimiter=' ', quotechar='|')36>>> for row in spamReader:37... print(', '.join(row))38Spam, Spam, Spam, Spam, Spam, Baked Beans39Spam, Lovely Spam, Wonderful Spam40```4142#### `csv.writer(csvfile, dialect='excel', **fmtparams)`4344Возвращает объект записи, который преобразует пользовательские данные в строки с разделителями для указанного файлоподобного объекта. *csvfile* может быть любым объектом с методом `write()`. Если *csvfile* является файловым объектом, его следует открывать с `newline=''` [\[1\]](https://python-all.ru/3.1/library/csv.html#id3). Можно передать необязательный параметр *dialect*, задающий набор параметров для конкретного диалекта CSV. Это может быть экземпляр подкласса класса [`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect) или одна из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.1/library/csv.html#csv.list_dialects). Другие необязательные именованные аргументы *fmtparams* позволяют переопределить отдельные параметры форматирования текущего диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе [*Диалекты и параметры форматирования*](https://python-all.ru/3.1/library/csv.html#csv-fmt-params). Чтобы упростить взаимодействие с модулями, реализующими DB API, значение [`None`](https://python-all.ru/3.1/library/constants.html#None) записывается как пустая строка. Хотя это преобразование необратимо, оно упрощает выгрузку значений SQL NULL в CSV-файлы без предварительной обработки данных, возвращаемых вызовом `cursor.fetch*`. Все остальные нестроковые данные перед записью преобразуются в строки с помощью [`str()`](https://python-all.ru/3.1/library/functions.html#str).4546Краткий пример использования:4748```python49>>> import csv50>>> spamWriter = csv.writer(open('eggs.csv', 'w', newline=''), delimiter=' ',51... quotechar='|', quoting=csv.QUOTE_MINIMAL)52>>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])53>>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])54```5556#### `csv.register_dialect(name[, dialect], **fmtparams)`5758Связывает5960*dialect*6162с именем6364*name*6566.6768*name*6970должен быть строкой. Диалект можно задать, передав подкласс7172[`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect)7374, или с помощью именованных аргументов7576*fmtparams*7778, или обоими способами; при этом именованные аргументы переопределяют параметры диалекта. Полные сведения о диалекте и параметрах форматирования см. в разделе7980[*Диалекты и параметры форматирования*](https://python-all.ru/3.1/library/csv.html#csv-fmt-params)8182.8384#### `csv.unregister_dialect(name)`8586Удаляет диалект, связанный с8788*name*8990, из реестра диалектов. Исключение9192[`Error`](https://python-all.ru/3.1/library/csv.html#csv.Error)9394возбуждается, если9596*name*9798не является зарегистрированным именем диалекта.99100#### `csv.get_dialect(name)`101102Возвращает диалект, связанный с103104*name*105106. Исключение107108[`Error`](https://python-all.ru/3.1/library/csv.html#csv.Error)109110возбуждается, если111112*name*113114не является зарегистрированным именем диалекта. Эта функция возвращает неизменяемый115116[`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect)117118.119120#### `csv.list_dialects()`121122Возвращает имена всех зарегистрированных диалектов.123124#### `csv.field_size_limit([new_limit])`125126Возвращает текущий максимальный размер поля, разрешенный парсером. Если задан127128*new\_limit*129130, он становится новым лимитом.131132Модуль `csv` определяет следующие классы:133134#### `class csv.DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)`135136Создаёт объект, который работает как обычный reader, но преобразует прочитанные данные в словарь (dict), ключи которого задаются необязательным параметром137138*fieldnames*139140. Если параметр141142*fieldnames*143144опущен, в качестве имён полей используются значения первой строки145146*csvfile*147148. Если прочитанная строка содержит больше полей, чем последовательность fieldnames, оставшиеся данные добавляются как последовательность, ключом которой служит значение149150*restkey*151152. Если прочитанная строка содержит меньше полей, чем последовательность fieldnames, оставшиеся ключи принимают значение необязательного параметра153154*restval*155156. Все остальные необязательные или ключевые аргументы передаются экземпляру157158[`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader)159160.161162#### `class csv.DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)`163164Создаёт объект, который работает как обычный writer, но преобразует словари в выходные строки. Параметр *fieldnames* определяет порядок, в котором значения словаря, переданного методу `writerow()`, записываются в *csvfile*. Необязательный параметр *restval* задаёт значение, которое будет записано, если в словаре отсутствует ключ из *fieldnames*. Если словарь, переданный методу `writerow()`, содержит ключ, отсутствующий в *fieldnames*, необязательный параметр *extrasaction* указывает, какое действие предпринять. Если он установлен в `'raise'`, возбуждается исключение [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError). Если установлен в `'ignore'`, дополнительные значения в словаре игнорируются. Все остальные необязательные или ключевые аргументы передаются экземпляру [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer).165166Обратите внимание: в отличие от класса [`DictReader`](https://python-all.ru/3.1/library/csv.html#csv.DictReader), параметр *fieldnames* [`DictWriter`](https://python-all.ru/3.1/library/csv.html#csv.DictWriter) обязателен. Поскольку объекты [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict) в Python не упорядочены, недостаточно информации, чтобы определить порядок, в котором строка должна быть записана в *csvfile*.167168#### `class csv.Dialect`169170Класс171172[`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect)173174– это класс-контейнер, используемый в основном для своих атрибутов, которые определяют параметры для конкретного экземпляра175176[`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader)177178или179180[`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer)181182.183184#### `class csv.excel`185186Класс187188[`excel`](https://python-all.ru/3.1/library/csv.html#csv.excel)189190определяет обычные свойства CSV-файла, созданного Excel. Он зарегистрирован под именем диалекта191192`'excel'`193194.195196#### `class csv.excel_tab`197198Класс199200[`excel_tab`](https://python-all.ru/3.1/library/csv.html#csv.excel_tab)201202определяет обычные свойства файла с разделителями-табуляцией, созданного Excel. Он зарегистрирован под именем диалекта203204`'excel-tab'`205206.207208#### `class csv.Sniffer`209210Класс [`Sniffer`](https://python-all.ru/3.1/library/csv.html#csv.Sniffer) используется для определения формата CSV-файла.211212Класс [`Sniffer`](https://python-all.ru/3.1/library/csv.html#csv.Sniffer) предоставляет два метода:213214#### `sniff(sample, delimiters=None)`215216Анализирует заданный образец217218*sample*219220и возвращает подкласс221222[`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect)223224, отражающий найденные параметры. Если задан необязательный параметр225226*delimiters*227228, он интерпретируется как строка, содержащая возможные допустимые символы-разделители.229230#### `has_header(sample)`231232Анализирует образец текста (предположительно в формате CSV) и возвращает233234[`True`](https://python-all.ru/3.1/library/constants.html#True)235236, если первая строка выглядит как набор заголовков столбцов.237238Пример использования [`Sniffer`](https://python-all.ru/3.1/library/csv.html#csv.Sniffer):239240```python241csvfile = open("example.csv")242dialect = csv.Sniffer().sniff(csvfile.read(1024))243csvfile.seek(0)244reader = csv.reader(csvfile, dialect)245# ... здесь обрабатывается содержимое CSV-файла ...246```247248Модуль `csv` определяет следующие константы:249250#### `csv.QUOTE_ALL`251252Указывает объектам253254[`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer)255256заключать все поля в кавычки.257258#### `csv.QUOTE_MINIMAL`259260Указывает объектам261262[`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer)263264заключать в кавычки только те поля, которые содержат специальные символы, такие как265266*delimiter*267268,269270*quotechar*271272или любые символы из273274*lineterminator*275276.277278#### `csv.QUOTE_NONNUMERIC`279280Указывает объектам [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer) заключать в кавычки все нечисловые поля.281282Указывает объекту чтения преобразовывать все нецитируемые поля в тип *float*.283284#### `csv.QUOTE_NONE`285286Указывает объектам [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer) никогда не заключать поля в кавычки. Когда текущий *delimiter* встречается в выходных данных, перед ним ставится текущий символ *escapechar*. Если *escapechar* не задан, writer вызовет [`Error`](https://python-all.ru/3.1/library/csv.html#csv.Error), если будут встречены символы, требующие экранирования.287288Указывает объектам [`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader) не выполнять никакой специальной обработки символов кавычек.289290Модуль `csv` определяет следующее исключение:291292#### `exception csv.Error`293294Возбуждается любой из функций при обнаружении ошибки.295296## 13.1.2. Диалекты и параметры форматирования297298Чтобы упростить задание формата входных и выходных записей, конкретные параметры форматирования группируются в диалекты. Диалект – это подкласс класса [`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect), имеющий набор определённых методов и единственный метод `validate()`. При создании объектов [`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader) или [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer) программист может указать строку или подкласс класса [`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect) в качестве параметра диалекта. В дополнение к параметру *dialect* или вместо него программист может также указать отдельные параметры форматирования, которые имеют те же имена, что и атрибуты, определённые ниже для класса [`Dialect`](https://python-all.ru/3.1/library/csv.html#csv.Dialect).299300Диалекты поддерживают следующие атрибуты:301302#### `Dialect.delimiter`303304Односимвольная строка, используемая для разделения полей. По умолчанию равна305306`','`307308.309310#### `Dialect.doublequote`311312Управляет тем, как экземпляры *quotechar*, появляющиеся внутри поля, должны экранироваться. Когда [`True`](https://python-all.ru/3.1/library/constants.html#True), символ удваивается. Когда [`False`](https://python-all.ru/3.1/library/constants.html#False), *escapechar* используется как префикс перед *quotechar*. По умолчанию [`True`](https://python-all.ru/3.1/library/constants.html#True).313314При выводе, если *doublequote* равно [`False`](https://python-all.ru/3.1/library/constants.html#False) и не задан *escapechar*, возникает [`Error`](https://python-all.ru/3.1/library/csv.html#csv.Error), если в поле обнаружен *quotechar*.315316#### `Dialect.escapechar`317318Односимвольная строка, используемая writer для экранирования319320*delimiter*321322, если323324*quoting*325326установлен в327328[`QUOTE_NONE`](https://python-all.ru/3.1/library/csv.html#csv.QUOTE_NONE)329330, и331332*quotechar*333334, если335336*doublequote*337338равно339340[`False`](https://python-all.ru/3.1/library/constants.html#False)341342. При чтении343344*escapechar*345346удаляет любое специальное значение из следующего символа. По умолчанию347348[`None`](https://python-all.ru/3.1/library/constants.html#None)349350, что отключает экранирование.351352#### `Dialect.lineterminator`353354Строка, используемая для завершения строк, создаваемых [`writer`](https://python-all.ru/3.1/library/csv.html#csv.writer). По умолчанию равна `'\r\n'`.355356> **Примечание**357>358> [`reader`](https://python-all.ru/3.1/library/csv.html#csv.reader) жёстко запрограммирован распознавать `'\r'` или `'\n'` как конец строки и игнорирует *lineterminator*. Это поведение может измениться в будущем.359360#### `Dialect.quotechar`361362Односимвольная строка, используемая для заключения в кавычки полей, содержащих специальные символы, такие как363364*разделитель*365366или367368*quotechar*369370, или содержащих символы новой строки. По умолчанию371372`'"'`373374.375376#### `Dialect.quoting`377378Управляет тем, когда кавычки должны генерироваться писателем и распознаваться читателем. Он может принимать любую из констант379380`QUOTE_*`381382(см. раздел383384[*Содержание модуля*](https://python-all.ru/3.1/library/csv.html#csv-contents)385386) и по умолчанию равен387388[`QUOTE_MINIMAL`](https://python-all.ru/3.1/library/csv.html#csv.QUOTE_MINIMAL)389390.391392#### `Dialect.skipinitialspace`393394Если395396[`True`](https://python-all.ru/3.1/library/constants.html#True)397398, пробелы, непосредственно следующие за399400*разделителем*401402, игнорируются. Значение по умолчанию –403404[`False`](https://python-all.ru/3.1/library/constants.html#False)405406.407408## 13.1.3. Объекты Reader409410Объекты-читатели (экземпляры [`DictReader`](https://python-all.ru/3.1/library/csv.html#csv.DictReader) и объекты, возвращаемые функцией [`reader()`](https://python-all.ru/3.1/library/csv.html#csv.reader)) имеют следующие открытые методы:411412#### `csvreader.__next__()`413414Возвращает следующую строку итерируемого объекта читателя в виде списка, разобранную в соответствии с текущим диалектом. Обычно следует вызывать это как415416`next(reader)`417418.419420Объекты reader имеют следующие открытые атрибуты:421422#### `csvreader.dialect`423424Доступное только для чтения описание диалекта, используемого синтаксическим анализатором.425426#### `csvreader.line_num`427428Количество строк, прочитанных из итератора-источника. Это число не совпадает с количеством возвращённых записей, так как записи могут занимать несколько строк.429430Объекты DictReader имеют следующий открытый атрибут:431432#### `csvreader.fieldnames`433434Если этот атрибут не был передан в качестве параметра при создании объекта, он инициализируется при первом обращении или при чтении первой записи из файла.435436## 13.1.4. Объекты Writer437438Объекты-писатели (`Writer`) (экземпляры [`DictWriter`](https://python-all.ru/3.1/library/csv.html#csv.DictWriter) и объекты, возвращаемые функцией [`writer()`](https://python-all.ru/3.1/library/csv.html#csv.writer)) имеют следующие открытые методы. *Строка* должна быть последовательностью строк или чисел для объектов `Writer` и словарём, отображающим имена полей на строки или числа (предварительно пропуская их через [`str()`](https://python-all.ru/3.1/library/functions.html#str)) для объектов [`DictWriter`](https://python-all.ru/3.1/library/csv.html#csv.DictWriter). Обратите внимание, что комплексные числа записываются в скобках. Это может вызвать проблемы у других программ, читающих CSV-файлы (если они вообще поддерживают комплексные числа).439440#### `csvwriter.writerow(row)`441442Записывает параметр443444*row*445446в файловый объект writer, отформатировав в соответствии с текущим диалектом.447448#### `csvwriter.writerows(rows)`449450Записывает все параметры451452*rows*453454(список объектов455456*row*457458, как описано выше) в файловый объект writer, форматируя в соответствии с текущим диалектом.459460Объекты Writer имеют следующий открытый атрибут:461462#### `csvwriter.dialect`463464Описание диалекта, используемого средством записи, доступное только для чтения.465466## 13.1.5. Примеры467468Простейший пример чтения CSV-файла:469470```python471import csv472with open('some.csv', newline='') as f:473 reader = csv.reader(f)474 for row in reader:475 print(row)476```477478Чтение файла в альтернативном формате:479480```python481import csv482with open('passwd', newline='') as f:483 reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)484 for row in reader:485 print(row)486```487488Соответствующий простейший пример записи:489490```python491import csv492with open('some.csv', 'w', newline='') as f:493 writer = csv.writer(f)494 writer.writerows(someiterable)495```496497Поскольку [`open()`](https://python-all.ru/3.1/library/functions.html#open) используется для открытия CSV-файла для чтения, файл по умолчанию будет декодирован в Unicode с использованием системной кодировки по умолчанию (см. [`locale.getpreferredencoding()`](https://python-all.ru/3.1/library/locale.html#locale.getpreferredencoding)). Чтобы декодировать файл с другой кодировкой, используйте аргумент `encoding` функции open:498499```python500import csv501with open('some.csv', newline='', encoding='utf-8') as f:502 reader = csv.reader(f)503 for row in reader:504 print(row)505```506507То же самое относится к записи в кодировке, отличной от системной: укажите аргумент encoding при открытии выходного файла.508509Регистрация нового диалекта:510511```python512import csv513csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)514with open('passwd', newline='') as f:515 reader = csv.reader(f, 'unixpwd')516```517518Чуть более продвинутое использование reader – перехват и сообщение об ошибках:519520```python521import csv, sys522filename = 'some.csv'523with open(filename, newline='') as f:524 reader = csv.reader(f)525 try:526 for row in reader:527 print(row)528 except csv.Error as e:529 sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))530```531532И хотя модуль напрямую не поддерживает разбор строк, это можно легко сделать:533534```python535import csv536for row in csv.reader(['one,two,three']):537 print(row)538```539540Сноски541542| \[1\] | *([1](https://python-all.ru/3.1/library/csv.html#id1), [2](https://python-all.ru/3.1/library/csv.html#id2))* Если параметр `newline=''` не указан, символы новой строки внутри полей в кавычках не будут правильно интерпретироваться, а на платформах, использующих `\r\n` в качестве окончания строки, при записи будет добавлен лишний символ `\r`. Всегда безопасно указывать `newline=''`, так как модуль csv выполняет собственную (универсальную) обработку символов новой строки. |543| --- | --- |544