pandas.read_excel

pandas.read_excel(io, sheet_name=0, header=0, names=None, index_col=None, usecols=None, squeeze=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=None, thousands=None, decimal='.', comment=None, skipfooter=0, convert_float=None, mangle_dupe_cols=True, storage_options=None)[source]

Чтение файла Excel в pandas DataFrame.

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

Параметры

io:str, bytes, ExcelFile, xlrd.Book, path object, or file-like object

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

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

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

sheet_name:str, int, list, or None, default 0

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

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

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

• 1: 2-й лист в виде DataFrame

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

• [0, 1, "Sheet5"]: Загрузка первого, второго и листа с именем «Sheet5» в виде словаря DataFrame

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

header:int, list of int, default 0

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

names:array-like, default None

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

index_col:int, list of int, default None

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

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

usecols:str, list-like, or callable, default None

• Если None, то анализируются все столбцы.

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

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

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

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

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

squeeze:bool, default False

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

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

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

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

engine:str, по умолчанию None

Если io не буфер или путь, это необходимо указать для идентификации io. Поддерживаемые движки: “xlrd”, “openpyxl”, “odf”, “pyxlsb”. Совместимость движков:

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

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

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

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

Изменено в версии 1.2.0: Движок xlrd теперь поддерживает только файлы старого формата .xls. Когда engine=None, будет использована следующая логика для определения движка:

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

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

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

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

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

  Изменено в версии 1.3.0.

converters:dict, default None

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

true_values:list, default None

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

false_values:list, default None

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

skiprows:list-like, int, or callable, optional

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

nrows:int, default None

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

na_values:скаляр, str, list-like, or dict, default None

Дополнительные строки, распознаваемые как 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: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_filter=False может улучшить производительность чтения большого файла.

verbose:bool, default False

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

parse_dates:bool, list-like, or dict, default False

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

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

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

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

• словарь, например, {‘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) в качестве аргументов.

thousands:str, default None

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

decimal:str, default ‘.’

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

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

comment:str, default None

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

skipfooter:int, default 0

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

convert_float:bool, default True

Преобразовать целые числа с плавающей запятой в целые числа (например, 1.0 –> 1). Если False, все числовые данные будут читаться как числа с плавающей запятой: Excel хранит все числа во внутреннем формате с плавающей запятой.

Устарело начиная с версии 1.3.0: convert_float будет удален в будущей версии

mangle_dupe_cols:bool, default True

Дублирующиеся столбцы будут указаны как ‘X’, ‘X.1’, …’X.N’, а не как ‘X’…’X’. Передача False приведет к перезаписи данных, если в столбцах есть дублирующиеся имена.

Устарело начиная с версии 1.5.0: Не реализовано, и вместо этого будет добавлен новый аргумент для указания шаблона имён дублирующихся столбцов

storage_options:dict, optional

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

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

Возвращает

DataFrame или словарь DataFrames

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

См. также

DataFrame.to_excel

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

DataFrame.to_csv

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

read_csv

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

read_fwf

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

Примеры

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

>>> 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

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