WorkSheet
The Worksheet is the core component of the application. It stores cell values, formulas, and styles, and provides methods to manipulate the cells.
Create a WorkSheet
The default WorkSheet 'Sheet1' is created when the Workbook is created. You can access the WorkSheet through an index, as shown in the code snippet below:
| Parameter | Data Type | Description |
|---|---|---|
sheet_name |
str |
Sheet Name |
pre_allocate |
dict[str, int] |
Pre-allocate the memory space of given row and column numbers |
plain_data |
list[list] (Optional) |
Row and Column to write the excel without style |
You can also create a new WorkSheet by calling the create_sheet(sheet_name: str) function:
If you know the dimension of the data you want to write. You can use pre_allocate
to pre_allocate the memory space of the pyfastexcel to improve the performance.
from pyfastexcel import Workbook
pre_allocate = {'n_rows': 1000, 'n_cols': 10}
# This will pre_allocate the memory space of the pyfastexcel
wb = Workbook(pre_allocate=pre_allocate)
wb.save('pre_allocate.xlsx')
If you don't need any style for the excel. You could also write the excel without any style with the following code (This is the fastest way to write the excel):
from pyfastexcel import Workbook
data = [[1, 2, 3], [4, 5, 6, 7, 8]]
# This will write the data into the default sheet 'Sheet1'
wb = Workbook()
wb.create_sheet('New Sheet', plain_data=data)
wb.save('plain_data.xlsx')
Note
"You can only specify either pre_allocate or plain_data at a time, not both.
Assign a value to a cell
There are multiple methods to assign a value and style to a cell. If you would like to adopt
a style to a cell, you should create a CustomStyle first and register it with the set_custom_style function. The first args in the set_custom_style function is the name of the style, and the second args is the CustomStyle instance. After you register the style, you can assign the style to a cell by passing the style name as the second element in the tuple. Besides, you can also assign the style by directly passing the CustomStyle instance to the cell.
from pyfastexcel import Workbook
from pyfastexcel.utils import set_custom_style
from openpyxl_style_writer import CustomStyle
wb = Workbook()
ws = wb['Sheet1']
# Create and register the style
bold_style = CustomStyle(font_size=19, font_bold=True)
set_custom_style('bold_style', bold_style)
# Assign a value to a cell with default_style
ws['A1'] = 1
# Assign a value to a cell with custom_style
ws['A2'] = (2, 'bold_style')
# Assign a value to a cell with custom_style instance (This method don't need to call set_custom_style)
ws['A3'] = (9, bold_style)
Style Setting
pyfastexcel accept the style as a tuple (value, style). If the style is not provided, the default style will be used. The default style is defined in the Workbook class.
Style assignment without set_custom_style
pyfastexcel support the style assignment without calling set_custom_style. You can directly pass the CustomStyle instance to the cell. pyfastexcel will register the style name with the auto increment id. This may lead to the style being duplicated in the workbook, and potentially decrease the performance.
Why not use a class instance for 'Cells'?
Although creating the cell value as a Cell class can make the cell
assignment more readable, such as ws['A1'].value = 10
or ws['A1'].style = a_style, the tuple method is more
efficient in terms of performance.
from pyfastexcel import CustomStyle, Workbook
from pyfastexcel.utils import set_custom_style
wb = Workbook()
ws = wb['Sheet1']
# Create and register the style
bold_style = CustomStyle(font_size=19, font_bold=True)
set_custom_style('bold_style', bold_style)
# Assign a value to a cell with default_style
ws['A1':'D1'] = [1, 2, 3, 4]
# Assign a value to a cell with string slice
ws['E1:G1'] = [1, 2, 3]
# Assign a value to a cell with custom_style
ws['A2':'D2'] = [
(2, 'bold_style'),
('12', 'bold_style'),
6, # (1)
(8, 'bold_style')
]
# Assign data to the range A2:D3. The dimensions of the input data
# must match the selected range.
ws['A2':'D3'] = [
[
(2, 'bold_style'),
('12', 'bold_style'),
6, # (1)
(8, 'bold_style')
],
[
(1, 'bold_style'),
(2, 'bold_style'),
3, # (1)
(9, 'bold_style')
],
]
- The default style will be used.
from pyfastexcel import CustomStyle, Workbook
from pyfastexcel.utils import set_custom_style
wb = Workbook()
ws = wb['Sheet1']
# Create and register the style
bold_style = CustomStyle(font_size=19, font_bold=True)
set_custom_style('bold_style', bold_style)
# Assign a value to a cell with default_style
ws[0] = [1, 2, 3, 4]
# Assign a value to a cell with custom_style
ws[1] = [
(2, 'bold_style'),
('12', 'bold_style'),
6
(8, 'bold_style')
]
Set Cell by row and columns index
Set the cell value by row and column index.
| Parameter | Data Type | Description |
|---|---|---|
row |
int | Target row. |
column |
int | Target column. |
value |
Any | The value to set in the cell. |
style |
CustomStyle or str | Style to apply to the cells. |
from pyfastexcel import Workbook
from pyfastexcel.utils import set_custom_style
wb = Workbook()
ws = wb['Sheet1']
# Create and register the style
bold_style = CustomStyle(font_size=19, font_bold=True)
set_custom_style('bold_style', bold_style)
# Set style with the register name
ws.cell(0, 0, 'Hello', style='bold_style')
# Set style with the CustomStyle instance
ws.cell(0, 1, '123', style=bold_style)
Note
The row and column index are 0-based. So if you want to set the value in the first row and the first column like A1 in excel, you should use ws.cell(0, 0, 'Hello').
Set Style
Set style with input coordinate.
| Parameter | Data Type | Description |
|---|---|---|
target |
str, slice, or list[int, int] | Target cells to apply style. |
style |
CustomStyle or str | Style to apply to the cells. |
from pyfastexcel import Workbook
from pyfastexcel.utils import set_custom_style
wb = Workbook()
ws = wb['Sheet1']
# Create and register the style
bold_style = CustomStyle(font_size=19, font_bold=True)
set_custom_style('bold_style', bold_style)
ws[0] = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I']
# Set style with CustomStyle instance
ws.set_style('A1', bold_style)
# Set style with the register name
ws.set_style('B1', 'bold_style')
# Set style with the string slice
ws.set_style('C1:E1', 'bold_style')
ws.set_style(slice('F1', 'H1'), 'bold_style')
# Set style across the row
ws.set_style("C1:E3", 'bold_style')
# Set style with the row and column index ([0, 8] = 'I1')
ws.set_style([0, 8], 'bold_style')
Set cell width and height
Set column width
| Parameter | Data Type | Description |
|---|---|---|
col |
str | The column number |
value |
str | The value of the width |
# Set through alphabet
ws.set_cell_width('A', 20)
# Set through number
ws.set_cell_width(1, 23)
Set row height
| Parameter | Data Type | Description |
|---|---|---|
row |
str or int | The row number |
value |
int | The value of the height |
Set Sheet Visibility
Set the visibility of the sheet. The following example will display the Sheet2 and hide the Sheet1.
from pyfastexcel import Workbook
wb = Workbook()
wb.create_sheet('Sheet2')
ws = wb['Sheet1']
# Set the sheet to be hidden
ws.sheet_visible = False
wb.save('sheet_visibility.xlsx')
Merge Cell
The cell can be merged through the function. You can choose to use either two parameters or one parameter to merge.
Note
- The function supports merging cells using either individual cell references or a cell range.
- Ensure that the
top-left cellis specified before thebottom-right cellwhen using two parameters. - Cell references should be valid within the sheet's boundaries (rows: 1 to 1,048,576, columns: A to XFD).
| Parameter | Data Type | Description |
|---|---|---|
top_left_cell |
str | The index of the top left cell |
bottom_right_cell |
str | The index of the bottom right cell |
| Parameter | Data Type | Description |
|---|---|---|
cell_range |
str | The cell range to merge |
AutoFilter
Create an auto filter in a worksheet.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
target_range |
str | The range where the auto filter will be applied. |
Example
Set Panes
Configure the pane settings for a specific sheet in an Excel file using the provided Excelize file.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
freeze |
bool | Determines if the panes are frozen. |
split |
bool | Determines if the panes are split. |
x_split |
int | The horizontal position where the panes are split, or the column index that should be frozen. |
y_split |
int | The vertical position where the panes are split, or the row index that should be frozen. |
top_left_cell |
str | The cell at the top left of the visible window. |
active_pane |
str | The active pane. |
selection |
list[dict[str, str]] | The selection settings for panes. |
Key of selection
The key of the selection is sq_ref, active_cell, and pane. sq_ref and active_cell
should be a cell reference, and pane should be one of the topLeft, topRight, bottomLeft, and bottomRight.
Options of active_pane
The options for active_pane and are topLeft, topRight, bottomLeft, and bottomRight.
Note
When freeze is set to true, x_split and y_split represent the column or row index where the panes are
frozen. When split is set to true, x_split and y_split represent the pixel position where the panes are split.
Example
from pyfastexcel.utils import Selection
# Freeze 1 to 6 rows
ws.set_panes(
freeze=True,
y_split=6,
top_left_cell="A34",
active_pane="bottomLeft",
selection=[
Selection(sq_ref="A7", active_cell="A7", pane="bottomLeft")
],
)
# Set panes's selection with dict
ws.set_panes(
freeze=True,
y_split=6,
top_left_cell="A34",
active_pane="bottomLeft",
selection=[
{
"sq_ref": "A7",
"active_cell": "A7",
"pane": "bottomLeft",
}
],
)
The example to split the panes
from pyfastexcel.utils import Selection
ws.set_panes(
split=True,
x_split=3500,
y_split=3500,
top_left_cell="L30",
active_pane="bottomLeft",
selection=[
Selection(sq_ref="A1", active_cell="A1", pane="topRight")
],
)
Set Data Validation
Set data validation for a specified range in a worksheet.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
sq_ref |
str | The range to set the data validation. |
set_range |
list[int or float] | The range of values to set the data validation. |
input_msg |
list[str] | The input message for the data validation. Must be a list with two elements: [Title, Body]. |
drop_list |
list[str] or str | The drop list for the data validation. Can be a list of strings or a range in the format "A1:B2". |
error_msg |
list[str] | The error message for the data validation. Must be a list with two elements: [Title, Body]. |
Example
# Example 1: Setting data validation with a specified range, input message, drop-down list, and error message
ws.set_data_validation(
sq_ref="A1:B2",
set_range=[1, 10],
input_msg=["Input Title", "Input Body"],
drop_list=["Option1", "Option2", "Option3"],
error_msg=["Error Title", "Error Body"]
)
# Example 2: Setting data validation with a drop-down list based on cell values
ws.set_data_validation(
sq_ref="A1:B2",
drop_list="C1:C5",
)
Add Comment
Adds a comment to the specified cell.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
cell |
str |
The cell location to add the comment. |
author |
str |
The author of the comment. |
text |
str or dict[str, str] or list[str or dict[str, str]] |
The text of the comment, and it's font style |
Example
from pyfastexcel.utils import CommentText
# Add a comment to cell A1 with CommentText Instance
comment_text = CommentText(text='Comment', bold=True)
ws.add_comment("A1", "pyfastexcel", comment_text)
# Add a comment to cell B1 with list of CommentText Instance
comment_text = CommentText(text='Comment', bold=True)
comment_text2 = CommentText(text=' Comment two', color='00ff00')
ws.add_comment("B1", "pyfastexcel", [comment_text, comment_text2])
# Add a comment to cell C1, and use string as the comment text
ws.add_comment("C1", "pyfastexcel", "This is a comment.")
# Add a comment to cell D1, and use dictionary as the comment text and set the font style
ws.add_comment("D1", "pyfastexcel", {"text": "This is a comment.", 'bold': True, 'italic': True})
# Add a comment to cell E1, and use list of dictionary as the comment text and set the font style
# This will create "This is a comment" with bold and italic font style, and "This is another comment" with bold and red color font style.
ws.add_comment(
"E1",
"pyfastexcel",
[
{
"text": "This is a comment.",
'bold': True,
'italic': True
},
{
"text": "This is another comment.",
'bold': True,
'color': 'FF0000'
}
]
)
Here is the key words of the comment when using the dictionary:
| Key | Data Type | Description |
|---|---|---|
text |
str | The text of the comment. |
size |
int | The font size of the comment text. |
name |
str | The font name of the comment text. |
bold |
bool | Sets the comment text to bold. |
italic |
bool | Sets the comment text to italic. |
underline |
str | Sets the underline style of the comment text. |
strike |
bool | Sets whether the comment text is strike through. |
vertAlign |
str | Sets the vertical alignment of the comment text. |
color |
str | Sets the font color of the comment text. |
Note
The text parameter can be a string, a dictionary, or a list of dictionaries. If it is a string, it will be treated as the comment text. If it is a dictionary, it should contain the key text with the comment's text as the corresponding value. If it is a list of dictionaries, each dictionary should contain the key text with the comment's text as the corresponding value.
Group Columns
Group columns in a worksheet. This function is currently implemented using openpyxl.
It is not recommended to use this function when dealing with large files.
Note
- Excelize does not currently support column grouping in Streaming mode.
- By default, if you call the
group_columnsfunction, pyfastexcel will write the Excel file using the normal API of Excelize, which is slower than Streaming mode. - As an alternative method, you can set the
engineparameter toopenpyxl. This will allow pyfastexcel to first write other Excel content using Streaming mode, and then load_workbook withopenpyxland use theopenpyxlAPI to group columns and save the file.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
start_col |
str | The cell reference where grouping starts. |
end_col |
Optional[str] | The cell reference where grouping ends. |
outline_level |
int | The level of grouping. |
hidden |
bool | Whether to hide the group or not. |
engine |
Literal['pyfastexcel', 'openpyxl'] | The engine to group columns |
Group Rows
Group Rows in a worksheet. This function is currently implemented using openpyxl.
It is not recommended to use this function when dealing with large files.
Note
- Excelize does not currently support column grouping in Streaming mode.
- By default, if you call the
group_rowsfunction, pyfastexcel will write the Excel file using the normal API of Excelize, which is slower than Streaming mode. - As an alternative method, you can set the
engineparameter toopenpyxl. This will allow pyfastexcel to first write other Excel content using Streaming mode, and then load_workbook withopenpyxland use theopenpyxlAPI to group rows and save the file.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
start_row |
int | The row reference where grouping starts. |
end_row |
Optional[int] | The row reference where grouping ends. |
outline_level |
int | The level of grouping. |
hidden |
bool | Whether to hide the group or not. |
engine |
Literal['pyfastexcel', 'openpyxl'] | The engine to group rows |
Create Table
Create a table in a sheet.
Note
There are some limitations when creating a table: 1. A table must always be created with at least one row of data. For example, if you want to create a table in the range 'A1:B3', you should first ensure that there is data in the range 'A1:A3'; otherwise, the table will not be created correctly. 2. Tables should not overlap with one another.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
cell_range |
str | The cell reference range, e.g., 'A1:B3'. |
name |
str | The name of the table. |
style_name |
str | The built-in style name for the table in Excel. |
show_first_column |
bool | Whether to display the first column. |
show_last_column |
bool | Whether to display the last column. |
show_row_stripes |
bool | Whether to display row stripes. |
show_column_stripes |
bool | Whether to display column stripes. |
Add Chart
The add_chart method allows for adding charts to a worksheet, either by specifying chart attributes directly or by using predefined Chart objects. This method is overloaded to accommodate different ways of defining and adding charts.
Parameters
| Parameter | Data Type | Description |
|---|---|---|
cell |
str | The cell reference range, e.g., 'Sheet1!A1:B3'. |
chart_model |
Chart or list[Chart] | The pydantic Chart |
from pyfastexcel import Workbook
from pyfastexcel.chart import (
Chart,
ChartSeries,
RichTextRun,
Font,
ChartAxis,
ChartLegend,
Fill,
Marker,
)
wb = Workbook()
ws = wb['Sheet1']
ws[0] = ['Category', '2024/01', '2024/02', '2024/03']
ws[1] = ['Food', 123, 125, 645]
ws[2] = ['Book', 456, 789, 321]
ws[3] = ['Phone', 777, 66, 214]
column_chart = Chart(
chart_type='col',
series=[
ChartSeries(
name='Sheet1!A2',
categories='Sheet1!B1:D1',
values='Sheet1!B2:D2',
fill=Fill(ftype='pattern', pattern=1, color='ebce42'),
marker=Marker(symbol='none'),
),
ChartSeries(
name='Sheet1!A3',
categories='Sheet1!B1:D1',
values='Sheet1!B3:D3',
fill=Fill(ftype='pattern', pattern=1, color='29a64b'),
marker=Marker(symbol='none'),
),
],
legend=ChartLegend(position='top', show_legend_key=True),
)
line_chart = Chart(
chart_type='line',
series=[
ChartSeries(
name='Sheet1!A4',
categories='Sheet1!B1:D1',
values='Sheet1!B4:D4',
fill=Fill(ftype='pattern', pattern=1, color='0000FF'),
marker=Marker(
symbol='circle',
fill=Fill(ftype='pattern', pattern=1, color='FFFF00'),
),
),
],
title=[RichTextRun(text='Example Chart', font=Font(color='FF0000', bold=True))],
x_axis=ChartAxis(major_grid_lines=True, font=Font(color='000000')),
y_axis=ChartAxis(major_grid_lines=True, font=Font(color='000000')),
legend=ChartLegend(position='top', show_legend_key=True),
)
ws.add_chart('E1', [column_chart, line_chart])
| Parameter | Data Type | Description |
|---|---|---|
cell |
str | The cell reference where the chart will be added. |
chart_type |
str | The type of chart (e.g., 'bar', 'line'). |
series |
List[ChartSeries] or ChartSeries | The data series to be plotted. |
graph_format |
Optional[GraphicOptions] | Graphical options for the chart. |
title |
Optional[List[RichTextRun]] | The title of the chart. |
legend |
Optional[ChartLegend] | Legend settings for the chart. |
dimension |
Optional[ChartDimension] | Dimensions of the chart. |
vary_colors |
Optional[bool] | Whether to vary colors by data point. |
x_axis |
Optional[ChartAxis] | Configuration of the X-axis. |
y_axis |
Optional[ChartAxis] | Configuration of the Y-axis. |
plot_area |
Optional[ChartPlotArea] | Configuration of the plot area. |
fill |
Optional[Fill] | Fill settings for the chart. |
border |
Optional[Line] | Border settings for the chart. |
show_blanks_as |
Optional[str] | How to display blanks in the chart. |
bubble_size |
Optional[int] | Size of bubbles in a bubble chart. |
hole_size |
Optional[int] | Size of the hole in a doughnut chart. |
order |
Optional[int] | The order of the series in the chart. |
from pyfastexcel import Workbook
from pyfastexcel.chart import (
Chart,
ChartSeries,
RichTextRun,
Font,
ChartAxis,
ChartLegend,
Fill,
Marker,
)
wb = Workbook()
ws = wb['Sheet1']
ws[0] = ['Category', '2024/01', '2024/02', '2024/03']
ws[1] = ['Food', 123, 125, 645]
ws[2] = ['Book', 456, 789, 321]
ws[3] = ['Phone', 777, 66, 214]
ws.add_chart(
'E1',
chart_type='col',
series=[
ChartSeries(
name='Sheet1!A2',
categories='Sheet1!B1:D1',
values='Sheet1!B2:D2',
fill=Fill(ftype='pattern', pattern=1, color='ebce42'),
marker=Marker(symbol='none'),
),
ChartSeries(
name='Sheet1!A3',
categories='Sheet1!B1:D1',
values='Sheet1!B3:D3',
fill=Fill(ftype='pattern', pattern=1, color='29a64b'),
marker=Marker(symbol='none'),
),
],
legend=ChartLegend(position='top', show_legend_key=True),
)
Add Pivot Table
This function allows you to add a pivot table to a worksheet using either a PivotTable object or by specifying ranges and fields directly. You can customize the appearance and functionality of the pivot table using various optional parameters.
Note
- You can either pass a
PivotTableobject or directly specify the data range, pivot table range, and fields. - Ensure that the data range and pivot table range are correctly formatted and within the sheet's valid boundaries.
- Optional parameters allow you to control the visibility of row and column headers, grand totals, stripes, and more.
Adding a Pivot Table Using a PivotTable Object or a List of PivotTable
| Parameter | Data Type | Description |
|---|---|---|
pivot_table |
PivotTable \| list[PivotTable] |
A single PivotTable object or a list of PivotTable objects to add to the worksheet. |
from pyfastexcle.pivot import PivotTable, PivotTableField
pivot_table_object = PivotTable(
data_range="Sheet1!A1:B10",
pivot_table_range="Sheet1!C3:D10",
rows=[PivotTableField()],
columns=[PivotTableField()],
data=[PivotTableField()],
row_grand_totals=True,
column_grand_totals=False,
pivot_table_style_name="PivotStyleMedium9"
)
# Add a pivot table using a PivotTable object
ws.add_pivot_table(pivot_table=pivot_table_object)
Adding a Pivot Table by Specifying Ranges and Fields
| Parameter | Data Type | Description |
|---|---|---|
data_range |
str |
The range of data to be used in the pivot table, e.g., "Sheet1!A1:B2". |
pivot_table_range |
str |
The range where the pivot table will be positioned, e.g., "Sheet1!C3:D4". |
rows |
list[PivotTableField] |
List of fields used as rows in the pivot table. |
pivot_filter |
list[PivotTableField] |
List of fields used as filters in the pivot table. |
columns |
list[PivotTableField] |
List of fields used as columns in the pivot table. |
data |
list[PivotTableField] |
List of fields used as data fields in the pivot table. |
row_grand_totals |
Optional[bool] |
Whether to display row grand totals. |
column_grand_totals |
Optional[bool] |
Whether to display column grand totals. |
show_drill |
Optional[bool] |
Whether to show drill indicators. |
show_row_headers |
Optional[bool] |
Whether to display row headers. |
show_column_headers |
Optional[bool] |
Whether to display column headers. |
show_row_stripes |
Optional[bool] |
Whether to display row stripes. |
show_col_stripes |
Optional[bool] |
Whether to display column stripes. |
show_last_column |
Optional[bool] |
Whether to highlight the last column. |
use_auto_formatting |
Optional[bool] |
Whether to use automatic formatting for the pivot table. |
page_over_then_down |
Optional[bool] |
Whether to order pages from top to bottom then left to right. |
merge_item |
Optional[bool] |
Whether to merge items. |
compact_data |
Optional[bool] |
Whether to display data in a compact form. |
show_error |
Optional[bool] |
Whether to display errors in the pivot table. |
classic_layout |
Optional[bool] |
Specifies whether to apply the classic layout style to the pivot table. |
pivot_table_style_name |
Optional[str] |
The style name to apply to the pivot table. |
from pyfastexcel.pivot import PivotTableField
# Add a pivot table by specifying the data range, pivot table range, and fields
ws.add_pivot_table(
data_range="Sheet1!A1:B10",
pivot_table_range="Sheet1!C3:D10",
rows=[PivotTableField()],
columns=[PivotTableField()],
data=[PivotTableField()],
row_grand_totals=True,
column_grand_totals=False,
pivot_table_style_name="PivotStyleMedium9"
)