pandas.read_csv

pandas.read_csv(filepath_or_buffer, *, sep=<no_default>, delimiter=None, header='infer', names=<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=<no_default>, skip_blank_lines=True, parse_dates=None, infer_datetime_format=<no_default>, keep_date_col=<no_default>, date_parser=<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=<no_default>, low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=<no_default>)[исходный код]

Прочитать файл со значениями, разделёнными запятыми (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, необязательно

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

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

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

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

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

index_col:Hashable, последовательность Hashable или False, необязательно

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

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

usecols:последовательность Hashable или Callable, необязательно

Подмножество столбцов для выбора, задаваемое либо метками столбцов, либо индексами столбцов. Если передано значение, похожее на список, все элементы должны быть либо позиционными (то есть целочисленными индексами столбцов документа), либо строками, соответствующими именам столбцов, указанным пользователем в 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:dtype или dict вида {Hashable: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:dict вида {Hashable:Callable}, необязательно

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

true_values:list, необязательно

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

false_values:list, необязательно

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

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

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

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

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

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

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

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

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

Количество строк файла для чтения. Удобно при чтении частей больших файлов.

na_values:Hashable, Iterable из Hashable или dict вида {Hashable:Iterable}, необязательно

Дополнительные строки, которые следует распознавать как 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: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, помещённых в нечисловые столбцы.

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

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

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

parse_dates:bool, список Hashable, список списков или dict вида {Hashable:list}, по умолчанию 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, по умолчанию False

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

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

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

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

date_parser:Callable, необязательно

Функция для преобразования последовательности строковых столбцов в массив экземпляров 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 или dict вида столбец -> формат, необязательно

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

• “ISO8601” — для разбора любой строки времени формата ISO8601

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

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

  и, вероятно, этот вариант следует использовать вместе с dayfirst.

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

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

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

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

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

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

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

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

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

compression:str или dict, по умолчанию ‘infer’

Для распаковки данных с диска на лету. Если задано ‘infer’ и ‘filepath_or_buffer’ является значением, похожим на путь, тип сжатия определяется по следующим расширениям: ‘.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ или ‘.tar.bz2’ (в противном случае сжатие не используется). При использовании ‘zip’ или ‘tar’ ZIP-архив должен содержать только один файл данных для чтения. Установите значение None, чтобы отключить распаковку. Также можно передать dict с ключом '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 (длина 1), необязательно

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

decimal:str (длина 1), по умолчанию ‘.’

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

lineterminator:str (длина 1), необязательно

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

quotechar:str (длина 1), необязательно

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

quoting:{0 или csv.QUOTE_MINIMAL, 1 или csv.QUOTE_ALL, 2 или csv.QUOTE_NONNUMERIC, 3 или csv.QUOTE_NONE}, по умолчанию csv.QUOTE_MINIMAL

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

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

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

escapechar:str (длина 1), необязательно

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

comment:str (длина 1), необязательно

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

encoding:str, необязательно, по умолчанию ‘utf-8’

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

encoding_errors:str, необязательно, по умолчанию ‘strict’

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

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

dialect:str или csv.Dialect, необязательно

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

on_bad_lines:{‘error’, ‘warn’, ‘skip’} или Callable, по умолчанию ‘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, по умолчанию False

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

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

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

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

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

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

float_precision:{‘high’, ‘legacy’, ‘round_trip’}, необязательно

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

storage_options:dict, необязательно

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

dtype_backend:{‘numpy_nullable’, ‘pyarrow’}, по умолчанию ‘numpy_nullable’

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

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

• "pyarrow": возвращает DataFrame с nullable-типами на основе pyarrow, ArrowDtype.

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

Возвращает:

DataFrame или TextFileReader

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

См. также

DataFrame.to_csv

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

read_table

Прочитать файл с произвольным разделителем в DataFrame.

read_fwf

Прочитать таблицу из строк фиксированной ширины в DataFrame.

Примеры

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