pandas.read_table

pandas.read_table(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=False, 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]

Чтение общего текстового файла с разделителями в 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:строка, по умолчанию ‘\t’ (табуляция)

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

delimiter:строка, по умолчанию None

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

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

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

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

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

index_col:целое число, строка, последовательность целых чисел / строк или False, необязательно, по умолчанию None

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

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

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:логическое значение, по умолчанию False

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

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

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

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

Устарело начиная с версии 1.4.0: Используйте списковое включение для столбцов DataFrame после вызова read_csv.

mangle_dupe_cols:логическое значение, по умолчанию 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:логическое значение, по умолчанию False

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

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

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

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

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

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

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

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

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

Дополнительные строки, распознаваемые как NA/NaN. Если передан словарь, он задаёт конкретные значения 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’, ‘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_filter=False может повысить производительность при чтении больших файлов.

verbose:логическое значение, по умолчанию False

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

skip_blank_lines:логическое значение, по умолчанию True

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

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

Возможны следующие варианты поведения:

• логическое значение. Если True -> попытаться разобрать индекс.

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

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

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

Если столбец или индекс нельзя представить в виде массива дат, например из-за нераспознаваемого значения или смешения часовых поясов, столбец или индекс будут возвращены без изменений с типом данных object. Для нестандартного разбора дат используйте 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 (length 1), optional

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

quotechar:str (length 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 (length 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_table('data.csv')