pandas.read_csv

pandas.read_csv(filepath_or_buffer, sep=_NoDefault.no_default, delimiter=None, header='infer', names=_NoDefault.no_default, index_col=None, usecols=None, squeeze=None, prefix=_NoDefault.no_default, mangle_dupe_cols=True, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skipinitialspace=False, skiprows=None, skipfooter=0, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=False, skip_blank_lines=True, parse_dates=None, infer_datetime_format=False, keep_date_col=False, date_parser=None, dayfirst=False, cache_dates=True, iterator=False, chunksize=None, compression='infer', thousands=None, decimal='.', lineterminator=None, quotechar='"', quoting=0, doublequote=True, escapechar=None, comment=None, encoding=None, encoding_errors='strict', dialect=None, error_bad_lines=None, warn_bad_lines=None, on_bad_lines=None, delim_whitespace=False, low_memory=True, memory_map=False, float_precision=None, storage_options=None)[source]

Чтение файла значений, разделённых запятыми (csv), в DataFrame.

Также поддерживает необязательное итеративное чтение или разделение файла на фрагменты.

Дополнительную помощь можно найти в онлайн-документации по Инструментам ввода-вывода.

Параметры

filepath_or_buffer:str, объект пути или объект типа «потоковый буфер»

Приемлемый любой допустимый путь в виде строки. Строка может быть URL-адресом. Допустимые схемы URL включают http, ftp, s3, gs и file. Для URL-адресов файлов ожидается хост. Локальный файл может быть: file://localhost/path/to/table.csv.

Если вы хотите передать объект пути, pandas принимает любой os.PathLike.

Под объектом типа «потоковый буфер» мы подразумеваем объекты с методом read(), например, дескриптор файла (например, с помощью встроенной функции open или StringIO).

sep:str, по умолчанию ‘,’

Разделитель. Если sep равен None, движок C не может автоматически определить разделитель, но движок Python может, что означает, что последний будет использоваться и автоматически определит разделитель с помощью встроенного инструмента анализа Python, csv.Sniffer. Кроме того, разделители, длина которых больше 1 символа и отличающиеся от '\s+', будут интерпретироваться как регулярные выражения и также будут принудительно использовать движок Python. Обратите внимание, что разделители-регулярные выражения могут игнорировать данные в кавычках. Пример регулярного выражения: '\r\t'.

delimiter:str, по умолчанию None

Псевдоним для sep.

header:int, список целых чисел, None, по умолчанию ‘infer’

Номер(а) строки, используемый в качестве имён столбцов, и начало данных. По умолчанию имена столбцов вычисляются: если имена не переданы, поведение идентично header=0 и имена столбцов вычисляются из первой строки файла, если имена столбцов явно переданы, то поведение идентично header=None. Явно передайте header=0 , чтобы иметь возможность заменить существующие имена. Заголовок может быть списком целых чисел, указывающих на расположение строк для многоуровневого индекса столбцов, например, [0, 1, 3]. Промежуточные строки, которые не указаны, будут пропущены (например, 2 в этом примере пропущена). Обратите внимание, что этот параметр игнорирует прокомментированные строки и пустые строки, если skip_blank_lines=True, поэтому header=0 обозначает первую строку данных, а не первую строку файла.

names:последовательность, необязательно

Список имён столбцов для использования. Если файл содержит строку заголовка, то вы должны явно передать header=0 для переопределения имён столбцов. Дубликаты в этом списке запрещены.

index_col:int, str, последовательность int / str или False, необязательно, по умолчанию None

Столбец(ы) для использования в качестве меток строк DataFrame, заданный либо именем строки, либо индексом столбца. Если задана последовательность int/str, используется MultiIndex.

Примечание: index_col=False может использоваться для принудительного отказа pandas от использования первого столбца в качестве индекса, например, при наличии поврежденного файла с разделителями в конце каждой строки.

usecols:последовательность или вызываемый объект, необязательно

