0
# Charts and Visualization
1
2
Classes for creating and manipulating Excel charts, including support for matplotlib figure integration and chart customization. xlwings provides comprehensive charting capabilities that bridge Python's visualization libraries with Excel's native charting engine.
3
4
## Capabilities
5
6
### Chart Objects
7
8
Excel charts created and manipulated through xlwings, supporting various chart types and customization options.
9
10
```python { .api }
11
class Chart:
12
"""Represents an Excel chart object."""
13
14
def delete(self):
15
"""Delete the chart from the worksheet."""
16
17
def to_pdf(self, path: str):
18
"""
19
Export chart to PDF file.
20
21
Args:
22
path (str): Output file path for PDF.
23
"""
24
25
def to_png(self, path: str):
26
"""
27
Export chart to PNG image file.
28
29
Args:
30
path (str): Output file path for PNG image.
31
"""
32
33
@property
34
def name(self) -> str:
35
"""Chart name/title."""
36
37
@name.setter
38
def name(self, value: str): ...
39
40
@property
41
def chart_type(self):
42
"""Get/set chart type using Excel chart type constants."""
43
44
@chart_type.setter
45
def chart_type(self, value): ...
46
47
@property
48
def source_data(self) -> Range:
49
"""Range containing the chart's source data."""
50
51
@source_data.setter
52
def source_data(self, value: Range): ...
53
54
@property
55
def api(self):
56
"""Access to native Excel chart object for advanced manipulation."""
57
```
58
59
### Picture Objects
60
61
Handles images in Excel worksheets, supporting various image formats and matplotlib figure integration.
62
63
```python { .api }
64
class Picture:
65
"""Represents an image/picture in Excel worksheet."""
66
67
def delete(self):
68
"""Delete the picture from the worksheet."""
69
70
def update(self, image):
71
"""
72
Update picture with new image data.
73
74
Args:
75
image: New image data. Supports file paths, matplotlib figures,
76
PIL images, or image data.
77
"""
78
79
@property
80
def name(self) -> str:
81
"""Picture name/identifier."""
82
83
@property
84
def left(self) -> float:
85
"""Left position in points from worksheet origin."""
86
87
@left.setter
88
def left(self, value: float): ...
89
90
@property
91
def top(self) -> float:
92
"""Top position in points from worksheet origin."""
93
94
@top.setter
95
def top(self, value: float): ...
96
97
@property
98
def width(self) -> float:
99
"""Picture width in points."""
100
101
@width.setter
102
def width(self, value: float): ...
103
104
@property
105
def height(self) -> float:
106
"""Picture height in points."""
107
108
@height.setter
109
def height(self, value: float): ...
110
111
@property
112
def api(self):
113
"""Access to native Excel picture object."""
114
```
115
116
### Shape Objects
117
118
Represents Excel shapes and drawing objects, including text boxes, lines, and geometric shapes.
119
120
```python { .api }
121
class Shape:
122
"""Represents Excel shape/drawing object."""
123
124
def delete(self):
125
"""Delete the shape from the worksheet."""
126
127
def duplicate(self):
128
"""
129
Create a duplicate of this shape.
130
131
Returns:
132
Shape: New shape object that is a copy of this shape.
133
"""
134
135
@property
136
def name(self) -> str:
137
"""Shape name/identifier."""
138
139
@property
140
def type(self):
141
"""Shape type (text box, rectangle, line, etc.)."""
142
143
@property
144
def left(self) -> float:
145
"""Left position in points from worksheet origin."""
146
147
@left.setter
148
def left(self, value: float): ...
149
150
@property
151
def top(self) -> float:
152
"""Top position in points from worksheet origin."""
153
154
@top.setter
155
def top(self, value: float): ...
156
157
@property
158
def width(self) -> float:
159
"""Shape width in points."""
160
161
@width.setter
162
def width(self, value: float): ...
163
164
@property
165
def height(self) -> float:
166
"""Shape height in points."""
167
168
@height.setter
169
def height(self, value: float): ...
170
171
@property
172
def api(self):
173
"""Access to native Excel shape object for advanced manipulation."""
174
```
175
176
Usage examples:
177
178
```python
179
import xlwings as xw
180
import matplotlib.pyplot as plt
181
from xlwings.constants import ChartType
182
import numpy as np
183
184
wb = xw.books.add()
185
ws = wb.sheets[0]
186
187
# Create sample data and chart
188
ws.range('A1:B6').value = [
189
['Month', 'Sales'],
190
['Jan', 100], ['Feb', 120], ['Mar', 140],
191
['Apr', 110], ['May', 160]
192
]
193
194
chart = ws.charts.add()
195
chart.source_data = ws.range('A1:B6')
196
chart.chart_type = ChartType.xlColumnClustered
197
chart.name = 'Monthly Sales'
198
199
# Add matplotlib figure
200
fig, ax = plt.subplots()
201
x = np.linspace(0, 10, 100)
202
y = np.sin(x)
203
ax.plot(x, y)
204
ax.set_title('Sine Wave')
205
206
pic = ws.pictures.add(fig, name='SinePlot',
207
left=ws.range('E1').left,
208
top=ws.range('E1').top)
209
210
# Export visualizations
211
chart.to_png('/path/to/sales_chart.png')
212
chart.to_pdf('/path/to/sales_chart.pdf')
213
```
214
215
## Types
216
217
```python { .api }
218
# Chart and visualization types
219
ChartObject = Chart
220
PictureObject = Picture
221
ShapeObject = Shape
222
223
# Collection types
224
Charts = Collection[Chart]
225
Pictures = Collection[Picture]
226
Shapes = Collection[Shape]
227
228
# Position and size types
229
Position = tuple[float, float] # (left, top)
230
Size = tuple[float, float] # (width, height)
231
232
# Format types
233
ImageFormat = Literal['png', 'jpg', 'jpeg', 'bmp', 'gif']
234
ExportFormat = Literal['pdf', 'png', 'jpg']
235
ChartTypeConstant = int # Excel chart type constants
236
```