polars.DataFrame.write_excel

DataFrame.write_excel(
    workbook: str | Workbook | IO[bytes] | Path | None = None,
    worksheet: str | Worksheet | None = None,
    *,
    position: tuple[int,
    int] | str = 'A1',
    table_style: str | dict[str,
    Any] | None = None,
    table_name: str | None = None,
    column_formats: ColumnFormatDict | None = None,
    dtype_formats: dict[OneOrMoreDataTypes,
    str] | None = None,
    conditional_formats: ConditionalFormatDict | None = None,
    header_format: dict[str,
    Any] | None = None,
    column_totals: ColumnTotalsDefinition | None = None,
    column_widths: ColumnWidthsDefinition | None = None,
    row_totals: RowTotalsDefinition | None = None,
    row_heights: dict[int | tuple[int,
    ...],
    int] | int | None = None,
    sparklines: dict[str,
    Sequence[str] | dict[str,
    Any]] | None = None,
    formulas: dict[str,
    str | dict[str,
    str]] | None = None,
    float_precision: int = 3,
    include_header: bool = True,
    autofilter: bool = True,
    autofit: bool = False,
    hidden_columns: Sequence[str] | SelectorType | None = None,
    hide_gridlines: bool = False,
    sheet_zoom: int | None = None,
    freeze_panes: str | tuple[int,
    int] | tuple[str,
    int,
    int] | tuple[int,
    int,
    int,
    int] | None = None,
    use_zip64: bool = False,
) → Workbook

Записывает данные фрейма в таблицу книги/листа Excel.

Параметры:

workbook{str, Workbook}

Строковое имя или путь к создаваемой книге, объект BytesIO, файл, открытый в двоичном режиме, или объект xlsxwriter.Workbook, который не был закрыт. Если None, данные записываются в dataframe.xlsx в рабочем каталоге.

worksheet{str, Worksheet}

Имя целевого листа или объект xlsxwriter.Worksheet (в этом случае workbook должен быть родительским объектом xlsxwriter.Workbook); если None, при создании новой книги данные записываются на «Sheet1» (обратите внимание: для записи в существующую книгу требуется допустимое существующее или новое имя листа).

position{str, tuple}

Положение таблицы в нотации Excel (например, «A1») или кортеж целых чисел (строка, столбец).

table_style{str, dict}

Имя встроенного стиля таблицы Excel, например «Table Style Medium 4», или словарь параметров {"key":value,}, содержащий один или несколько следующих ключей: «style», «first_column», «last_column», «banded_columns», «banded_rows».

table_namestr

Имя выходного объекта таблицы на листе; на него можно ссылаться в формулах/диаграммах листа или в последующих операциях xlsxwriter.

column_formatsdict

Словарь {colname(s):str,} или {selector:str,} для применения строки формата Excel к указанным столбцам. Заданные здесь форматы (например, «dd/mm/yyyy», «0.00%» и т. д.) переопределяют любые форматы, заданные в dtype_formats.

dtype_formatsdict

Словарь {dtype:str,}, задающий формат Excel по умолчанию для указанного dtype. (Его можно переопределить отдельно для каждого столбца с помощью параметра column_formats.)

conditional_formatsdict

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

Если передаётся строка с именем типа, это должен быть один из допустимых типов xlsxwriter, например «3_color_scale», «data_bar» и т. д.
Если передаётся словарь, можно использовать любые поддерживаемые параметры xlsxwriter, включая наборы значков, формулы и т. д.
Передача нескольких столбцов в виде кортежа/ключа применит единый формат ко всем столбцам. Это удобно для создания тепловой карты, поскольку минимальные/максимальные значения будут определяться по всему диапазону, а не отдельно для каждого столбца.
Наконец, можно также передать список, составленный из указанных выше параметров, чтобы применить к одному диапазону несколько правил условного форматирования.

header_formatdict

Словарь {key:value,} с параметрами формата xlsxwriter для строки заголовка таблицы, например {"bold":True, "font_color":"#702963"}.

column_totals{bool, list, dict}

Добавляет в экспортируемую таблицу строку итогов по столбцам.

Если значение True, для всех числовых столбцов будет добавлен итог с использованием функции «sum».
Если передаётся строка, она должна быть именем одной из допустимых функций вычисления итогов, и для всех числовых столбцов будет добавлен итог с использованием этой функции.
Если передаётся список имён столбцов, итог будет добавлен только для указанных столбцов.
Для более гибкой настройки передайте словарь {colname:funcname,}.

Допустимые имена функций вычисления итогов по столбцам: «average», «count_nums», «count», «max», «min», «std_dev», «sum» и «var».

