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, 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=_NoDefault.no_default, skip_blank_lines=True, parse_dates=None, infer_datetime_format=_NoDefault.no_default, keep_date_col=_NoDefault.no_default, date_parser=_NoDefault.no_default, date_format=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, on_bad_lines='error', delim_whitespace=_NoDefault.no_default, low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=_NoDefault.no_default)[source]

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

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

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

Параметры:

filepath_or_buffer:строка, объект пути или объект-поток

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

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

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

sep:строка, по умолчанию ‘,’

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

delimiter:строка, необязательно

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

header:целое число, последовательность целых чисел, ‘infer’ или None, по умолчанию ‘infer’

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

names:последовательность хешируемых объектов, необязательно

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

index_col:хешируемый объект, последовательность хешируемых объектов или False, необязательно

Столбец(ы) для использования в качестве метки(ок) строки, обозначенный либо метками столбцов, либо индексами столбцов. Если задана последовательность меток или индексов, 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']. Использование этого параметра приводит к значительно более быстрому времени обработки и меньшему использованию памяти.

dtype:тип данных или словарь {хешируемый объект: тип данных}, необязательно

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

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

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

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

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

converters:словарь {хешируемый объект: вызываемая функция}, необязательно

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

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

Значения, рассматриваемые как True в дополнение к вариантам значений ‘True’ с учетом регистра.

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

Значения, рассматриваемые как False в дополнение к вариантам значений ‘False’ с учетом регистра.

skipinitialspace:булево, по умолчанию False

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

skiprows:целое число, список целых чисел или вызываемая функция, необязательно

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

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

skipfooter:целое число, по умолчанию 0

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

nrows:целое число, необязательно

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

na_values:хешируемый объект, итерируемый объект или словарь {хешируемый объект: итерируемый объект}, необязательно

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

keep_default_na:булево, по умолчанию 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:булево, по умолчанию True

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

verbose:булево, по умолчанию False

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

Устарело начиная с версии 2.2.0.

skip_blank_lines:булево, по умолчанию True

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

parse_dates:булево, список хешируемых объектов, список списков или словарь {хешируемый объект: список}, по умолчанию False

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

• bool. Если True -> попытаться разобрать индекс. Примечание: Автоматически устанавливается в True, если были переданы аргументы date_format или date_parser.

• list столбцов int или имён. Например, если [1, 2, 3] -> попытаться разобрать столбцы 1, 2, 3 каждый как отдельный столбец даты.

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

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

Если столбец или индекс не может быть представлен как массив datetime, например, из-за неразборчивого значения или смешения часовых поясов, столбец или индекс будут возвращены без изменений как тип данных object. Для нестандартного разбора datetime, используйте to_datetime() после read_csv().

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

infer_datetime_format:bool, default False

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

Устарело начиная с версии 2.0.0: Строгая версия этого аргумента теперь является стандартной; передача его не имеет эффекта.

keep_date_col:bool, default False

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

date_parser:Callable, optional

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

Устарело начиная с версии 2.0.0: Используйте date_format вместо этого, или считайте как object и затем применяйте to_datetime() по мере необходимости.

date_format:str or dict of column -> format, optional

Формат для разбора дат при совместном использовании с parse_dates. Формат strftime для разбора времени, например, "%d/%m/%Y". См. документацию strftime для получения дополнительной информации об вариантах, хотя обратите внимание, что "%f" будет разбирать значения до наносекунд. Также можно передать:

• “ISO8601”, для разбора любой ISO8601

  строки времени (не обязательно в точно таком же формате);

• “mixed”, для определения формата для каждого элемента по отдельности. Это рискованно,

  и вы, вероятно, должны использовать его вместе с dayfirst.

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

dayfirst:bool, default False

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

cache_dates:bool, default True

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

iterator:bool, default False

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

chunksize:int, optional

Количество строк, считываемых из файла за фрагмент. Передача значения приведет к возврату функции объекта TextFileReader для итерации. См. документацию IO Tools для получения дополнительной информации о iterator и chunksize.

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', 'xz', 'tar'} и другие пары ключ-значение передаются zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor, lzma.LZMAFile или tarfile.TarFile, соответственно. Например, для распаковки Zstandard с использованием пользовательского словаря сжатия можно передать: compression={'method': 'zstd', 'dict_data': my_compression_dict}.

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

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

thousands:str (length 1), optional

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

decimal:str (length 1), default ‘.’

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

lineterminator:str (length 1), optional

Символ, используемый для обозначения конца строки. Действителен только для парсера C.

quotechar:str (length 1), optional

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

quoting:{0 or csv.QUOTE_MINIMAL, 1 or csv.QUOTE_ALL, 2 or csv.QUOTE_NONNUMERIC, 3 or csv.QUOTE_NONE}, default csv.QUOTE_MINIMAL

Управление поведением цитирования полей согласно csv.QUOTE_* константам. По умолчанию значение csv.QUOTE_MINIMAL (т.е. 0), что подразумевает, что цитируются только поля, содержащие специальные символы (например, символы, определённые в quotechar, delimiter, или lineterminator.

doublequote:bool, default True

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

escapechar:str (length 1), optional

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

comment:str (length 1), optional

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

encoding:str, optional, default ‘utf-8’

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

encoding_errors:str, optional, default ‘strict’

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

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

dialect:str or csv.Dialect, optional

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

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

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

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

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

• 'skip', пропустить плохие строки без генерации исключений или предупреждений.

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

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

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

Изменено в версии 2.2.0:

• Вызываемый объект, функция со сигнатурой, как описано в документации pyarrow, при engine='pyarrow'

delim_whitespace:bool, default False

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

Устарело начиная с версии 2.2.0: Используйте sep="\s+" вместо этого.

low_memory:bool, default True

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

memory_map:bool, default False

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

float_precision:{‘high’, ‘legacy’, ‘round_trip’}, optional

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

storage_options:dict, optional

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

dtype_backend:{‘numpy_nullable’, ‘pyarrow’}, default ‘numpy_nullable’

Тип данных, применяемый к результирующей DataFrame (ещё экспериментально). Поведение следующее:

• "numpy_nullable": возвращает DataFrame с поддержкой типов с возможностью NULL (по умолчанию).

• "pyarrow": возвращает ArrowDtype DataFrame с поддержкой NULL, основанный на pyarrow.

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

Возвращаемое значение:

DataFrame или TextFileReader

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

См. также

DataFrame.to_csv

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

read_table

Чтение общего файла с разделителями в DataFrame.

read_fwf

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

Примеры

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