> **Источник:** https://python-all.ru/3.6/library/csv.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 14.1. [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv)– чтение и запись CSV-файлов **Исходный код:** [Lib/csv.py](https://python-all.ru/src/3.6/Lib/csv.py) --- Так называемый формат CSV (Comma Separated Values) – самый распространенный формат импорта и экспорта для электронных таблиц и баз данных. Формат CSV использовался много лет до попыток дать ему стандартизированное описание в [**RFC 4180**](https://python-all.ru/3.6/library/csv.html). Отсутствие четкого стандарта приводит к тому, что в данных, создаваемых и используемых разными приложениями, часто встречаются незначительные различия. Из-за этих различий обработка CSV-файлов из разных источников может быть утомительной. Тем не менее, хотя разделители и символы кавычек различаются, общий формат достаточно схож, чтобы можно было написать один модуль, способный эффективно работать с такими данными, скрывая от программиста детали чтения и записи. Модуль [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) реализует классы для чтения и записи табличных данных в формате CSV. Он позволяет программистам сказать: «запиши эти данные в формате, предпочитаемом Excel» или «прочитай данные из этого файла, созданного Excel», не вдаваясь в точные детали формата CSV, используемого Excel. Программисты также могут описывать форматы CSV, используемые другими приложениями, или определять собственные специализированные форматы CSV. Объекты [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader) и [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) модуля [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) читают и записывают последовательности. Программисты также могут читать и записывать данные в словарной форме, используя классы [`DictReader`](https://python-all.ru/3.6/library/csv.html#csv.DictReader) и [`DictWriter`](https://python-all.ru/3.6/library/csv.html#csv.DictWriter). > **См. также** > > **[**PEP 305**](https://python-all.ru/3.6/library/csv.html) - API для CSV-файлов** > > Предложение по улучшению Python, в котором было предложено это дополнение. ## 14.1.1. Содержание модуля Модуль [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) определяет следующие функции: #### `csv.reader(csvfile, dialect='excel', **fmtparams)` Возвращает объект reader, который перебирает строки в указанном *csvfile*. *csvfile* может быть любым объектом, поддерживающим протокол [итератора](https://python-all.ru/3.6/glossary.html#term-iterator) и возвращающим строку при каждом вызове метода `__next__()` – подходят как [файловые объекты](https://python-all.ru/3.6/glossary.html#term-file-object), так и списки. Если *csvfile* является файловым объектом, он должен быть открыт с `newline=''`. [1](https://python-all.ru/3.6/library/csv.html#id3) Можно указать необязательный параметр *dialect*, который задаёт набор параметров, специфичных для конкретного диалекта CSV. Он может быть экземпляром подкласса класса [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect) или одной из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.6/library/csv.html#csv.list_dialects). Остальные необязательные именованные аргументы *fmtparams* можно указать для переопределения отдельных параметров форматирования в текущем диалекте. Подробнее о диалекте и параметрах форматирования см. в разделе [Диалекты и параметры форматирования](https://python-all.ru/3.6/library/csv.html#csv-fmt-params). Каждая строка, прочитанная из CSV-файла, возвращается в виде списка строк. Автоматическое преобразование типов данных не выполняется, если не задан параметр формата `QUOTE_NONNUMERIC` (в этом случае незакавыченные поля преобразуются в числа с плавающей запятой). Краткий пример использования: ```python >>> 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](https://python-all.ru/3.6/library/csv.html#id3). Можно указать необязательный параметр *dialect*, который задаёт набор параметров для определённого диалекта CSV. Он может быть экземпляром подкласса [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect) или одной из строк, возвращаемых функцией [`list_dialects()`](https://python-all.ru/3.6/library/csv.html#csv.list_dialects). Остальные необязательные именованные аргументы *fmtparams* можно задать, чтобы переопределить отдельные параметры форматирования в текущем диалекте. Подробнее о диалектах и параметрах форматирования см. раздел [Диалекты и параметры форматирования](https://python-all.ru/3.6/library/csv.html#csv-fmt-params). Чтобы упростить взаимодействие с модулями, реализующими DB API, значение [`None`](https://python-all.ru/3.6/library/constants.html#None) записывается как пустая строка. Хотя это преобразование не является обратимым, оно упрощает выгрузку значений SQL NULL в CSV-файлы без предварительной обработки данных, возвращаемых вызовом `cursor.fetch*`. Все остальные нестроковые данные преобразуются в строки с помощью [`str()`](https://python-all.ru/3.6/library/stdtypes.html#str) перед записью. Краткий пример использования: ```python 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`](https://python-all.ru/3.6/library/csv.html#csv.Dialect), или именованными аргументами *fmtparams*, или и тем и другим; именованные аргументы переопределяют параметры диалекта. Подробнее о диалектах и параметрах форматирования см. раздел [Диалекты и параметры форматирования](https://python-all.ru/3.6/library/csv.html#csv-fmt-params). #### `csv.unregister_dialect(name)` Удаляет диалект, связанный с *name*, из реестра диалектов. Возникает исключение [`Error`](https://python-all.ru/3.6/library/csv.html#csv.Error), если *name* не является зарегистрированным именем диалекта. #### `csv.get_dialect(name)` Возвращает диалект, связанный с *name*. Возникает исключение [`Error`](https://python-all.ru/3.6/library/csv.html#csv.Error), если *name* не является зарегистрированным именем диалекта. Эта функция возвращает неизменяемый [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect). #### `csv.list_dialects()` Возвращает имена всех зарегистрированных диалектов. #### `csv.field_size_limit([new_limit])` Возвращает текущий максимальный размер поля, разрешенный парсером. Если задан *new\_limit*, он становится новым лимитом. Модуль [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) определяет следующие классы: #### `class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)` Создаёт объект, который работает как обычный reader, но сопоставляет информацию из каждой строки с [`OrderedDict`](https://python-all.ru/3.6/library/collections.html#collections.OrderedDict), ключи которого задаются необязательным параметром *fieldnames*. Параметр *fieldnames* – это [последовательность](https://python-all.ru/3.6/glossary.html#term-sequence). Если *fieldnames* опущен, в качестве названий полей используются значения первой строки файла *f*. Независимо от того, как определяются названия полей, упорядоченный словарь сохраняет их исходный порядок. Если строка содержит больше полей, чем fieldnames, оставшиеся данные помещаются в список и сохраняются с именем поля, указанным в *restkey* (по умолчанию `None`). Если непустая строка содержит меньше полей, чем fieldnames, недостающие значения заполняются `None`. Все остальные необязательные и именованные аргументы передаются базовому экземпляру [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader). Изменено в версии 3.6: Возвращаемые строки теперь имеют тип `OrderedDict`. Краткий пример использования: ```python >>> 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) OrderedDict([('first_name', 'John'), ('last_name', 'Cleese')]) ``` #### `class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)` Создаёт объект, который работает как обычный writer, но отображает словари на выходные строки. Параметр *fieldnames* – это [`sequence`](https://python-all.ru/3.6/library/collections.abc.html#module-collections.abc) ключей, определяющих порядок, в котором значения из словаря, переданного методу `writerow()`, записываются в файл *f*. Необязательный параметр *restval* задаёт значение, которое будет записано, если в словаре отсутствует ключ из *fieldnames*. Если словарь, переданный методу `writerow()`, содержит ключ, отсутствующий в *fieldnames*, необязательный параметр *extrasaction* указывает, какие действия предпринять. Если он установлен в `'raise'` (значение по умолчанию), возбуждается [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError). Если он установлен в `'ignore'`, дополнительные значения в словаре игнорируются. Все остальные необязательные и именованные аргументы передаются базовому экземпляру [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer). Обратите внимание, что в отличие от класса [`DictReader`](https://python-all.ru/3.6/library/csv.html#csv.DictReader), параметр *fieldnames* в [`DictWriter`](https://python-all.ru/3.6/library/csv.html#csv.DictWriter) не является необязательным. Поскольку объекты [`dict`](https://python-all.ru/3.6/library/stdtypes.html#dict) в Python не упорядочены, недостаточно информации, чтобы определить порядок, в котором строка должна быть записана в файл *f*. Краткий пример использования: ```python 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`](https://python-all.ru/3.6/library/csv.html#csv.Dialect) – это контейнерный класс, используемый в первую очередь для своих атрибутов, которые задают параметры для конкретного экземпляра [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader) или [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer). #### `class csv.excel` Класс [`excel`](https://python-all.ru/3.6/library/csv.html#csv.excel) определяет обычные свойства CSV-файла, созданного в Excel. Он зарегистрирован под именем диалекта `'excel'`. #### `class csv.excel_tab` Класс [`excel_tab`](https://python-all.ru/3.6/library/csv.html#csv.excel_tab) определяет обычные свойства файла с разделителями табуляции, созданного в Excel. Он зарегистрирован под именем диалекта `'excel-tab'`. #### `class csv.unix_dialect` Класс [`unix_dialect`](https://python-all.ru/3.6/library/csv.html#csv.unix_dialect) определяет обычные свойства CSV-файла, созданного в UNIX-системах, то есть использующего `'\n'` в качестве завершителя строк и заключающего все поля в кавычки. Он зарегистрирован под именем диалекта `'unix'`. Новое в версии 3.2. #### `class csv.Sniffer` Класс [`Sniffer`](https://python-all.ru/3.6/library/csv.html#csv.Sniffer) используется для определения формата CSV-файла. Класс [`Sniffer`](https://python-all.ru/3.6/library/csv.html#csv.Sniffer) предоставляет два метода: #### `sniff(sample, delimiters=None)` Анализирует переданный *sample* и возвращает подкласс [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect), отражающий найденные параметры. Если указан необязательный параметр *delimiters*, он интерпретируется как строка, содержащая возможные допустимые символы-разделители. #### `has_header(sample)` Анализирует образец текста (предположительно в формате CSV) и возвращает [`True`](https://python-all.ru/3.6/library/constants.html#True), если первая строка выглядит как набор заголовков столбцов. Пример использования [`Sniffer`](https://python-all.ru/3.6/library/csv.html#csv.Sniffer): ```python with open('example.csv', newline='') as csvfile: dialect = csv.Sniffer().sniff(csvfile.read(1024)) csvfile.seek(0) reader = csv.reader(csvfile, dialect) # ... здесь обрабатывается содержимое CSV-файла ... ``` Модуль [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) определяет следующие константы: #### `csv.QUOTE_ALL` Указывает объектам [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) заключать все поля в кавычки. #### `csv.QUOTE_MINIMAL` Указывает объектам [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) заключать в кавычки только те поля, которые содержат специальные символы, такие как *разделитель*, *символ кавычки* или любой из символов *терминатора строки*. #### `csv.QUOTE_NONNUMERIC` Указывает объектам [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) заключать все нечисловые поля в кавычки. Указывает объекту чтения преобразовывать все нецитируемые поля в тип *float*. #### `csv.QUOTE_NONE` Указывает объектам [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) никогда не заключать поля в кавычки. Если текущий *разделитель* встречается в выходных данных, перед ним ставится текущий символ *escapechar*. Если *escapechar* не задан, объект writer вызовет [`Error`](https://python-all.ru/3.6/library/csv.html#csv.Error), если встретятся символы, требующие экранирования. Указывает [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader) не выполнять специальной обработки символов кавычек. Модуль [`csv`](https://python-all.ru/3.6/library/csv.html#module-csv) определяет следующее исключение: #### `exception csv.Error` Возбуждается любой из функций при обнаружении ошибки. ## 14.1.2. Диалекты и параметры форматирования Чтобы упростить задание формата входных и выходных записей, определённые параметры форматирования группируются в диалекты. Диалект – это подкласс класса [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect), имеющий набор определённых методов и единственный метод `validate()`. При создании объектов [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader) или [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer) программист может указать в качестве параметра dialect строку или подкласс класса [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect). В дополнение к параметру *dialect* или вместо него программист может также указать отдельные параметры форматирования, имена которых совпадают с атрибутами класса [`Dialect`](https://python-all.ru/3.6/library/csv.html#csv.Dialect), определёнными ниже. Диалекты поддерживают следующие атрибуты: #### `Dialect.delimiter` Односимвольная строка, используемая для разделения полей. По умолчанию равна `','`. #### `Dialect.doublequote` Управляет тем, как должны заключаться в кавычки экземпляры *quotechar*, встречающиеся внутри поля. Когда [`True`](https://python-all.ru/3.6/library/constants.html#True), символ удваивается. Когда [`False`](https://python-all.ru/3.6/library/constants.html#False), *escapechar* используется в качестве префикса для *quotechar*. По умолчанию [`True`](https://python-all.ru/3.6/library/constants.html#True). При выводе, если *doublequote* равно [`False`](https://python-all.ru/3.6/library/constants.html#False) и *escapechar* не задан, возбуждается [`Error`](https://python-all.ru/3.6/library/csv.html#csv.Error), если в поле обнаружен *quotechar*. #### `Dialect.escapechar` Односимвольная строка, используемая объектом writer для экранирования *разделителя*, если для *quoting* установлено значение [`QUOTE_NONE`](https://python-all.ru/3.6/library/csv.html#csv.QUOTE_NONE), и *quotechar*, если *doublequote* равно [`False`](https://python-all.ru/3.6/library/constants.html#False). При чтении *escapechar* снимает особое значение со следующего символа. По умолчанию [`None`](https://python-all.ru/3.6/library/constants.html#None), что отключает экранирование. #### `Dialect.lineterminator` Строка, используемая для завершения строк, создаваемых [`writer`](https://python-all.ru/3.6/library/csv.html#csv.writer). По умолчанию равна `'\r\n'`. > **Примечание** > > Модуль [`reader`](https://python-all.ru/3.6/library/csv.html#csv.reader) жёстко запрограммирован распознавать `'\r'` или `'\n'` как конец строки и игнорировать *lineterminator*. В будущем это поведение может измениться. #### `Dialect.quotechar` Односимвольная строка, используемая для заключения в кавычки полей, содержащих специальные символы, такие как *разделитель* или *quotechar*, или содержащих символы новой строки. По умолчанию `'"'`. #### `Dialect.quoting` Управляет тем, когда кавычки должны генерироваться писателем (writer) и распознаваться читателем (reader). Может принимать любое из значений констант `QUOTE_*` (см. раздел [Содержание модуля](https://python-all.ru/3.6/library/csv.html#csv-contents)); по умолчанию [`QUOTE_MINIMAL`](https://python-all.ru/3.6/library/csv.html#csv.QUOTE_MINIMAL). #### `Dialect.skipinitialspace` Когда [`True`](https://python-all.ru/3.6/library/constants.html#True), пробелы сразу после *разделителя* игнорируются. По умолчанию [`False`](https://python-all.ru/3.6/library/constants.html#False). #### `Dialect.strict` Если `True`, при некорректном CSV-вводе вызывается исключение [`Error`](https://python-all.ru/3.6/library/csv.html#csv.Error). По умолчанию `False`. ## 14.1.3. Объекты Reader Объекты reader (экземпляры [`DictReader`](https://python-all.ru/3.6/library/csv.html#csv.DictReader) и объекты, возвращаемые функцией [`reader()`](https://python-all.ru/3.6/library/csv.html#csv.reader)) имеют следующие открытые методы: #### `csvreader.__next__()` Возвращает следующую строку итерируемого объекта reader в виде списка (если объект был возвращён из [`reader()`](https://python-all.ru/3.6/library/csv.html#csv.reader)) или словаря (если это экземпляр [`DictReader`](https://python-all.ru/3.6/library/csv.html#csv.DictReader)), разобранную в соответствии с текущим диалектом. Обычно это следует вызывать как `next(reader)`. Объекты reader имеют следующие открытые атрибуты: #### `csvreader.dialect` Доступное только для чтения описание диалекта, используемого синтаксическим анализатором. #### `csvreader.line_num` Количество строк, прочитанных из итератора-источника. Это число не совпадает с количеством возвращённых записей, так как записи могут занимать несколько строк. Объекты DictReader имеют следующий открытый атрибут: #### `csvreader.fieldnames` Если этот атрибут не был передан в качестве параметра при создании объекта, он инициализируется при первом обращении или при чтении первой записи из файла. ## 14.1.4. Объекты Writer Объекты `Writer` (экземпляры [`DictWriter`](https://python-all.ru/3.6/library/csv.html#csv.DictWriter) и объекты, возвращаемые функцией [`writer()`](https://python-all.ru/3.6/library/csv.html#csv.writer)) имеют следующие открытые методы. Параметр *row* должен быть итерацией строк или чисел для объектов `Writer` и словарём, сопоставляющим имена полей со строками или числами (предварительно пропустив их через [`str()`](https://python-all.ru/3.6/library/stdtypes.html#str)) для объектов [`DictWriter`](https://python-all.ru/3.6/library/csv.html#csv.DictWriter). Обратите внимание, что комплексные числа записываются в круглых скобках. Это может вызвать некоторые проблемы для других программ, читающих CSV-файлы (если они вообще поддерживают комплексные числа). #### `csvwriter.writerow(row)` Записывает параметр *row* в файловый объект writer, отформатировав в соответствии с текущим диалектом. Изменено в версии 3.5: Добавлена поддержка произвольных итераций. #### `csvwriter.writerows(rows)` Записывает все элементы из *rows* (итерацию объектов *row*, как описано выше) в файловый объекта средства записи, форматируя в соответствии с текущим диалектом. Объекты Writer имеют следующий открытый атрибут: #### `csvwriter.dialect` Описание диалекта, используемого средством записи, доступное только для чтения. Объекты DictWriter имеют следующий открытый метод: #### `DictWriter.writeheader()` Записывает строку с названиями полей (как указано в конструкторе). Новое в версии 3.2. ## 14.1.5. Примеры Простейший пример чтения CSV-файла: ```python import csv with open('some.csv', newline='') as f: reader = csv.reader(f) for row in reader: print(row) ``` Чтение файла в альтернативном формате: ```python import csv with open('passwd', newline='') as f: reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE) for row in reader: print(row) ``` Соответствующий простейший пример записи: ```python import csv with open('some.csv', 'w', newline='') as f: writer = csv.writer(f) writer.writerows(someiterable) ``` Поскольку [`open()`](https://python-all.ru/3.6/library/functions.html#open) используется для открытия CSV-файла для чтения, файл по умолчанию будет декодирован в Unicode с использованием системной кодировки по умолчанию (см. [`locale.getpreferredencoding()`](https://python-all.ru/3.6/library/locale.html#locale.getpreferredencoding)). Чтобы декодировать файл с другой кодировкой, используйте аргумент `encoding` функции open: ```python import csv with open('some.csv', newline='', encoding='utf-8') as f: reader = csv.reader(f) for row in reader: print(row) ``` То же самое относится к записи в кодировке, отличной от системной: укажите аргумент encoding при открытии выходного файла. Регистрация нового диалекта: ```python import csv csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE) with open('passwd', newline='') as f: reader = csv.reader(f, 'unixpwd') ``` Чуть более продвинутое использование reader – перехват и сообщение об ошибках: ```python 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)) ``` И хотя модуль напрямую не поддерживает разбор строк, это можно легко сделать: ```python import csv for row in csv.reader(['one,two,three']): print(row) ``` Сноски **1([1](https://python-all.ru/3.6/library/csv.html#id1),[2](https://python-all.ru/3.6/library/csv.html#id2))** Если `newline=''` не указан, символы новой строки внутри полей в кавычках не будут интерпретироваться правильно, и на платформах, использующих `\r\n` окончания строк, при записи будет добавлен лишний `\r`. Всегда безопасно указывать `newline=''`, поскольку модуль csv выполняет свою собственную ([универсальную](https://python-all.ru/3.6/glossary.html#term-universal-newlines)) обработку символов новой строки.