Возвращает подмножество столбцов. Если это последовательность, все элементы должны быть либо позиционными (т. е. целочисленными индексами столбцов документа), либо строками, соответствующими именам столбцов, предоставленным либо пользователем в names, либо выведенным из строки(ок) заголовка документа. Если names , то строки(ы) заголовка документа не учитываются. Например, допустимым списковым параметром usecols будет [0, 1, 2] или ['foo', 'bar', 'baz']. Порядок элементов игнорируется, поэтому usecols=[0, 1] эквивалентно [1, 0]. Чтобы создать DataFrame из data с сохранением порядка элементов, используйте pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']] для столбцов в порядке ['foo', 'bar'] или pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']] для порядка ['bar', 'foo'].

Если это вызываемый объект, вызываемая функция будет оцениваться по именам столбцов, возвращая имена, где вызываемая функция принимает значение True. Примером допустимого вызываемого аргумента будет lambda x: x.upper() in ['AAA', 'BBB', 'DDD']. Использование этого параметра приводит к значительно более быстрому парсингу и меньшему использованию памяти.

squeeze:bool, по умолчанию False

Если проанализированные данные содержат только один столбец, то возвращается Series.

Устаревшее с версии 1.4.0: Добавьте .squeeze("columns") к вызову read_csv для сжатия данных.

prefix:str, необязательно

Префикс, добавляемый к номерам столбцов, если заголовок отсутствует, например, ‘X’ для X0, X1, …

Устаревшее с версии 1.4.0: Используйте генератор списков по столбцам DataFrame после вызова read_csv.

mangle_dupe_cols:bool, по умолчанию True

Дублирующиеся столбцы будут указаны как ‘X’, ‘X.1’, …’X.N’, а не ‘X’…’X’. Передача False приведет к перезаписи данных, если в столбцах есть дублирующиеся имена.

Устаревшее с версии 1.5.0: Не реализовано, вместо этого будет добавлен новый аргумент для указания шаблона имён дублирующихся столбцов

dtype:Имя типа или словарь столбец->тип, необязательно

Тип данных для данных или столбцов. Например, {‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’}. Используйте str или object вместе с соответствующими настройками na_values, чтобы сохранить и не интерпретировать тип данных. Если заданы преобразователи, они будут применяться ВМЕСТО преобразования типа данных.

Новое в версии 1.5.0: Добавлена поддержка defaultdict. Укажите defaultdict в качестве входных данных, где значение по умолчанию определяет тип данных столбцов, которые не указаны явно.

engine:{‘c’, ‘python’, ‘pyarrow’}, необязательно

Движок парсера для использования. Движки C и pyarrow быстрее, а движок python в настоящее время более функционален. Многопоточность в настоящее время поддерживается только движком pyarrow.

Новое в версии 1.4.0: Движок “pyarrow” был добавлен как экспериментальный движок, и некоторые функции не поддерживаются или могут работать неправильно с этим движком.

converters:словарь, необязательно

Словарь функций для преобразования значений в определённых столбцах. Ключи могут быть либо целыми числами, либо метками столбцов.

true_values:список, необязательно

Значения, которые следует рассматривать как True.

false_values:список, необязательно

Значения, которые следует рассматривать как False.

skipinitialspace:bool, по умолчанию False

Пропуск пробелов после разделителя.

skiprows:последовательность, целое число или вызываемый объект, необязательно

Номера строк для пропуска (с индексом 0) или количество строк для пропуска (целое число) в начале файла.

Если это вызываемый объект, вызываемая функция будет оцениваться по индексам строк, возвращая True, если строка должна быть пропущена, и False в противном случае. Примером допустимого вызываемого аргумента будет lambda x: x in [0, 2].

skipfooter:int, по умолчанию 0

Количество строк в конце файла, которые нужно пропустить (не поддерживается с engine='c').

nrows:int, необязательно

Количество строк файла для чтения. Полезно для чтения фрагментов больших файлов.

na_values:скаляр, строка, последовательность или словарь, необязательно