column_widths{dict, int}

Словарь {colname:int,} или {selector:int,} либо одно целое число, задающее (или переопределяющее при автоматической подгонке) ширину столбцов таблицы в целых пикселях. Если передано целое число, для всех столбцов таблицы используется одно и то же значение.

row_totals{dict, list, bool}

Добавляет столбец итогов по строкам справа от экспортируемой таблицы.

Если значение True, в конце таблицы будет добавлен столбец с именем «total», в котором для каждой строки применяется функция «sum» ко всем числовым столбцам.
Если передаётся список/последовательность имён столбцов, в суммировании будут участвовать только соответствующие столбцы.
Можно также передать словарь {colname:columns,}, чтобы создать один или несколько столбцов итогов с разными именами и ссылками на разные столбцы.

row_heights{dict, int}

Целое число или словарь {row_index:int,}, задающий высоту указанных строк (если передан словарь) или всех строк (если передано целое число), пересекающих тело таблицы (включая строки заголовка и итогов), в целых пикселях. Обратите внимание: row_index начинается с нуля и указывает на строку заголовка (если только include_header не равно False).

sparklinesdict

Словарь {colname:list,} или {colname:dict,}, задающий одну или несколько спарклайн-диаграмм, которые будут записаны в новый столбец таблицы.

Если передать список имён столбцов (используемых в качестве источника данных для спарклайна), будут применены параметры спарклайна по умолчанию (например, линейная диаграмма без маркеров).
Для более гибкой настройки можно передать словарь параметров, совместимый с xlsxwriter. В этом случае доступны три дополнительных специфичных для polars ключа: «columns», «insert_before» и «insert_after». Они позволяют задать исходные столбцы и расположение спарклайна относительно других столбцов таблицы. Если положение не задано, спарклайны добавляются в конец таблицы (то есть в крайнюю правую часть) в указанном порядке.

formulasdict

Словарь {colname:formula,} или {colname:dict,}, задающий одну или несколько формул, которые будут записаны в новый столбец таблицы. Настоятельно рекомендуется по возможности использовать в формулах структурированные ссылки, чтобы упростить обращение к столбцам по имени.

Если передать строку с формулой (например, «=[@colx]*[@coly]»), столбец будет добавлен в конец таблицы (то есть в крайнюю правую часть), после спарклайнов по умолчанию и перед итогами по строкам.
Для максимальной гибкости передайте словарь параметров со следующими ключами: «formula» (обязательный), один из ключей «insert_before» или «insert_after», а также необязательный «return_dtype». Последний используется для корректного форматирования результата формулы и позволяет включить его в итоги по строкам/столбцам.

float_precisionint

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

include_headerbool

Указывает, следует ли создавать таблицу со строкой заголовка.

autofilterbool

Если у таблицы есть заголовки, включает возможность автофильтрации.

autofitbool

Вычисляет ширину каждого столбца на основе данных.

hidden_columnsstr | list

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

hide_gridlinesbool

Скрывает все линии сетки на выходном листе.

sheet_zoomint

Задаёт уровень масштабирования по умолчанию для выходного листа.

freeze_panesstr | (str, int, int) | (int, int) | (int, int, int, int)

Закрепляет области книги.

Если передан кортеж (строка, столбец), области разделяются в верхнем левом углу указанной ячейки; индексация начинается с нуля. Поэтому, чтобы закрепить только верхнюю строку, передайте (1, 0).
Также можно указать ячейку в формате Excel. Например, «A2» означает, что разделение происходит в верхнем левом углу ячейки A2, что эквивалентно (1, 0).
Если передан кортеж (строка, столбец, верхняя_строка, верхний_столбец), области разделяются на основе row и col, а область прокрутки начинает отображаться с top_row и top_col. Поэтому, чтобы закрепить только верхнюю строку и начать прокрутку со строки 10, столбца D (5-й столбец), передайте (1, 0, 9, 4). Эквивалентный вариант с нотацией Excel для (строка, столбец): («A2», 9, 4).

use_zip64bool

Следует ли использовать расширения ZIP64 при записи книги. Это позволяет записывать исключительно большие файлы книги (размером после распаковки >=4 ГБ), но обеспечивает меньшую совместимость.

Примечания

