Pictures¶
- class Pictures(impl)¶
A collection of all
picture
objects on the specified sheet:>>> import xlwings as xw >>> xw.books['Book1'].sheets[0].pictures Pictures([<Picture 'Picture 1' in <Sheet [Book1]Sheet1>>, <Picture 'Picture 2' in <Sheet [Book1]Sheet1>>])
Added in version 0.9.0.
- add(image, link_to_file=False, save_with_document=True, left=None, top=None, width=None, height=None, name=None, update=False, scale=None, format=None, anchor=None, export_options=None)¶
Adds a picture to the specified sheet.
Arguments¶
- imagestr or path-like object or matplotlib.figure.Figure
Either a filepath or a Matplotlib figure object.
- leftfloat, default None
Left position in points, defaults to 0. If you use
top
/left
, you must not provide a value foranchor
.- topfloat, default None
Top position in points, defaults to 0. If you use
top
/left
, you must not provide a value foranchor
.- widthfloat, default None
Width in points. Defaults to original width.
- heightfloat, default None
Height in points. Defaults to original height.
- namestr, default None
Excel picture name. Defaults to Excel standard name if not provided, e.g., ‘Picture 1’.
- updatebool, default False
Replace an existing picture with the same name. Requires
name
to be set.- scalefloat, default None
Scales your picture by the provided factor.
- formatstr, default None
Only used if image is a Matplotlib or Plotly plot. By default, the plot is inserted in the “png” format, but you may want to change this to a vector-based format like “svg” on Windows (may require Microsoft 365) or “eps” on macOS for better print quality. If you use
'vector'
, it will be using'svg'
on Windows and'eps'
on macOS. To find out which formats your version of Excel supports, see: https://support.microsoft.com/en-us/topic/support-for-eps-images-has-been-turned-off-in-office-a069d664-4bcf-415e-a1b5-cbb0c334a840- anchor: xw.Range, default None
The xlwings Range object of where you want to insert the picture. If you use
anchor
, you must not provide values fortop
/left
.Added in version 0.24.3.
- export_optionsdict, default None
For Matplotlib plots, this dictionary is passed on to
image.savefig()
with the following defaults:{"bbox_inches": "tight", "dpi": 200}
, so if you want to leave the picture uncropped and increase dpi to 300, use:export_options={"dpi": 300}
. For Plotly, the options are passed towrite_image()
.Added in version 0.27.7.
Returns¶
Picture
Examples¶
Picture
>>> import xlwings as xw >>> sht = xw.Book().sheets[0] >>> sht.pictures.add(r'C:\path\to\file.png') <Picture 'Picture 1' in <Sheet [Book1]Sheet1>>
Matplotlib
>>> import matplotlib.pyplot as plt >>> fig = plt.figure() >>> plt.plot([1, 2, 3, 4, 5]) >>> sht.pictures.add(fig, name='MyPlot', update=True) <Picture 'MyPlot' in <Sheet [Book1]Sheet1>>
- property api¶
Returns the native object (
pywin32
orappscript
obj) of the engine being used.
- property count¶
Returns the number of objects in the collection.