Дополнительные строки, распознаваемые как NA/NaN. Если передан словарь, то для каждого столбца. По умолчанию следующие значения интерпретируются как NaN: ‘’, ‘#N/A’, ‘#N/A N/A’, ‘#NA’, ‘-1.#IND’, ‘-1.#QNAN’, ‘-NaN’, ‘-nan’, ‘1.#IND’, ‘1.#QNAN’, ‘<NA>’, ‘N/A’, ‘NA’, ‘NULL’, ‘NaN’, ‘n/a’, ‘nan’, ‘null’.

keep_default_na:bool, по умолчанию True

Учитывать ли значения NaN по умолчанию при анализе данных. В зависимости от того, передан ли na_values, поведение следующее:

• Если keep_default_na True, и na_values заданы, na_values добавляются к значениям NaN по умолчанию, используемым для анализа.

• Если keep_default_na True, и na_values не заданы, для анализа используются только значения NaN по умолчанию.

• Если keep_default_na False, и na_values заданы, для анализа используются только значения NaN, указанные в na_values.

• Если keep_default_na False, и na_values не заданы, никакие строки не будут анализироваться как NaN.

Обратите внимание, что если na_filter задан как False, параметры keep_default_na и na_values будут проигнорированы.

na_filter:bool, по умолчанию True

Обнаружение маркеров отсутствующих значений (пустых строк и значений na_values). В данных без каких-либо значений NA передача na_filter=False может улучшить производительность чтения большого файла.

verbose:bool, по умолчанию False

Указывает количество значений NA, помещённых в нечисловые столбцы.

skip_blank_lines:bool, по умолчанию True

Если True, пропускает пустые строки, а не интерпретирует их как значения NaN.

parse_dates:bool или список целых чисел или имён или список списков или словарь, по умолчанию False

Поведение следующее:

• boolean. Если True -> попытка распарсить индекс.

• список целых чисел или имён. Например, если [1, 2, 3] -> попытка распарсить столбцы 1, 2, 3 как отдельные столбцы дат.

• список списков. Например, если [[1, 3]] -> объединить столбцы 1 и 3 и распарсить как один столбец дат.

• словарь, например, {‘foo’ : [1, 3]} -> распарсить столбцы 1, 3 как даты и назвать результат ‘foo’

Если столбец или индекс не может быть представлен как массив дат, например, из-за нераспознаваемого значения или смешения часовых поясов, столбец или индекс будут возвращены без изменений как тип данных объекта. Для нестандартного парсинга дат используйте pd.to_datetime после pd.read_csv. Чтобы распарсить индекс или столбец со смешанными часовыми поясами, укажите date_parser как частично применённую pandas.to_datetime() с utc=True. Более подробно см. Парсинг CSV со смешанными часовыми поясами.

Примечание: для дат в формате iso8601 существует быстрый метод.

infer_datetime_format:bool, default False

Если True и parse_dates включены, pandas попытается определить формат строк дат в столбцах и, если это удастся, переключится на более быстрый метод их парсинга. В некоторых случаях это может увеличить скорость парсинга в 5-10 раз.

keep_date_col:bool, default False

Если True и parse_dates определяет объединение нескольких столбцов, то сохранить исходные столбцы.

date_parser:function, optional

Функция для преобразования последовательности столбцов строк в массив экземпляров дат. По умолчанию используется dateutil.parser.parser для преобразования. Pandas попытается вызвать date_parser тремя различными способами, переходя к следующему, если произойдет исключение: 1) Передать один или несколько массивов (как определено parse_dates) в качестве аргументов; 2) склеить (по строкам) строковые значения из столбцов, определённых parse_dates, в один массив и передать его; и 3) вызвать date_parser один раз для каждой строки, используя одну или несколько строк (соответствующих столбцам, определённым parse_dates) в качестве аргументов.

dayfirst:bool, default False

Даты в формате ДД/ММ, международный и европейский формат.

cache_dates:bool, default True

