polars.read_excel

polars.read_excel(
    source: FileSource | memoryview[int],
    *,
    sheet_id: int | Sequence[int] | None = None,
    sheet_name: str | list[str] | tuple[str,
    ...] | None = None,
    table_name: str | None = None,
    engine: ExcelSpreadsheetEngine = 'calamine',
    engine_options: dict[str,
    Any] | None = None,
    read_options: dict[str,
    Any] | None = None,
    has_header: bool = True,
    columns: Sequence[int] | Sequence[str] | str | None = None,
    schema_overrides: SchemaDict | None = None,
    infer_schema_length: int | None = 100,
    include_file_paths: str | None = None,
    drop_empty_rows: bool = True,
    drop_empty_cols: bool = True,
    raise_if_empty: bool = True,
) → DataFrame | dict[str, DataFrame]

Читает данные электронной таблицы Excel в DataFrame.

Добавлено в версии 1.20: Поддерживается загрузка данных из именованных объектов таблиц с параметром table_name.

Добавлено в версии 1.18: Поддерживается загрузка данных из списка (или шаблона glob) нескольких книг.

Изменено в версии 1.0: Теперь по умолчанию используется движок «calamine» (ранее — «xlsx2csv»).

Изменено в версии 0.20.7: Параметр read_csv_options переименован в read_options.

Изменено в версии 0.20.6: Параметр xlsx2csv_options переименован в engine_options.

Параметры:

source

Путь или пути к файлу либо объект, подобный файлу (под «объектом, подобным файлу» подразумеваются объекты с методом read(), например файловый дескриптор, созданный встроенной функцией open, или экземпляр BytesIO). Для объектов, подобных файлам, позиция в потоке после чтения может не обновиться.

sheet_id

Номер или номера листов для преобразования (задайте 0, чтобы загрузить все листы в виде DataFrame) с возвратом словаря {sheetname:frame,}. (Если не задан ни этот параметр, ни sheet_name, по умолчанию используется 1.) Также можно передать последовательность номеров листов.

sheet_name

Имя или имена листов для преобразования; нельзя использовать вместе с sheet_id. Если указано более одного имени, возвращается словарь {sheetname:frame,}.

table_name

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

engine{‘calamine’, ‘openpyxl’, ‘xlsx2csv’}

Библиотека для анализа файла электронной таблицы; по умолчанию используется «calamine».

• «calamine»: этот движок можно использовать для чтения всех основных типов книг Excel (.xlsx, .xlsb, .xls); он значительно быстрее других вариантов и использует модуль fastexcel для связи с парсером Calamine на основе Rust.
• «openpyxl»: этот движок значительно медленнее и calamine, и xlsx2csv, но может служить полезным запасным вариантом, если прочитать данные из книги другими способами не удаётся.
• «xlsx2csv»: преобразует данные в CSV в памяти, а затем использует встроенный метод polars read_csv для анализа результата.

engine_options

Дополнительные параметры, передаваемые основному конструктору парсера используемого движка (указан ниже), если они поддерживаются:

• «calamine»: не применимо (можно указать только read_options)
• «openpyxl»: load_workbook
• «xlsx2csv»: Xlsx2csv

read_options

Параметры, передаваемые методу используемого движка, который считывает данные листа. Если поддерживается, это позволяет дополнительно управлять разбором данных. Для каждого движка используются следующие методы чтения:

• «calamine»: load_sheet_by_name (или load_table, если используется параметр table_name).
• «openpyxl»: не применимо (можно указать только engine_options)
• «xlsx2csv»: см. read_csv()

has_header

Указывает, является ли первая строка данных таблицы заголовком. Если значение равно False, имена столбцов будут сгенерированы в следующем формате: column_x, где x — порядковый номер каждого столбца в наборе данных, начиная с 1.

columns

Столбцы для чтения с листа; если параметр не указан, считываются все столбцы. Можно передать последовательность имён или индексов столбцов либо одно имя столбца.

schema_overrides

Позволяет задать или переопределить типы одного или нескольких столбцов.

infer_schema_length

Максимальное количество строк для сканирования при определении схемы. Если задать None, для определения типов данных сканируется весь набор данных, что может замедлить разбор больших книг. Обратите внимание, что этот параметр поддерживается только движками «calamine» и «xlsx2csv».

include_file_paths

Добавляет путь или пути к исходным файлам в виде столбца с этим именем.

drop_empty_rows

Указывает, нужно ли пропускать пустые строки при чтении данных в DataFrame.

drop_empty_cols

Указывает, нужно ли пропускать пустые столбцы (без заголовков) при чтении данных в DataFrame. Обратите внимание, что способ определения пустых столбцов может различаться в зависимости от используемого движка.

raise_if_empty

Если на листе нет данных, возникает исключение `NoDataError`. Если для этого параметра задано значение False, вместо этого возвращается пустой DataFrame (без столбцов).

Возвращает:

DataFrame

Если считывается один лист.

dict

Если считывается несколько листов, возвращается словарь «{sheetname: DataFrame, …}».

См. также

read_ods

Примечания

• По возможности используйте для чтения книг Excel движок «calamine» по умолчанию, поскольку он значительно быстрее других вариантов.
• При использовании движка xlsx2csv целевой лист Excel сначала преобразуется в CSV с помощью xlsx2csv.Xlsx2csv(source).convert(), а затем разбирается функцией read_csv() из Polars. Чтобы повлиять на этот этап конвейера разбора, можно передать дополнительные параметры в read_options.
• Если вы хотите прочитать несколько листов и задать разные параметры (read_options, schema_overrides и т. д.), следует выполнить отдельные вызовы, поскольку параметры задаются глобально, а не для каждого листа отдельно.

Примеры

Считайте лист «data» из файла Excel в DataFrame.

>>> pl.read_excel(
...     source="test.xlsx",
...     sheet_name="data",
... )  

Если не удаётся определить правильные типы данных, задайте их с помощью параметра schema_overrides или увеличьте длину выборки для определения типов с помощью infer_schema_length.

>>> pl.read_excel(
...     source="test.xlsx",
...     schema_overrides={"dt": pl.Date},
...     infer_schema_length=None,
... )  

С помощью движка xlsx2csv считайте данные таблицы с листа 3 книги Excel в DataFrame, пропуская пустые строки листа. Поскольку на листе 3 нет строки заголовков, необходимые дополнительные настройки можно передать через параметр read_options; они будут переданы в read_csv().

>>> pl.read_excel(
...     source="test.xlsx",
...     sheet_id=3,
...     engine="xlsx2csv",
...     engine_options={"skip_empty_lines": True},
...     read_options={"has_header": False, "new_columns": ["a", "b", "c"]},
... )