Pictures

class Pictures(impl: Any)

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: str | PathLike[str] | Any, link_to_file: bool = False, save_with_document: bool = True, left: float | None = None, top: float | None = None, width: float | None = None, height: float | None = None, name: str | None = None, update: bool = False, scale: float | None = None, format: str | None = None, anchor: Range | None = None, export_options: dict[str, Any] | None = None) → Picture

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 for anchor.

topfloat, default None

Top position in points, defaults to 0. If you use top/left, you must not provide a value for anchor.

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 for top/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 to write_image().

Added in version 0.27.7.

Returns

Picture

Examples

  1. 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>>

  1. 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: Any

Returns the native object (pywin32 or appscript obj) of the engine being used.

property count: int

Returns the number of objects in the collection.