Если True, использовать кэш уникальных преобразованных дат для применения преобразования дат. Может существенно ускорить парсинг дублирующихся строк дат, особенно с часовыми поясами.

Добавлена в версии 0.25.0.

iterator:bool, default False

Возвращает объект TextFileReader для итерации или получения фрагментов с get_chunk().

Изменено в версии 1.2: TextFileReader — это менеджер контекста.

chunksize:int, optional

Возвращает объект TextFileReader для итерации. См. документацию по инструментам ввода-вывода для получения дополнительной информации о iterator и chunksize.

Изменено в версии 1.2: TextFileReader — это менеджер контекста.

compression:str or dict, default ‘infer’

Для онлайн-распаковки данных на диске. Если ‘infer’ и ‘filepath_or_buffer’ — это путь, то распознать сжатие по следующим расширениям: ‘.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ или ‘.tar.bz2’ (иначе без сжатия). При использовании ‘zip’ или ‘tar’ файл ZIP должен содержать только один файл данных для чтения. Установите в None для отсутствия распаковки. Также может быть словарь с ключом 'method', установленным в один из {'zip', 'gzip', 'bz2', 'zstd', 'tar'} и другие пары ключ-значение передаются в zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor или tarfile.TarFile, соответственно. Например, для распаковки Zstandard с использованием пользовательского словаря сжатия можно передать: compression={'method': 'zstd', 'dict_data': my_compression_dict}.

Добавлена в версии 1.5.0: Поддержка файлов .tar.

Изменено в версии 1.4.0: Поддержка Zstandard.

thousands:str, optional

Разделитель тысяч.

decimal:str, default ‘.’

Символ, распознаваемый как десятичная точка (например, используйте ‘,’ для европейских данных).

lineterminator:str (длина 1), optional

Символ для разделения файла на строки. Действителен только для парсера C.

quotechar:str (длина 1), optional

Символ, используемый для обозначения начала и конца цитируемого элемента. Цитата может содержать разделитель, и он будет пропущен.

quoting:int or csv.QUOTE_* instance, default 0

Управление поведением цитирования полей по csv.QUOTE_* константам. Используйте один из QUOTE_MINIMAL (0), QUOTE_ALL (1), QUOTE_NONNUMERIC (2) или QUOTE_NONE (3).

doublequote:bool, default True

Когда quotechar указан и quoting не QUOTE_NONE, укажите, следует ли интерпретировать два последовательных элемента quotechar ВНУТРИ поля как один quotechar элемент.

escapechar:str (длина 1), optional

Строка длиной один символ, используемая для экранирования других символов.

comment:str, optional

Указывает, что остальная часть строки не должна обрабатываться. Если он находится в начале строки, строка полностью пропускается. Этот параметр должен быть одним символом. Как и пустые строки (пока skip_blank_lines=True), полностью комментируемые строки игнорируются параметром header, но не skiprows. Например, если comment='#', парсинг #empty\na,b,c\n1,2,3 с header=0 приведёт к тому, что ‘a,b,c’ будет считаться заголовком.

encoding:str, optional

Кодировка для использования для UTF при чтении/записи (например, ‘utf-8’). Список стандартных кодировок Python .

Изменено в версии 1.2: Когда encoding является None, errors="replace" передаётся в open(). В противном случае, errors="strict" передаётся в open(). Это поведение ранее было только в случае engine="python".

Изменено в версии 1.3.0: encoding_errors — новый аргумент. encoding больше не влияет на обработку ошибок кодирования.

encoding_errors:str, optional, default “strict”

Как обрабатывать ошибки кодирования. Список возможных значений .

Добавлена в версии 1.3.0.

dialect:str or csv.Dialect, optional

Если указан, этот параметр переопределит значения (по умолчанию или нет) для следующих параметров: delimiter, doublequote, escapechar, skipinitialspace, quotechar и quoting. Если требуется переопределить значения, будет выведено предупреждение ParserWarning. См. документацию csv.Dialect для получения более подробной информации.

