pandas.read_table

pandas.read_table(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=False, 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>)[исходный код]

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

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

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

Параметры:

filepath_or_buffer:str, path object or file-like object

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

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

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

sep:str, default ‘\t’ (tab-stop)

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

delimiter:str, optional

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

header:int, Sequence of int, ‘infer’ or None, default ‘infer’

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

names:Sequence of Hashable, optional

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

index_col:Hashable, Sequence of Hashable or False, optional

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

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

usecols:Sequence of Hashable or Callable, optional

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

Тип данных, применяемый ко всему набору данных или к отдельным столбцам. Например, {'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’}, optional

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

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

converters:dict of {Hashable:Callable}, optional

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

true_values:list, optional

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

false_values:list, optional

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

skipinitialspace:bool, default False

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

skiprows:int, list of int or Callable, optional

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

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

skipfooter:int, default 0

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

nrows:int, optional

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

na_values:Hashable, Iterable of Hashable or dict of {Hashable:Iterable}, optional

Дополнительные строки, которые следует распознавать как 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, default 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, default True

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

verbose:bool, default False

Показывать количество значений NA, добавленных в нечисловые столбцы.

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

skip_blank_lines:bool, default True

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

parse_dates:bool, list of Hashable, list of lists or dict of {Hashable:list}, default 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().

Примечание: для дат в формате ISO 8601 предусмотрен быстрый алгоритм.

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

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

cache_dates:bool, default True

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

iterator:bool, default False

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

chunksize:int, optional

Количество строк файла для чтения в каждом фрагменте. При передаче значения функция вернет объект TextFileReader для итерации. Подробнее о 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

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

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

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

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

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

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

Возвращает:

DataFrame or TextFileReader

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

См. также

DataFrame.to_csv

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

read_csv

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

read_fwf

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

Примеры

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