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=<no_default>, date_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=<no_default>, engine_kwargs=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.

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

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

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

Возможные варианты:

• По умолчанию используется 0: первый лист в виде DataFrame

• 1: второй лист в виде DataFrame

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

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

• None: все листы.

header:int, list of int, default 0

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

names:array-like, default None

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

index_col:int, str, list of int, default None

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

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

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

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

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

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

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

• Если указана callable-функция, каждое имя столбца проверяется с её помощью, и столбец анализируется, если функция возвращает True.

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

dtype:Type name or dict of column -> type, default None

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

engine:{‘openpyxl’, ‘calamine’, ‘odf’, ‘pyxlsb’, ‘xlrd’}, default 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.

converters:dict, default None

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

true_values:list, default None

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

false_values:list, default None

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

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

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

nrows:int, default None

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

na_values:scalar, 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’, ‘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, добавленных в нечисловые столбцы.

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

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

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

• list целых чисел или имён. Например, если указано [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.

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

date_parser:function, 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, default None

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

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

thousands:str, default None

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

decimal:str, default ‘.’

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

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

comment:str, default None

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

skipfooter:int, default 0

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

storage_options:dict, optional

Дополнительные параметры, относящиеся к конкретному подключению к хранилищу, например host, port, username, password и т. д. Для 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 с типами данных, поддерживающими пропущенные значения (по умолчанию).

• "pyarrow": возвращает DataFrame с поддержкой пропущенных значений на основе pyarrow и типом ArrowDtype.

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

engine_kwargs:dict, optional

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

Возвращает:

DataFrame or dict of DataFrames

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

См. также

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.

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