Список совместимых имён свойств формата xlsxwriter можно найти здесь: https://xlsxwriter.readthedocs.io/format.html#format-methods-and-format-properties
В словарях условного форматирования следует указывать определения, совместимые с xlsxwriter; polars самостоятельно применит их на листе с учётом относительного положения листа/столбца. Список поддерживаемых параметров см. здесь: https://xlsxwriter.readthedocs.io/working_with_conditional_formats.html
Аналогично, словари параметров спарклайнов должны содержать ключи/значения, совместимые с xlsxwriter, а также обязательный ключ polars «columns», задающий исходные данные спарклайна; исходные столбцы должны располагаться рядом. Для указания положения спарклайна в таблице доступны ещё два специфичных для polars ключа: «insert_after» и «insert_before». Значением этих ключей должно быть имя столбца экспортируемой таблицы. https://xlsxwriter.readthedocs.io/working_with_sparklines.html
Словари формул должны содержать ключ «formula», а также могут содержать необязательные ключи «insert_after», «insert_before» и/или «return_dtype». Эти дополнительные ключи позволяют вставить столбец в определённое место таблицы и/или задать тип результата формулы (например, «Int64», «Float64» и т. д.). В формулах, ссылающихся на столбцы таблицы, следует использовать синтаксис структурированных ссылок Excel, чтобы формула применялась корректно и учитывала относительное положение в таблице. https://support.microsoft.com/en-us/office/using-structured-references-with-excel-tables-f5ed2452-2337-4f71-bed3-c8ae6d2b276e
Чтобы получить вывод без форматирования, можно применить селектор формата «General» ко всем столбцам (или ко всем нетемпоральным столбцам, чтобы сохранить форматирование столбцов с датами/датой и временем), например: column_formats={~cs.temporal(): "General"}.

Примеры

Создайте экземпляр базового DataFrame:

>>> from random import uniform
>>> from datetime import date
>>>
>>> df = pl.DataFrame(
...     {
...         "dtm": [date(2023, 1, 1), date(2023, 1, 2), date(2023, 1, 3)],
...         "num": [uniform(-500, 500), uniform(-500, 500), uniform(-500, 500)],
...         "val": [10_000, 20_000, 30_000],
...     }
... )

Экспортируйте данные в «dataframe.xlsx» (имя книги по умолчанию, если оно не указано) в рабочем каталоге, добавьте итоги по всем числовым столбцам (по умолчанию используется «sum»), затем автоматически подберите ширину столбцов:

>>> df.write_excel(column_totals=True, autofit=True)

Запишите фрейм в указанное место листа, задайте именованный стиль таблицы, примените формат даты в американском стиле, увеличьте точность форматирования чисел с плавающей точкой, примените к указанному столбцу нестандартную функцию вычисления итогов и автоматически подберите ширину столбцов:

>>> df.write_excel(  
...     position="B4",
...     table_style="Table Style Light 16",
...     dtype_formats={pl.Date: "mm/dd/yyyy"},
...     column_totals={"num": "average"},
...     float_precision=6,
...     autofit=True,
... )

Дважды запишите тот же фрейм на именованный лист, применяя к каждой таблице разные стили и условное форматирование, а также добавляя заголовки таблиц с пользовательским форматированием и явной интеграцией xlsxwriter:

>>> from xlsxwriter import Workbook
>>> with Workbook("multi_frame.xlsx") as wb:  
...     # basic/default conditional formatting
...     df.write_excel(
...         workbook=wb,
...         worksheet="data",
...         position=(3, 1),  # specify position as (row,col) coordinates
...         conditional_formats={"num": "3_color_scale", "val": "data_bar"},
...         table_style="Table Style Medium 4",
...     )
...
...     # advanced conditional formatting, custom styles
...     df.write_excel(
...         workbook=wb,
...         worksheet="data",
...         position=(df.height + 7, 1),
...         table_style={
...             "style": "Table Style Light 4",
...             "first_column": True,
...         },
...         conditional_formats={
...             "num": {
...                 "type": "3_color_scale",
...                 "min_color": "#76933c",
...                 "mid_color": "#c4d79b",
...                 "max_color": "#ebf1de",
...             },
...             "val": {
...                 "type": "data_bar",
...                 "data_bar_2010": True,
...                 "bar_color": "#9bbb59",
...                 "bar_negative_color_same": True,
...                 "bar_negative_border_color_same": True,
...             },
...         },
...         column_formats={"num": "#,##0.000;[White]-#,##0.000"},
...         column_widths={"val": 125},
...         autofit=True,
...     )
...
...     # add some table titles (with a custom format)
...     ws = wb.get_worksheet_by_name("data")
...     fmt_title = wb.add_format(
...         {
...             "font_color": "#4f6228",
...             "font_size": 12,
...             "italic": True,
...             "bold": True,
...         }
...     )
...     ws.write(2, 1, "Basic/default conditional formatting", fmt_title)
...     ws.write(df.height + 6, 1, "Custom conditional formatting", fmt_title)

