pandas.read_excel#

pandas.read_excel(io, sheet_name=0, *, header=0, names=None, index_col=None, usecols=None, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skiprows=None, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=False, parse_dates=False, date_parser=, date_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=, engine_kwargs=None)[источник]#

Прочитать файл Excel в pandas DataFrame.

Поддерживает xls, xlsx, Отладка C-расширений, xlsb, odf, ods и odt расширения файлов, читаемые из локальной файловой системы или URL. Поддерживает опцию чтения одного листа или списка листов.

Параметры:
iostr, bytes, ExcelFile, xlrd.Book, объект пути или файлоподобный объект

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

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

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

Устарело с версии 2.1.0: Передача байтовых строк устарела. Для чтения из байтовой строки оберните её в BytesIO объект.

sheet_namestr, int, list или None, по умолчанию 0

Строки используются для названий листов. Целые числа используются для позиций листов с нулевой индексацией (листы диаграмм не учитываются в позиции листа). Списки строк/целых чисел используются для запроса нескольких листов. Укажите None для получения всех рабочих листов.

Доступные варианты:

  • По умолчанию 0: 1-й лист как DataFrame

  • 1: 2-й лист как DataFrame

  • "Sheet1": Загрузить лист с именем "Sheet1"

  • [0, 1, "Sheet5"]: Загрузить первый, второй и лист с именем "Sheet5" как словарь DataFrame

  • None: Все рабочие листы.

headerint, список int, по умолчанию 0

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

namesмассивоподобный, по умолчанию None

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

index_colint, str, list of int, default None

Столбец (с индексом 0) для использования в качестве меток строк DataFrame. Передайте None, если такого столбца нет. Если передаётся список, эти столбцы будут объединены в MultiIndex. Если подмножество данных выбрано с usecols, index_col основан на подмножестве.

Пропущенные значения будут заполнены вперед, чтобы обеспечить двустороннюю совместимость с to_excel для merged_cells=True. Чтобы избежать заполнения пропущенных значений вперёд, используйте set_index после чтения данных вместо index_col.

usecolsстрока, список или вызываемый объект, по умолчанию None

  • Если None, то разобрать все столбцы.

  • Если строка, то указывает разделенный запятыми список букв столбцов Excel и диапазонов столбцов (например, “A:E” или “A,C,E:F”). Диапазоны включают обе стороны.

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

  • Если список строк, то указывает список имён столбцов для разбора.

  • Если вызываемый объект, то оцените каждое имя столбца по нему и проанализируйте столбец, если вызываемый объект возвращает True.

Возвращает подмножество столбцов в соответствии с описанным выше поведением.

dtypeИмя типа или словарь столбец -> тип, по умолчанию None

Тип данных для данных или столбцов. Например, {'a': np.float64, 'b': np.int32} Используйте object чтобы сохранить данные как хранящиеся в Excel и не интерпретировать dtype, что обязательно приведёт к object типом данных. Если указаны преобразователи, они будут применены ВМЕСТО преобразования типа данных. Если вы используете None, он будет выводить тип данных каждого столбца на основе данных.

движок{‘openpyxl’, ‘calamine’, ‘odf’, ‘pyxlsb’, ‘xlrd’}, по умолчанию None

Если io не является буфером или путём, это должно быть установлено для идентификации io. Совместимость движков:

  • openpyxl поддерживает более новые форматы файлов Excel.

  • calamine поддерживает форматы файлов Excel (.xls, .xlsx, .xlsm, .xlsb) и OpenDocument (.ods).

  • odf поддерживает форматы файлов OpenDocument (.odf, .ods, .odt).

  • pyxlsb поддерживает двоичные файлы Excel.

  • xlrd поддерживает старые файлы Excel (.xls).

Когда engine=None, следующая логика будет использоваться для определения движка:

  • Если path_or_buffer является форматом OpenDocument (.odf, .ods, .odt), тогда odf будет использоваться.

  • В противном случае, если path_or_buffer является форматом xls, xlrd будет использоваться.

  • В противном случае, если path_or_buffer имеет формат xlsb, pyxlsb будет использоваться.

  • В противном случае openpyxl будет использоваться.

конвертерыdict, по умолчанию None

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

