import pandas df = 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=no_default, date_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=no_default, engine_kwargs=None)
io - любой допустимый путь в виде строки. Строка может быть URL. Допустимые схемы URL включают http(s), ftp(s), s3, gs и file. Для URL-адресов ожидается host. Локальным файлом может быть: file://localhost/path/to/table.xlsx.
Если необходимо передать объект pathlib, то этот аргумент принимает любой оs.PathLike объект.
Аргумент также поддерживает объекты подобные открытому файлу, у которых есть метод file.read(), такие как дескриптор файла (например, открытый файл open()) или io.BytesIO.
Обязательно смотрим описание класса
pandas.ExcelFile(). Он объединяет в себе практически все аргументы.
sheet_name=0 - строка с названием листа. Вместо названия листа можно передать целое число, которые говорит о его позиции (отсчет начинается с 0, листы диаграмм не считаются за позицию). Списки строк/целых чисел используются для запроса нескольких листов. Передача None загружает все листы.
Доступные варианты:
DataFrame.DataFrame.'Sheet1': загрузить лист с именем 'Sheet1'[0, 1, 'Sheet5']: загрузить первый, второй лист и лист с именем 'Sheet5'None: загрузить ВСЕ рабочие листы.header=0 - cтрока (с индексом 0), которая будет использоваться для меток столбцов анализируемого DataFrame. Если передается список целых чисел, эти позиции строк будут объединены в MultiIndex. Если строка с заголовками отсутствует, необходимо использовать None.
names=None - список имен столбцов, которые будут использоваться. Если файл не содержит строки c заголовками столбцов, то следует явно передать header=None.
index_col=None - строка с именем или номер позиции столбца (отсчет с 0), данные которого будут использоваться в качестве меток строк (индекса) DataFrame. Если такого столбца нет, то аргумент должен быть None. Если передается список строк/чисел, то эти столбцы будут объединены в MultiIndex. Если с помощью аргумента usecols выбрано подмножество столбцов, то index_col будет основан на этом подмножестве.
Отсутствующие значения будут заполнены вперед, чтобы можно было выполнить двусторонний обмен с to_excel() для merged_cells=True. Чтобы избежать прямого заполнения пропущенных значений, то вместо index_col используйте метод DataFrame.set_index() после чтения данных.
usecols=None - подмножество столбцов для сборки в DataFrame. Если None, то анализирует все столбцы.
'A:E' или 'A,C,E:F'). Диапазоны включают обе стороны.True для нужных.dtype=None - желаемый тип данных для столбцов в виде словаря. Например, {'a': np.float64, 'b': np.int32}. Для сохранения данных в том виде, в каком они хранятся в Excel необходимо использовать тип object и не интерпретируйте dtype, что обязательно приведет к получению dtype: object. Если указаны преобразователи (аргумент converters), то они будут применены ВМЕСТО преобразования dtype. Если None, то dtype каждого столбца будет выведен на основе данных этого столбца.
engine=None - модуль python, который будет читать файл Excel: 'openpyxl', 'calamine', 'odf', 'pyxlsb', 'xlrd'
Поведение по умолчанию (когда engine=None):
io имеет формат OpenDocument (.odf, .ods, .odt), то будет использоваться модуль odf.io имеет формат xls, то будет использоваться модуль xlrd.io имеет формат xlsb, то будет использоваться модуль pyxlsb.openpyxl.converters=None - словарь функций для преобразования значений в определенных столбцах. Ключами могут быть либо целые числа, либо метки столбцов, значения - это функции, которые принимают один входной аргумент, содержимое ячейки Excel, и возвращают преобразованное содержимое.
true_values=None - список значений, которые следует рассматривать как True.
false_values=None - список значений, которые следует рассматривать как False.
skiprows=None - список номеров строк (int), которые нужно пропустить (отсчет с 0), или количество строк (int), которые нужно пропустить в начале файла. Если передан вызываемый объект, то она принимает индексы строк, возвращая True (если строку следует пропустить), и False в противном случае. Примером допустимого вызываемого аргумента может быть: lambda x: x in [0, 2].
nrows=None - количество строк (int) для анализа.
na_values=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', 'None', '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 передача na_filter=False может повысить производительность чтения большого файла.
verbose=False - есть ли значений NA в нечисловых столбцах.
parse_dates=False - принимает bool, список, список списков или словарь списков.
Поведение заключается в следующем:
True - попробует проанализировать индекс. Примечание: автоматически устанавливается в True, если были переданы аргументы date_format или date_parser.[1, 2, 3] - попробует разобрать столбцы 1, 2, 3 каждый как отдельный столбец даты.[[1, 3]] - объединит столбцы 1 и 3 и проанализировать как один столбец даты. (Устарело с версии pandas 2.2, объедините нужные столбцы с pandas.to_datetime() после синтаксического анализа).{'foo' : [1, 3]} - разбирает столбцы 1, 3 как дату и вызывает результат ‘foo’. Значения объединяются пробелом перед разбором.Если столбец или индекс не могут быть представлены в виде массива datetime, скажем, из-за неразличимого значения или сочетания часовых поясов, то столбец или индекс будут возвращены без изменений как объектный тип данных. Для нестандартного анализа даты/времени, после прочтения данных в DataFrame, необходимо использовать pandas.to_datetime().
date_parser=no_default - (Устарело с версии pandas 2.0, используйте pandas.to_datetime() после синтаксического анализа) функция, используемая для преобразования последовательности строковых столбцов в массив экземпляров даты/времени. По умолчанию для преобразования используется dateutil.parser.parser. Pandas попытается вызвать date_parser тремя разными способами, переходя к следующему в случае возникновения исключения:
parse_dates); parse_dates, в один массив и передать его; date_parser один раз для каждой строки, используя в качестве аргументов одну или несколько строк (соответствующих столбцам, определенным в parse_dates).date_format=None - строка формата (например, '%d/%m/%Y'), используемая для анализа даты совместно с parse_dates. Информацию о вариантах строки формата смотрите в документации по strftime, но учтите, что '%f' будет анализировать вплоть до наносекунд. Для чего-либо более сложного, используйте pandas.to_datetime() по мере необходимости.
thousands=None - один символ, действующий как разделитель тысяч в числовых значениях .
decimal='.' - один символ, который нужно распознать как десятичную точку.
comment=None - символ или символы для указания комментариев во входном файле. Любые данные между строкой комментария и концом текущей строки игнорируются.
skipfooter=0 - количество строк в нижней части файла, которые нужно пропустить.
storage_options=None - дополнительные параметры, которые имеют смысл для конкретного подключения к хранилищу. Например, хост, порт, имя пользователя, пароль и т. д. Для URL-адресов HTTP(S) пары ключ-значение пересылаются в urllib.request.Request в качестве заголовков.
dtype_backend='numpy_nullable' - (экспериментальный) внутренний тип данных, применяемый к результирующему DataFrame.
Поведение выглядит следующим образом:
'numpy_nullable': возвращает фрейм с поддержкой null-dtype (по умолчанию).'pyarrow': возвращает фрейм данных ArrowDtype с нулевым значением, поддерживаемый pyarrow.engine_kwargs=None - произвольные ключевые аргументы, которые передаются в движок (аргумент engine).
Функция read_excel() модуля pandas считывает файл Excel в DataFrame. Поддерживает возможность чтения одного листа или списка листов.
Поддерживает расширения файлов xls, xlsx, xlsm, xlsb, odf, ods и odt, считываемые из локальной файловой системы или URL-адреса.
В самом простом варианте использования, функция read_excel() принимает путь к файлу Excel и аргумент sheet_name, указывающий, какой лист нужно проанализировать.
df = pd.read_excel("path_to_file.xls", sheet_name="Sheet1")
При использовании аргумента engine_kwargs - функция передаст эти аргументы движку. Для этого важно знать, какую функцию pandas использует под капотом.
.xlsx и .xlsm используется openpyxl.load_workbook() ..xls используется xlrd.open_workbook()..xlsb используется pyxlsb.open_workbook()..ods используется odf.opendocument.load() .pandas.ExcelFile()Чтобы облегчить работу с несколькими листами из одного файла, может использоваться класс pandas.ExcelFile(). При чтении нескольких листов будет улучшена производительность, т.к. файл будет читаться в память только один раз.
import pandas as pd xlsx = pd.ExcelFile("path_to_file.xls") df = pd.read_excel(xlsx, "Sheet1")
Класс ExcelFile() также можно использовать в качестве контекстного менеджера.
with pd.ExcelFile("path_to_file.xls") as xls: df1 = pd.read_excel(xls, "Sheet1") df2 = pd.read_excel(xls, "Sheet2")
Свойство ExcelFile.sheet_names сгенерирует список названий листов в файле.
Основным вариантом использования ExcelFile является синтаксический анализ нескольких листов с разными параметрами:
data = {} # случай, когда формат `Sheet1` отличается от формата `Sheet2` with pd.ExcelFile("path_to_file.xls") as xls: data["Sheet1"] = pd.read_excel(xls, "Sheet1", index_col=None, na_values=["NA"]) data["Sheet2"] = pd.read_excel(xls, "Sheet2", index_col=1)
Обратите внимание, что если для всех листов используются одни и те же параметры синтаксического анализа, то список с именами листов может быть просто передан в read_excel() без потери производительности.
# использование класса `ExcelFile()` data = {} with pd.ExcelFile("path_to_file.xls") as xls: data["Sheet1"] = pd.read_excel(xls, "Sheet1", index_col=None, na_values=["NA"]) data["Sheet2"] = pd.read_excel(xls, "Sheet2", index_col=None, na_values=["NA"]) # эквивалент с использованием списка имен листов data = pd.read_excel( "path_to_file.xls", ["Sheet1", "Sheet2"], index_col=None, na_values=["NA"] )
Класс ExcelFile() также может быть вызван с помощью xlrd.book.Book в качестве аргумента. Это позволяет пользователю управлять способом чтения файла Excel. Например, листы могут быть загружены по запросу путем вызова xlrd.open_workbook() с on_demand=True.
import xlrd xlrd_book = xlrd.open_workbook("path_to_file.xls", on_demand=True) with pd.ExcelFile(xlrd_book) as xls: df1 = pd.read_excel(xls, "Sheet1") df2 = pd.read_excel(xls, "Sheet2")
Примечание:
- Второй аргумент функции
read_excel()являетсяsheet_name, не путать со атрибутомExcelFile.sheet_names.- Атрибут
ExcelFile.sheet_namesобеспечивает доступ к списку листов.
sheet_name позволяют указать лист или листы для чтения.sheet_name=0, что указывает на необходимость чтения первого листа.sheet_name указывает на имя определенного листа в книге.sheet_name указывает на индекс листа. Индексы соответствуют соглашению Python, начиная с 0.sheet_name, вернет словарь DataFrame указанных листов.None вернет словарь DataFrame всех доступных листов.# Возвращает `DataFrame` pd.read_excel("path_to_file.xls", "Sheet1", index_col=None, na_values=["NA"])
Использование индекса листа:
# Возвращает `DataFrame` pd.read_excel("path_to_file.xls", 0, index_col=None, na_values=["NA"])
Использование значения по умолчанию:
# Возвращает `DataFrame` pd.read_excel("path_to_file.xls")
Использование None для получения всех листов:
# Возвращает словарь с `DataFrame` pd.read_excel("path_to_file.xls", sheet_name=None)
Использование списка для получения нескольких листов:
# Возвращает 1-й и 4-й листы в виде словаря `DataFrame`. pd.read_excel("path_to_file.xls", sheet_name=["Sheet1", 3])
Функция read_excel() может читать более одного листа, задав для параметра sheet_name либо список имен листов, либо список позиций листов, либо значение None для чтения всех листов. Листы можно указать по индексу листа или имени листа, используя целое число или строку соответственно.
Обязательно смотрим описание класса
pandas.ExcelFile().
MultiIndexФункция read_excel() может читать индекс-MultiIndex, передавая список столбцов аргументу index_col, а столбец-MultiIndex, передавая список строк аргументу header. Если индекс или столбцы имеют сериализованные имена уровней, то они также будут считаны путем указания строк/столбцов, составляющих уровни.
Например, чтобы прочитать индекс MultiIndex без имен:
df = pd.DataFrame( {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]}, index=pd.MultiIndex.from_product([["a", "b"], ["c", "d"]]), ) # запишем в файл `.xlsx` >>> df.to_excel("path_to_file.xlsx") >>> df = pd.read_excel("path_to_file.xlsx", index_col=[0, 1]) >>> df # a b # a c 1 5 # d 2 6 # b c 3 7 # d 4 8
Если индекс имеет имена уровней, то они также будут анализироваться с использованием тех же аргументов.
>>> df.index = df.index.set_names(["lvl1", "lvl2"]) >>> df.to_excel("path_to_file.xlsx") >>> df = pd.read_excel("path_to_file.xlsx", index_col=[0, 1]) >>> df # a b # lvl1 lvl2 # a c 1 5 # d 2 6 # b c 3 7 # d 4 8
Если исходный файл имеет как индекс-MultiIndex, так и столбцы-MultiIndex, то списки, определяющие каждый из них, должны быть переданы аргументам index_col и header:
>>> df.columns = pd.MultiIndex.from_product([["a"], ["b", "d"]], names=["c1", "c2"]) >>> df.to_excel("path_to_file.xlsx") >>> df = pd.read_excel("path_to_file.xlsx", index_col=[0, 1], header=[0, 1]) >>> df # c1 a # c2 b d # lvl1 lvl2 # a c 1 5 # d 2 6 # b c 3 7 # d 4 8
Отсутствующие значения в столбцах, указанных в index_col, будут заполнены вперед, чтобы обеспечить возможность двустороннего переключения с помощью to_excel() для merged_cells=True. Чтобы избежать прямого заполнения недостающих значений, необходимо использовать DataFrame.set_index() после чтения данных вместо index_col.
DataFrame из определенных столбцов таблицы ExcelФункция read_excel() использует ключевой аргумент usecols, который позволяет указать подмножество столбцов таблицы Excel для анализа.
Можете указать набор столбцов и диапазонов Excel, разделенных запятыми, в виде одной строки:
pd.read_excel("path_to_file.xls", "Sheet1", usecols="A,C:E")
Если usecols - это список целых чисел, то предполагается, что это индексы столбцов таблицы Excel.
pd.read_excel("path_to_file.xls", "Sheet1", usecols=[0, 2, 3])
Порядок элементов игнорируется, поэтому usecols=[0, 1] может прочитаться как [1, 0].
Если usecols представляет собой список строк, предполагается, что каждая строка соответствует имени столбца, указанному пользователем в таблице Excel или выведенному из строки(строк) заголовка документа.
pd.read_excel("path_to_file.xls", "Sheet1", usecols=["foo", "bar"])
Порядок элементов игнорируется, поэтому usecols=['baz', 'joe'] может прочитаться как ['joe', 'baz'].
Если usecols является вызываемым объектом, то функция должна принимать имена столбцов, и возвращать True для имен столбцов, которые должны попасть в результирующий DataFrame.
pd.read_excel("path_to_file.xls", "Sheet1", usecols=lambda x: x.isalpha())
Обработка ячеек с датой/временем
При чтении файла Excel, значения, подобные дате и времени, обычно автоматически преобразуются в соответствующий тип dtype. Но если есть столбец строк, которые выглядят как даты (но на самом деле не отформатированы как даты в Excel), то можно использовать ключевой аргумент parse_dates для преобразования этих строк в представление datetime модуля pandas:
pd.read_excel("path_to_file.xls", "Sheet1", parse_dates=["date_strings"])
Содержимое ячеек Excel можно преобразовать с помощью аргумента converters. Например, чтобы преобразовать столбец в логическое значение:
pd.read_excel("path_to_file.xls", "Sheet1", converters={"MyBools": bool})
Эта опция обрабатывает исключения в функциях-преобразователях как пропущенные данные. Преобразования применяются ячейка за ячейкой, а не ко всему столбцу в целом, поэтому dtype массива не гарантируется. Например, столбец целых чисел с пропущенными значениями не может быть преобразован в массив с целочисленным dtype, потому что NaN - это значение float. Но можете вручную замаскировать отсутствующие данные, чтобы восстановить целочисленный dtype:
def cfun(x): return int(x) if x else -1 pd.read_excel("path_to_file.xls", "Sheet1", converters={"MyInts": cfun})
dtypeВ качестве альтернативы преобразователям (аргумент converters) тип для всего столбца может быть указан с помощью ключевого аргумента dtype, которое использует словарь, сопоставляющий имена столбцов с типами. Чтобы интерпретировать данные без определенного типа, используйте тип str или object.
pd.read_excel("path_to_file.xls", dtype={"MyInts": "int64", "MyText": str})
pandas.read_excel()Файл может быть прочитан, используя имя файла в виде строки или открытого объекта file:
Имя файла в виде строки:
>>> 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
Типы столбцов определяются pandas, но могут быть указаны явно:
>>> 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 можно пропустить:
>>> pd.read_excel('tmp.xlsx', index_col=0, comment='#') # Name Value # 0 string1 1.0 # 1 string2 2.0 # 2 None NaN