Экспортируйте таблицу с двумя разными типами спарклайнов. Используйте параметры по умолчанию для спарклайна «trend» и пользовательские параметры (и позиционирование) для спарклайна win_loss «+/-», а также нестандартное форматирование целых чисел, итоги по столбцам, ненавязчивую двухцветную тепловую карту и скрытые линии сетки листа:

>>> df = pl.DataFrame(
...     {
...         "id": ["aaa", "bbb", "ccc", "ddd", "eee"],
...         "q1": [100, 55, -20, 0, 35],
...         "q2": [30, -10, 15, 60, 20],
...         "q3": [-50, 0, 40, 80, 80],
...         "q4": [75, 55, 25, -10, -55],
...     }
... )
>>> df.write_excel(  
...     table_style="Table Style Light 2",
...     # apply accounting format to all flavours of integer
...     dtype_formats={dt: "#,##0_);(#,##0)" for dt in [pl.Int32, pl.Int64]},
...     sparklines={
...         # default options; just provide source cols
...         "trend": ["q1", "q2", "q3", "q4"],
...         # customized sparkline type, with positioning directive
...         "+/-": {
...             "columns": ["q1", "q2", "q3", "q4"],
...             "insert_after": "id",
...             "type": "win_loss",
...         },
...     },
...     conditional_formats={
...         # create a unified multi-column heatmap
...         ("q1", "q2", "q3", "q4"): {
...             "type": "2_color_scale",
...             "min_color": "#95b3d7",
...             "max_color": "#ffffff",
...         },
...     },
...     column_totals=["q1", "q2", "q3", "q4"],
...     row_totals=True,
...     hide_gridlines=True,
... )

Экспортируйте таблицу со столбцом, вычисляемым с помощью формулы Excel и рассчитывающим стандартизированный Z-показатель; в примере показано использование структурированных ссылок вместе с директивами позиционирования, итогами по столбцам и пользовательским форматированием.

>>> df = pl.DataFrame(
...     {
...         "id": ["a123", "b345", "c567", "d789", "e101"],
...         "points": [99, 45, 50, 85, 35],
...     }
... )
>>> df.write_excel(  
...     table_style={
...         "style": "Table Style Medium 15",
...         "first_column": True,
...     },
...     column_formats={
...         "id": {"font": "Consolas"},
...         "points": {"align": "center"},
...         "z-score": {"align": "center"},
...     },
...     column_totals="average",
...     formulas={
...         "z-score": {
...             # use structured references to refer to the table columns and 'totals' row
...             "formula": "=STANDARDIZE([@points], [[#Totals],[points]], STDEV([points]))",
...             "insert_after": "points",
...             "return_dtype": pl.Float64,
...         }
...     },
...     hide_gridlines=True,
...     sheet_zoom=125,
... )

Создайте объект Worksheet и напрямую обратитесь к нему, добавив простую диаграмму. Настоятельно рекомендуется использовать структурированные ссылки для задания значений рядов данных и категорий диаграммы, чтобы не приходилось вычислять позиции ячеек относительно данных фрейма и листа:

>>> with Workbook("basic_chart.xlsx") as wb:  
...     # create worksheet object and write frame data to it
...     ws = wb.add_worksheet("demo")
...     df.write_excel(
...         workbook=wb,
...         worksheet=ws,
...         table_name="DataTable",
...         table_style="Table Style Medium 26",
...         hide_gridlines=True,
...     )
...     # create chart object, point to the written table
...     # data using structured references, and style it
...     chart = wb.add_chart({"type": "column"})
...     chart.set_title({"name": "Example Chart"})
...     chart.set_legend({"none": True})
...     chart.set_style(38)
...     chart.add_series(
...         {  # note the use of structured references
...             "values": "=DataTable[points]",
...             "categories": "=DataTable[id]",
...             "data_labels": {"value": True},
...         }
...     )
...     # add chart to the worksheet
...     ws.insert_chart("D1", chart)

Экспортируйте данные почти без форматирования (без форматирования чисел и стандартизированной точности для чисел с плавающей точкой), отключите автофильтр, но сохраните форматирование дат и даты/времени:

>>> import polars.selectors as cs
>>> df = pl.DataFrame(
...     {
...         "n1": [-100, None, 200, 555],
...         "n2": [987.4321, -200, 44.444, 555.5],
...     }
... )
>>> df.write_excel(  
...     column_formats={~cs.temporal(): "General"},
...     autofilter=False,
... )

© 2020 Ritchie Vink
© 2022 Polars contributors
Licensed under the MIT License.
https://docs.pola.rs/api/python/stable/reference/api/polars.DataFrame.write_excel.html