true_valuesсписок, по умолчанию None

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

false_valuesсписок, по умолчанию None

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

skiprowslist-like, int или callable, необязательный

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

nrowsint, по умолчанию None

Количество строк для разбора.

na_valuesскаляр, строка, список или словарь, по умолчанию None

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

keep_default_nabool, по умолчанию 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_filterbool, по умолчанию True

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

verbosebool, по умолчанию False

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

parse_datesbool, list-like, или dict, по умолчанию False

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

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

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

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

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

Если столбец или индекс содержит неразбираемую дату, весь столбец или индекс будет возвращен неизмененным как тип данных object. Если вы не хотите разбирать некоторые ячейки как даты, просто измените их тип в Excel на "Текст". Для нестандартного разбора даты используйте pd.to_datetime после pd.read_excel.

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

date_parserфункция, необязательный

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

Если используется вместе с parse_dates, будет анализировать даты в соответствии с этим форматом. Для более сложных случаев, пожалуйста, читайте как object и затем применить to_datetime() по мере необходимости.

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

тысячиstr, по умолчанию None

Разделитель тысяч для парсинга строковых столбцов в числовые. Обратите внимание, что этот параметр необходим только для столбцов, хранящихся как TEXT в Excel, любые числовые столбцы будут автоматически распарсены, независимо от формата отображения.

десятичныйstr, default ‘.’

Символ, распознаваемый как десятичная точка для парсинга строковых столбцов в числовые. Обратите внимание, что этот параметр необходим только для столбцов, хранящихся как TEXT в Excel, любые числовые столбцы будут автоматически распарсены, независимо от формата отображения (например, используйте ',' для европейских данных).

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

комментарийstr, по умолчанию None

Комментирует оставшуюся часть строки. Передайте символ или символы в этот аргумент, чтобы указать комментарии во входном файле. Любые данные между строкой комментария и концом текущей строки игнорируются.

skipfooterint, по умолчанию 0

Строки в конце для пропуска (0-индексированные).

storage_optionsdict, optional

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

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

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

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

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

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

engine_kwargsdict, optional

Произвольные ключевые аргументы, передаваемые движку Excel.

Возвращает:
DataFrame или словарь DataFrames

DataFrame из переданного файла Excel. См. примечания в аргументе sheet_name для получения дополнительной информации о том, когда возвращается словарь DataFrame.

Смотрите также

DataFrame.to_excel

Запись DataFrame в файл Excel.

DataFrame.to_csv

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

read_csv

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

read_fwf

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

Примечания

Для конкретной информации о методах, используемых для каждого движка Excel, обратитесь к pandas руководство пользователя

Примеры

Файл можно прочитать, используя имя файла в виде строки или открытый файловый объект:

>>> pd.read_excel('tmp.xlsx', index_col=0)  
       Name  Value
0   string1      1
1   string2      2
2  #Comment      3

>>> pd.read_excel(open('tmp.xlsx', 'rb'),
...               sheet_name='Sheet3')  
   Unnamed: 0      Name  Value
0           0   string1      1
1           1   string2      2
2           2  #Comment      3

Индекс и заголовок могут быть указаны через index_col и header аргументы

>>> pd.read_excel('tmp.xlsx', index_col=None, header=None)  
     0         1      2
0  NaN      Name  Value
1  0.0   string1      1
2  1.0   string2      2
3  2.0  #Comment      3

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

>>> pd.read_excel('tmp.xlsx', index_col=0,
...               dtype={'Name': str, 'Value': float})  
       Name  Value
0   string1    1.0
1   string2    2.0
2  #Comment    3.0

Значения True, False и NA, а также разделители тысяч имеют значения по умолчанию, но могут быть явно указаны. Укажите нужные значения в виде строк или списков строк!

>>> pd.read_excel('tmp.xlsx', index_col=0,
...               na_values=['string1', 'string2'])  
       Name  Value
0       NaN      1
1       NaN      2
2  #Comment      3

Строки комментариев во входном файле Excel можно пропустить с помощью comment kwarg.

>>> pd.read_excel('tmp.xlsx', index_col=0, comment='#')  
      Name  Value
0  string1    1.0
1  string2    2.0
2     None    NaN