Skip to content

Commit 77189c2

Browse files
tvsotvso
authored
Add pivot table chapter (#4)
1 parent 26d0e53 commit 77189c2

File tree

3 files changed

+147
-2
lines changed

3 files changed

+147
-2
lines changed

‎en/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Excelize for Python is a Python port of Go [Excelize](https://github.com/xuri/ex
99
- PyPI: [pypi.org/project/excelize](https://pypi.org/project/excelize)
1010
- Licenses: [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause)
1111
- Last version: [v0.0.4](https://github.com/xuri/excelize-py/releases/latest)
12-
- Document update time: August 18, 2025
12+
- Document update time: August 19, 2025
1313

1414
## Project mission
1515

‎en/SUMMARY.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,4 +122,8 @@
122122
* [Insert page break in stream](stream.md#InsertPageBreak)
123123
* [Data](data.md)
124124
* [Add slicer](data.md#AddSlicer)
125-
* [Delete slicer](data.md#DeleteSlicer)
125+
* [Delete slicer](data.md#DeleteSlicer)
126+
* [Pivot Table](pivot.md#PivotTable)
127+
* [Create pivot table](pivot.md#AddPivotTable)
128+
* [Get pivot tables](pivot.md#GetPivotTables)
129+
* [Delete pivot table](pivot.md#DeletePivotTable)

‎en/pivot.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Pivot Table {#PivotTable}
2+
3+
A pivot table is a table of statistics that summarizes the data of a more extensive table (such as from a database, spreadsheet, or business intelligence program). This summary might include sums, averages, or other statistics, which the pivot table groups together in a meaningful way.
4+
5+
`PivotTableOptions` directly maps the format settings of the pivot table.
6+
7+
```python
8+
class PivotTableOptions:
9+
data_range: str = ""
10+
pivot_table_range: str = ""
11+
name: str = ""
12+
rows: Optional[List[PivotTableField]] = None
13+
columns: Optional[List[PivotTableField]] = None
14+
data: Optional[List[PivotTableField]] = None
15+
filter: Optional[List[PivotTableField]] = None
16+
row_grand_totals: bool = False
17+
col_grand_totals: bool = False
18+
show_drill: bool = False
19+
use_auto_formatting: bool = False
20+
page_over_then_down: bool = False
21+
merge_item: bool = False
22+
classic_layout: bool = False
23+
compact_data: bool = False
24+
show_error: bool = False
25+
show_row_headers: bool = False
26+
show_col_headers: bool = False
27+
show_row_stripes: bool = False
28+
show_col_stripes: bool = False
29+
show_last_column: bool = False
30+
field_print_titles: bool = False
31+
item_print_titles: bool = False
32+
pivot_table_style_name: str = ""
33+
```
34+
35+
`pivot_table_style_name`: The built-in pivot table style names:
36+
37+
```text
38+
PivotStyleLight1 - PivotStyleLight28
39+
PivotStyleMedium1 - PivotStyleMedium28
40+
PivotStyleDark1 - PivotStyleDark28
41+
```
42+
43+
`PivotTableField` directly maps the field settings of the pivot table.
44+
45+
```python
46+
class PivotTableField:
47+
compact: bool = False
48+
data: str = ""
49+
name: str = ""
50+
outline: bool = False
51+
show_all: bool = False
52+
insert_blank_row: bool = False
53+
subtotal: str = ""
54+
default_subtotal: bool = False
55+
num_fmt: int = 0
56+
```
57+
58+
`subtotal` specifies the aggregation function that applies to this data field. The default value is `Sum`. The possible values for this attribute are:
59+
60+
|Optional Value|
61+
|---|
62+
|Average|
63+
|Count|
64+
|CountNums|
65+
|Max|
66+
|Min|
67+
|Product|
68+
|StdDev|
69+
|StdDevp|
70+
|Sum|
71+
|Var|
72+
|Varp|
73+
74+
`name` specifies the name of the data field. Maximum `255` characters are allowed in data field name, excess characters will be truncated.
75+
76+
## Create pivot table {#AddPivotTable}
77+
78+
```python
79+
def add_pivot_table(self, opts: Optional[PivotTableOptions]) -> None
80+
```
81+
82+
Add pivot table by given pivot table options.
83+
84+
For example, create a pivot table on the `Sheet1!$G$2:$M$34` area with the region `Sheet1!$A$1:$E$31` as the data source, summarize by sum for sales:
85+
86+
<p align="center"><img width="1117" src="https://xuri.me/excelize/en/images/pivot_table_01.png" alt="create pivot table with excelize using Go"></p>
87+
88+
```python
89+
import excelize
90+
import random
91+
92+
f = excelize.new_file()
93+
month = [
94+
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
95+
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
96+
]
97+
year = [2017, 2018, 2019]
98+
types = ["Meat", "Dairy", "Beverages", "Produce"]
99+
region = ["East", "West", "North", "South"]
100+
try:
101+
f.set_sheet_row("Sheet1", "A1", ["Month", "Year", "Type", "Sales", "Region"])
102+
for row in range(2, 32):
103+
f.set_cell_value("Sheet1", f"A{row}", month[random.randrange(12)])
104+
f.set_cell_value("Sheet1", f"B{row}", year[random.randrange(3)])
105+
f.set_cell_value("Sheet1", f"C{row}", types[random.randrange(4)])
106+
f.set_cell_value("Sheet1", f"D{row}", random.randrange(5000))
107+
f.set_cell_value("Sheet1", f"E{row}", region[random.randrange(4)])
108+
109+
f.add_pivot_table(
110+
excelize.PivotTableOptions(
111+
data_range="Sheet1!A1:E31",
112+
pivot_table_range="Sheet1!G2:M34",
113+
rows=[
114+
excelize.PivotTableField(data="Month", default_subtotal=True),
115+
excelize.PivotTableField(data="Year"),
116+
],
117+
filter=[excelize.PivotTableField(data="Region")],
118+
columns=[
119+
excelize.PivotTableField(data="Type", default_subtotal=True),
120+
],
121+
data=[
122+
excelize.PivotTableField(
123+
data="Sales", name="Summarize", subtotal="Sum",
124+
)
125+
],
126+
row_grand_totals=True,
127+
col_grand_totals=True,
128+
show_drill=True,
129+
show_row_headers=True,
130+
show_col_headers=True,
131+
show_last_column=True,
132+
)
133+
)
134+
f.save_as("Book1.xlsx")
135+
except (RuntimeError, TypeError) as err:
136+
print(err)
137+
finally:
138+
err = f.close()
139+
if err:
140+
print(err)
141+
```

0 commit comments

Comments
 (0)