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=_NoDefault.no_default, date_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=_NoDefault.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: 1-й лист как DataFrame

• 1: 2-й лист как 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, то анализируются все столбцы.

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

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

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

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

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

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

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

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

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

nrows:int, default 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’, ‘<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.

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

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

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

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

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

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

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

decimal:строка, по умолчанию ‘.’

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

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

comment:str, default None

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

skipfooter:int, default 0

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

storage_options:dict, optional

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

• "pyarrow": возвращает DataFrame с типом данных pyarrow, поддерживающим значения NULL ArrowDtype.

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

engine_kwargs:dict, optional

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

Возвращаемое значение:

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

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

См. также

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