error_bad_lines:bool, optional, default None

Строки с слишком многими полями (например, строка csv со слишком многими запятыми) по умолчанию вызывают исключение, и DataFrame не возвращается. Если False, эти «плохие строки» будут удалены из возвращаемого DataFrame.

Устарело начиная с версии 1.3.0: Вместо параметра on_bad_lines необходимо использовать для указания поведения при обнаружении плохой строки.

warn_bad_lines:bool, optional, default None

Если error_bad_lines — False, а warn_bad_lines — True, для каждой «плохой строки» будет выведено предупреждение.

Устарело начиная с версии 1.3.0: Вместо параметра on_bad_lines необходимо использовать для указания поведения при обнаружении плохой строки.

on_bad_lines:{‘error’, ‘warn’, ‘skip’} or callable, default ‘error’

Указывает, что делать при обнаружении плохой строки (строки со слишком многими полями). Допустимые значения:

• ‘error’, выдать исключение при обнаружении плохой строки.

• ‘warn’, выдать предупреждение при обнаружении плохой строки и пропустить эту строку.

• ‘skip’, пропустить плохие строки без вывода предупреждений или исключений при их обнаружении.

Добавлена в версии 1.3.0.

Добавлена в версии 1.4.0:

• callable, функция с сигнатурой (bad_line: list[str]) -> list[str] | None для обработки одной плохой строки. bad_line — это список строк, разделенных sep. Если функция возвращает None, плохая строка будет пропущена. Если функция возвращает новый список строк с количеством элементов больше ожидаемого, будет выведено предупреждение ParserWarning при удалении дополнительных элементов. Поддерживается только когда engine="python"

delim_whitespace:bool, default False

Указывает, будет ли пробел (например, ' ' или '    ') использоваться в качестве разделителя. Эквивалентно установлению sep='\s+'. Если этот параметр установлен в True, для параметра delimiter ничего передавать не нужно.

low_memory:bool, default True

Внутренне обрабатывает файл частями, что приводит к меньшему использованию памяти при парсинге, но, возможно, к смешанному типу вывода. Чтобы избежать смешанного типа, установите False или укажите тип с параметром dtype. Обратите внимание, что весь файл все равно читается в одну DataFrame. Используйте параметр chunksize или iterator, чтобы возвращать данные частями. (Действительно только с C-парсером).

memory_map:bool, default False

Если для filepath_or_buffer указан путь к файлу, отображает объект файла непосредственно в памяти и получает доступ к данным напрямую. Использование этого параметра может повысить производительность, так как больше нет необходимости в операциях ввода-вывода.

float_precision:str, optional

Указывает, какой преобразователь C-движок должен использовать для значений с плавающей точкой. Доступные параметры: None или ‘high’ для обычного преобразователя, ‘legacy’ для оригинального преобразователя pandas с меньшей точностью и ‘round_trip’ для преобразователя с обратной совместимостью.

Изменено в версии 1.2.

storage_options:dict, optional

Дополнительные параметры, имеющие смысл для конкретного подключения к хранилищу, например, хост, порт, имя пользователя, пароль и т. д. Для HTTP(S)-URL-адресов пары ключ-значение передаются в urllib.request.Request в качестве параметров заголовков. Для других URL-адресов (например, начинающихся с «s3://» и «gcs://») пары ключ-значение передаются в fsspec.open. Дополнительную информацию см. в fsspec и urllib. Более подробные примеры параметров хранилища см. здесь.

Введено в версии 1.2.

Возвращает

DataFrame или TextParser

Файл с разделителями (csv) возвращается как двумерная структура данных с маркированными осями.

См. также

DataFrame.to_csv

Запись DataFrame в файл с разделителями (csv).

read_csv

Чтение файла с разделителями (csv) в DataFrame.

read_fwf

Чтение таблицы с фиксированной шириной строк в DataFrame.

Примеры

>>> pd.read_csv('data.csv')