XL Wings
XL Wings
XL Wings
Release dev
1 Video course 1
2 Installation 3
2.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.5 How to activate xlwings PRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.6 Optional Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.7 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.8 Uninstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Quickstart 7
3.1 1. Interacting with Excel from a Jupyter notebook . . . . . . . . . . . . . . . . . . . . . . 7
3.2 2. Scripting: Automate/interact with Excel from Python . . . . . . . . . . . . . . . . . . . 7
3.3 3. Macros: Call Python from Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 4. UDFs: User Defined Functions (Windows only) . . . . . . . . . . . . . . . . . . . . . . 9
4 Connect to a Book 11
4.1 Python to Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Excel to Python (RunPython) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 User Defined Functions (UDFs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5 Syntax Overview 13
5.1 Active Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2 Full qualification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.3 App context manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4 Range indexing/slicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.5 Range Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.6 Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
i
6.2 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.3 Range expanding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.4 NumPy arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.5 Pandas DataFrames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.6 Pandas Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6.7 Chunking: Read/Write big DataFrames etc. . . . . . . . . . . . . . . . . . . . . . . . . . . 20
8 RunPython 29
8.1 xlwings add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
8.2 Call Python with “RunPython” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
8.3 Function Arguments and Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
13 Deployment 49
13.1 Zip files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
ii
13.2 RunFrozenPython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
14 Troubleshooting 51
14.1 Issue: dll not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
14.2 Issue: Couldn’t find the local location of your OneDrive or SharePoint . . . . . . . . . . . 51
16 Debugging 65
16.1 RunPython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
16.2 UDF debug server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
17 Extensions 69
17.1 In-Excel SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
18 Custom Add-ins 71
18.1 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
18.2 Changing the Ribbon menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
18.3 Importing UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
18.4 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
18.5 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
18.6 Renaming your add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
18.7 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
20 Missing Features 81
20.1 Example: Workaround to use VBA’s Range.WrapText . . . . . . . . . . . . . . . . . . 81
23 xlwings Reports 87
23.1 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
23.2 DataFrames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
23.3 Excel Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
23.4 Excel Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
23.5 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
23.6 Matplotlib and Plotly Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
iii
23.7 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
23.8 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
23.9 Number Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
23.10 Frames: Multi-column Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
23.11 PDF Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Index 205
iv
CHAPTER 1
Video course
Those who prefer a didactically structured video course over this documentation should have a look at our
video course:
https://training.xlwings.org/p/xlwings
It’s also a great way to support the ongoing development of xlwings :)
1
xlwings - Make Excel Fly!, Release dev
Installation
2.1 Prerequisites
• xlwings requires an installation of Excel and therefore only works on Windows and macOS. Note
that macOS currently does not support UDFs.
• xlwings requires at least Python 3.6.
Here are the last versions of xlwings to support:
• Python 3.5: 0.19.5
• Python 2.7: 0.16.6
2.2 Installation
or conda:
3
xlwings - Make Excel Fly!, Release dev
Note that the official conda package might be a few releases behind. You can, however, use the
conda-forge channel (replace install with upgrade if xlwings is already installed):
Note: When you are on macOS and are installing xlwings with conda (or use the version that comes with
Anaconda), you’ll need to run $ xlwings runpython install once to enable the RunPython
calls from VBA. This is done automatically if you install the addin via $ xlwings addin install.
2.3 Add-in
To call Excel from Python, you don’t need an add-in. Also, you can use a single file VBA module (stan-
dalone workbook) instead of the add-in. For more details, see Add-in & Settings.
Note: The add-in needs to be the same version as the Python package. Make sure to re-install the add-in
after upgrading the xlwings package.
2.4 Dependencies
• Windows: pywin32
• Mac: psutil, appscript
The dependencies are automatically installed via conda or pip.
xlwings PRO offers access to additional functionality. All PRO features are marked with xlwings PRO in
the docs.
Note: To get access to the additional functionality of xlwings PRO, you need a license key and at least xl-
wings v0.19.0. Everything under the xlwings.pro subpackage is distributed under a commercial license.
See xlwings PRO Overview for more details.
4 Chapter 2. Installation
xlwings - Make Excel Fly!, Release dev
Make sure to replace LICENSE_KEY with your personal key. This will store the license key under your
xlwings.conf file (see User Config: Ribbon/Config File for where this is on your system). Alternatively,
you can also store the license key as an environment variable with the name XLWINGS_LICENSE_KEY.
xlwings PRO requires additionally the cryptography and Jinja2 packages which come preinstalled
with Anaconda and WinPython. Otherwise, install them via pip or conda.
With pip, you can also run pip install "xlwings[pro]" which will take care of the extra depen-
dencies for xlwings PRO.
• NumPy
• Pandas
• Matplotlib
• Pillow/PIL
• Flask (for REST API)
• cryptography (for xlwings.pro)
• Jinja2 (for xlwings.pro.reports)
• requests (for permissioning)
These packages are not required but highly recommended as they play very nicely with xlwings. They are
all pre-installed with Anaconda. With pip, you can install xlwings with all optional dependencies as follows:
2.7 Update
To update to the latest xlwings version, run the following in a command prompt:
or:
Make sure to keep your version of the Excel add-in in sync with your Python package by running the
following (make sure to close Excel first):
2.8 Uninstall
To uninstall xlwings completely, first uninstall the add-in, then uninstall the xlwings package using the same
method (pip or conda) that you used for installing it:
Then
or:
Finally, manually remove the .xlwings directory in your home folder if it exists.
6 Chapter 2. Installation
CHAPTER 3
Quickstart
This guide assumes you have xlwings already installed. If that’s not the case, head over to Installation.
If you’re just interested in getting a pandas DataFrame in and out of your Jupyter notebook, you can use the
view and load functions, see Jupyter Notebooks: Interact with Excel.
If you have the same file open in two instances of Excel, you need to fully qualify it and include the app
instance. You will find your app instance key (the PID) via xw.apps.keys():
>>> xw.apps[10559].books['FileName.xlsx']
7
xlwings - Make Excel Fly!, Release dev
>>> sheet.range('A1').value = [['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.
˓→0]]
>>> sheet.range('A1').expand().value
[['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.0]]
Powerful converters handle most data types of interest, including Numpy arrays and Pandas DataFrames
in both directions:
You can call Python functions either by clicking the Run button (new in v0.16) in the add-in or from VBA
using the RunPython function:
The Run button expects a function called main in a Python module with the same name as your workbook.
The great thing about that approach is that you don’t need your workbooks to be macro-enabled, you can
save it as xlsx.
If you want to call any Python function no matter in what module it lives or what name it has, use
RunPython:
Sub HelloWorld()
RunPython "import hello; hello.world()"
End Sub
Note: Per default, RunPython expects hello.py in the same directory as the Excel file with the same
8 Chapter 3. Quickstart
xlwings - Make Excel Fly!, Release dev
name, but you can change both of these things: if your Python file is an a different folder, add that folder
to the PYTHONPATH in the config. If the file has a different name, change the RunPython command
accordingly.
# hello.py
import numpy as np
import xlwings as xw
def world():
wb = xw.Book.caller()
wb.sheets[0].range('A1').value = 'Hello World!'
To make this run, you’ll need to have the xlwings add-in installed or have the workbooks setup in the
standalone mode. The easiest way to get everything set up is to use the xlwings command line client from
either a command prompt on Windows or a terminal on Mac: xlwings quickstart myproject.
For details about the addin, see Add-in & Settings.
import xlwings as xw
@xw.func
def hello(name):
return f'Hello {name}'
Converters can be used with UDFs, too. Again a Pandas DataFrame example:
import xlwings as xw
import pandas as pd
@xw.func
@xw.arg('x', pd.DataFrame)
def correl2(x):
# x arrives as DataFrame
return x.corr()
Import this function into Excel by clicking the import button of the xlwings add-in: for a step-by-step
tutorial, see User Defined Functions (UDFs).
10 Chapter 3. Quickstart
CHAPTER 4
Connect to a Book
When reading/writing data to the active sheet, you don’t need a book object:
The easiest way to connect to a book is offered by xw.Book: it looks for the book in all app instances and
returns an error, should the same book be open in multiple instances. To connect to a book in the active app
instance, use xw.books and to refer to a specific app, use:
>>> app = xw.App() # or something like xw.apps[10559] for existing apps, get
˓→the available PIDs via xw.apps.keys()
>>> app.books['Book1']
Note that you usually should use App as a context manager as this will make sure that the Excel instance is
closed and cleaned up again properly:
xw.Book xw.books
New book xw.Book() xw.books.add()
Unsaved book xw.Book('Book1') xw.books['Book1']
Book by xw.Book(r'C:/path/to/ xw.books.open(r'C:/path/to/
(full)name file.xlsx') file.xlsx')
11
xlwings - Make Excel Fly!, Release dev
Note: When specifying file paths on Windows, you should either use raw strings by putting an r in front
of the string or use double back-slashes like so: C:\\path\\to\\file.xlsx.
To reference the calling book when using RunPython in VBA, use xw.Book.caller(), see Call
Python with “RunPython”. Check out the section about Debugging to see how you can call a script from
both sides, Python and Excel, without the need to constantly change between xw.Book.caller() and
one of the methods explained above.
Unlike RunPython, UDFs don’t need a call to xw.Book.caller(), see User Defined Functions
(UDFs). You’ll usually use the caller argument which returns the xlwings range object from where
you call the function.
Syntax Overview
The xlwings object model is very similar to the one used by VBA.
All code samples below depend on the following import:
# Active book
>>> wb = xw.books.active # in active app
>>> wb = app.books.active # in specific app
# Active sheet
>>> sheet = xw.sheets.active # in active book
>>> sheet = wb.sheets.active # in specific book
A Range can be instantiated with A1 notation, a tuple of Excel’s 1-based indices, a named range or two
Range objects:
xw.Range('A1')
xw.Range('A1:C3')
xw.Range((1,1))
(continues on next page)
13
xlwings - Make Excel Fly!, Release dev
Round brackets follow Excel’s behavior (i.e. 1-based indexing), while square brackets use Python’s 0-based
indexing/slicing. As an example, the following expressions all reference the same range:
xw.apps[763].books[0].sheets[0].range('A1')
xw.apps(10559).books(1).sheets(1).range('A1')
xw.apps[763].books['Book1'].sheets['Sheet1'].range('A1')
xw.apps(10559).books('Book1').sheets('Sheet1').range('A1')
Note that the apps keys are different for you as they are the process IDs (PID). You can get the list of your
PIDs via xw.apps.keys().
If you want to open a new Excel instance via App(), you usually should use App as a context manager as
this will make sure that the Excel instance is closed and cleaned up again properly:
with xw.App() as app:
book = app.books['Book1']
Sheet objects offer a shortcut for range objects by using index/slice notation on the sheet object. This evalu-
ates to either sheet.range or sheet.cells depending on whether you pass a string or indices/slices:
The following shows an example of the object hierarchy, i.e. how to get from an app to a range object and
all the way back:
This tutorial gives you a quick introduction to the most common use cases and default behaviour of xlwings
when reading and writing values. For an in-depth documentation of how to control the behavior using the
options method, have a look at Converters and Options.
All code samples below depend on the following import:
Single cells are by default returned either as float, unicode, None or datetime objects, depending
on whether the cell contains a number, a string, is empty or represents a date:
17
xlwings - Make Excel Fly!, Release dev
6.2 Lists
• 1d lists: Ranges that represent rows or columns in Excel are returned as simple lists, which means
that once they are in Python, you’ve lost the information about the orientation. If that is an issue, the
next point shows you how to preserve this info:
>>> sheet.range('A1').options(ndim=1).value
[1.0]
• 2d lists: If the row or column orientation has to be preserved, set ndim in the Range options. This
will return the Ranges as nested lists (“2d lists”):
>>> sheet.range('A1:A5').options(ndim=2).value
[[1.0], [2.0], [3.0], [4.0], [5.0]]
>>> sheet.range('A1:E1').options(ndim=2).value
[[1.0, 2.0, 3.0, 4.0, 5.0]]
• 2 dimensional Ranges are automatically returned as nested lists. When assigning (nested) lists to a
Range in Excel, it’s enough to just specify the top left cell as target address. This sample also makes
use of index notation to read the values back into Python:
>>> sheet.range('A10').value = [['Foo 1', 'Foo 2', 'Foo 3'], [10, 20,
˓→30]]
>>> sheet.range((10,1),(11,3)).value
[['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.0]]
Note: Try to minimize the number of interactions with Excel. It is always more efficient to do sheet.
range('A1').value = [[1,2],[3,4]] than sheet.range('A1').value = [1, 2] and
sheet.range('A2').value = [3, 4].
You can get the dimensions of Excel Ranges dynamically through either the method expand or through the
expand keyword in the options method. While expand gives back an expanded Range object, options
are only evaluated when accessing the values of a Range. The difference is best explained with an example:
>>> sheet = xw.Book().sheets[0]
>>> sheet.range('A1').value = [[1,2], [3,4]]
>>> rng1 = sheet.range('A1').expand('table') # or just .expand()
>>> rng2 = sheet.range('A1').options(expand='table')
>>> rng1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> rng2.value
[[1.0, 2.0], [3.0, 4.0]]
>>> sheet.range('A3').value = [5, 6]
>>> rng1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> rng2.value
[[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]
'table' expands to 'down' and 'right', the other available options which can be used for column or
row only expansion, respectively.
Note: Using expand() together with a named Range as top left cell gives you a flexible setup in Excel:
You can move around the table and change its size without having to adjust your code, e.g. by using
something like sheet.range('NamedRange').expand().value.
NumPy arrays work similar to nested lists. However, empty cells are represented by nan instead of None.
If you want to read in a Range as array, set convert=np.array in the options method:
>>> import numpy as np
>>> sheet = xw.Book().sheets[0]
>>> sheet.range('A1').value = np.eye(3)
>>> sheet.range('A1').options(np.array, expand='table').value
array([[ 1., 0., 0.],
[ 0., 1., 0.],
[ 0., 0., 1.]])
Note: You only need to specify the top left cell when writing a list, a NumPy array or a Pandas DataFrame
to Excel, e.g.: sheet.range('A1').value = np.eye(10)
When you read and write from or to big ranges, you may have to chunk them or you will hit a timeout or a
memory error. The ideal chunksize will depend on your system and size of the array, so you will have to
try out a few different chunksizes to find one that works well:
import pandas as pd
import numpy as np
sheet = xw.Book().sheets[0]
data = np.arange(75_000 * 20).reshape(75_000, 20)
df = pd.DataFrame(data=data)
sheet['A1'].options(chunksize=10_000).value = df
# As DataFrame
df = sheet['A1'].expand().options(pd.DataFrame, chunksize=10_000).value
# As list of list
df = sheet['A1'].expand().options(chunksize=10_000).value
The xlwings add-in is the preferred way to be able to use the Run main button, RunPython or UDFs.
Note that you don’t need an add-in if you just want to manipulate Excel by running a Python script.
Note: The ribbon of the add-in is compatible with Excel >= 2007 on Windows and >= 2016 on Mac. On
Mac, all UDF related functionality is not available.
Note: The add-in is password protected with the password xlwings. For debugging or to add new
extensions, you need to unprotect it. Alternatively, you can also install the add-in via xlwings addin
install --unprotected.
23
xlwings - Make Excel Fly!, Release dev
7.2 Installation
Technically, this copies the add-in from Python’s installation directory to Excel’s XLSTART folder. Then,
to use RunPython or UDFs in a workbook, you need to set a reference to xlwings in the VBA editor,
see screenshot (Windows: Tools > References..., Mac: it’s on the lower left corner of the VBA
editor). Note that when you create a workbook via xlwings quickstart, the reference should already
be set.
When you install the add-in for the first time, it will get auto-configured and therefore, a quickstart
project should work out of the box. For fine-tuning, here are the available settings:
• Interpreter: This is the path to the Python interpreter. This works also with virtual or conda
envs on Mac. If you use conda envs on Windows, then leave this empty and use Conda Path
and Conda Env below instead. Examples: "C:\Python39\pythonw.exe" or "/usr/
local/bin/python3.9". Note that in the settings, this is stored as Interpreter_Win or
Interpreter_Mac, respectively, see below!
• PYTHONPATH: If the source file of your code is not found, add the path to its directory here.
• Conda Path: If you are on Windows and use Anaconda or Miniconda, then type here the path to
your installation, e.g. C:\Users\Username\Miniconda3 or %USERPROFILE%\Anaconda.
NOTE that you need at least conda 4.6! You also need to set Conda Env, see next point.
• Conda Env: If you are on Windows and use Anaconda or Miniconda, type here the name of your
conda env, e.g. base for the base installation or myenv for a conda env with the name myenv.
• UDF Modules: Names of Python modules (without .py extension) from which the UDFs are be-
ing imported. Separate multiple modules by “;”. Example: UDF_MODULES = "common_udfs;
myproject" The default imports a file in the same directory as the Excel spreadsheet with the same
name but ending in .py.
• Debug UDFs: Check this box if you want to run the xlwings COM server manually for debugging,
see Debugging.
• RunPython: Use UDF Server: Uses the same COM Server for RunPython as for UDFs. This
will be faster, as the interpreter doesn’t shut down after each call.
• Restart UDF Server: This restarts the UDF Server/Python interpreter.
• Show Console: Check the box in the ribbon or set the config to TRUE if you want the command
prompt to pop up. This currently only works on Windows.
7.3.1 Anaconda/Miniconda
If you use Anaconda or Miniconda on Windows, you will need to set your Conda Path and Conda Env
settings, as you will otherwise get errors when using NumPy etc. In return, leave Interpreter empty.
With environment variables, you can set dynamic paths e.g. to your interpreter or PYTHONPATH:
• On Windows, you can use all environment variables like so: %USERPROFILE%\Anaconda.
• On macOS, the following special variables are supported: $HOME, $APPLICATIONS,
$DOCUMENTS, $DESKTOP.
The settings in the xlwings Ribbon are stored in a config file that can also be manipulated externally. The
location is
• Windows: .xlwings\xlwings.conf in your home folder, that is usually
C:\Users\<username>
• macOS: ~/Library/Containers/com.microsoft.Excel/Data/xlwings.conf
The format is as follows (currently the keys are required to be all caps) - note the OS specific Interpreter
settings!
"INTERPRETER_WIN","C:\path\to\python.exe"
"INTERPRETER_MAC","/path/to/python"
"PYTHONPATH",""
"CONDA PATH",""
"CONDA ENV",""
"UDF MODULES",""
"DEBUG UDFS",""
"USE UDF SERVER",""
"SHOW CONSOLE",""
"ONEDRIVE_WIN",""
"ONEDRIVE_MAC",""
Note: The ONEDRIVE_WIN/_MAC setting has to be edited directly in the file, there is currently no
possibility to edit it via the ribbon. Usually, it is only required if you are either on macOS or if your
environment variables on Windows are not correctly set or if you have a private and corporate location and
don’t want to go with the default one. ONEDRIVE_WIN/_MAC has to point to the root folder of your local
OneDrive folder.
The global settings of the Ribbon/Config file can be overridden for one or more workbooks by creating a
xlwings.conf file in the workbook’s directory.
Workbook specific settings will override global (Ribbon) and workbook directory config files: Workbook
specific settings are set by listing the config key/value pairs in a sheet with the name xlwings.conf.
When you create a new project with xlwings quickstart, it’ll already have such a sheet but you need
to rename it to xlwings.conf to make it active.
Sometimes, it might be useful to run xlwings code without having to install an add-in first. To do so, you need
to use the standalone option when creating a new project: xlwings quickstart myproject
--standalone.
This will add the content of the add-in as a single VBA module so you don’t need to set a reference to
the add-in anymore. It will also include Dictionary.cls as this is required on macOS. It will still
read in the settings from your xlwings.conf if you don’t override them by using a sheet with the name
xlwings.conf.
RunPython
To get access to Run main (new in v0.16) button or the RunPython VBA function, you’ll need the
xlwings addin (or VBA module), see Add-in & Settings.
For new projects, the easiest way to get started is by using the command line client with the quickstart
command, see Command Line Client (CLI) for details:
In the VBA Editor (Alt-F11), write the code below into a VBA module. xlwings quickstart
automatically adds a new module with a sample call. If you rather want to start from scratch, you can add a
new module via Insert > Module.
Sub HelloWorld()
RunPython "import hello; hello.world()"
End Sub
# hello.py
import numpy as np
import xlwings as xw
def world():
(continues on next page)
29
xlwings - Make Excel Fly!, Release dev
You can then attach HelloWorld to a button or run it directly in the VBA Editor by hitting F5.
Note: Place xw.Book.caller() within the function that is being called from Excel and not outside as
global variable. Otherwise it prevents Excel from shutting down properly upon exiting and leaves you with
a zombie process when you use Use UDF Server = True.
While it’s technically possible to include arguments in the function call within RunPython, it’s not very
convenient. Also, RunPython does not allow you to return values. To overcome these issues, use UDFs,
see User Defined Functions (UDFs) - however, this is currently limited to Windows only.
30 Chapter 8. RunPython
CHAPTER 9
This tutorial gets you quickly started on how to write User Defined Functions.
Note:
• UDFs are currently only available on Windows.
• For details of how to control the behaviour of the arguments and return values, have a look at Con-
verters and Options.
• For a comprehensive overview of the available decorators and their options, check out the correspond-
ing API docs: UDF decorators.
1) Enable Trust access to the VBA project object model under File >
Options > Trust Center > Trust Center Settings > Macro Settings.
You only need to do this once. Also, this is only required for importing the functions, i.e. end users
won’t need to bother about this.
2) Install the add-in via command prompt: xlwings addin install (see Add-in & Settings).
The easiest way to start a new project is to run xlwings quickstart myproject on a command
prompt (see Command Line Client (CLI)). This automatically adds the xlwings reference to the generated
workbook.
31
xlwings - Make Excel Fly!, Release dev
The default addin settings expect a Python source file in the way it is created by quickstart:
• in the same directory as the Excel file
• with the same name as the Excel file, but with a .py ending instead of .xlsm.
Alternatively, you can point to a specific module via UDF Modules in the xlwings ribbon.
Let’s assume you have a Workbook myproject.xlsm, then you would write the following code in
myproject.py:
import xlwings as xw
@xw.func
def double_sum(x, y):
"""Returns twice the sum of the two arguments"""
return 2 * (x + y)
• Now click on Import Python UDFs in the xlwings tab to pick up the changes made to
myproject.py.
• Enter the formula =double_sum(1, 2) into a cell and you will see the correct result:
Note:
• You only need to re-import your functions if you change the function arguments or the function name.
• Code changes in the actual functions are picked up automatically (i.e. at the next calculation of the
formula, e.g. triggered by Ctrl-Alt-F9), but changes in imported modules are not. This is the
very behaviour of how Python imports work. If you want to make sure everything is in a fresh state,
click Restart UDF Server.
• The @xw.func decorator is only used by xlwings when the function is being imported into Excel. It
tells xlwings for which functions it should create a VBA wrapper function, otherwise it has no effect
on how the functions behave in Python.
Calling one big array formula in Excel is much more efficient than calling many single-cell formulas, so it’s
generally a good idea to use them, especially if you hit performance problems.
You can pass an Excel Range as a function argument, as opposed to a single cell and it will show up in
Python as list of lists.
For example, you can write the following function to add 1 to every cell in a Range:
@xw.func
def add_one(data):
return [[cell + 1 for cell in row] for row in data]
The above formula has the issue that it expects a “two dimensional” input, e.g. a nested list of the form [[1,
2], [3, 4]]. Therefore, if you would apply the formula to a single cell, you would get the following
error: TypeError: 'float' object is not iterable.
To force Excel to always give you a two-dimensional array, no matter whether the argument is a single cell,
a column/row or a two-dimensional Range, you can extend the above formula like this:
@xw.func
@xw.arg('data', ndim=2)
def add_one(data):
return [[cell + 1 for cell in row] for row in data]
Often, you’ll want to use NumPy arrays or Pandas DataFrames in your UDF, as this unlocks the full power
of Python’s ecosystem for scientific computing.
To define a formula for matrix multiplication using numpy arrays, you would define the following function:
import xlwings as xw
import numpy as np
@xw.func
@xw.arg('x', np.array, ndim=2)
@xw.arg('y', np.array, ndim=2)
def matrix_mult(x, y):
return x @ y
Note: If you are not on Python >= 3.5 with NumPy >= 1.10, use x.dot(y) instead of x @ y.
A great example of how you can put Pandas at work is the creation of an array-based CORREL formula.
Excel’s version of CORREL only works on 2 datasets and is cumbersome to use if you want to quickly
get the correlation matrix of a few time-series, for example. Pandas makes the creation of an array-based
CORREL2 formula basically a one-liner:
import xlwings as xw
import pandas as pd
@xw.func
@xw.arg('x', pd.DataFrame, index=False, header=False)
@xw.ret(index=False, header=False)
def CORREL2(x):
"""Like CORREL, but as array formula for more than 2 data sets"""
return x.corr()
These decorators are to UDFs what the options method is to Range objects: they allow you to apply
converters and their options to function arguments (@xw.arg) and to the return value (@xw.ret). For
example, to convert the argument x into a pandas DataFrame and suppress the index when returning it, you
would do the following:
@xw.func
@xw.arg('x', pd.DataFrame)
@xw.ret(index=False)
def myfunction(x):
# x is a DataFrame, do something with it
return x
Note: If your version of Excel supports the new native dynamic arrays, then you don’t have to do anything
special, and you shouldn’t use the expand decorator! To check if your version of Excel supports it, see if
you have the =UNIQUE() formula available. Native dynamic arrays were introduced in Office 365 Insider
Fast at the end of September 2018.
As seen above, to use Excel’s array formulas, you need to specify their dimensions up front by selecting the
result array first, then entering the formula and finally hitting Ctrl-Shift-Enter. In practice, it often
turns out to be a cumbersome process, especially when working with dynamic arrays such as time series
data. Since v0.10, xlwings offers dynamic UDF expansion:
This is a simple example that demonstrates the syntax and effect of UDF expansion:
import numpy as np
@xw.func
@xw.ret(expand='table')
def dynamic_array(r, c):
return np.random.randn(int(r), int(c))
Note:
• Expanding array formulas will overwrite cells without prompting
• Pre v0.15.0 doesn’t allow to have volatile functions as arguments, e.g. you cannot use functions like
=TODAY() as arguments. Starting with v0.15.0, you can use volatile functions as input, but the UDF
will be called more than 1x.
• Dynamic Arrays have been refactored with v0.15.0 to be proper legacy arrays: To edit a dynamic
array with xlwings >= v0.15.0, you need to hit Ctrl-Shift-Enter while in the top left cell. Note
that you don’t have to do that when you enter the formula for the first time.
9.8 Docstrings
The following sample shows how to include docstrings both for the function and for the arguments x and y
that then show up in the function wizard in Excel:
import xlwings as xw
@xw.func
@xw.arg('x', doc='This is x.')
@xw.arg('y', doc='This is y.')
def double_sum(x, y):
"""Returns twice the sum of the two arguments"""
return 2 * (x + y)
You often need to know which cell called the UDF. For this, xlwings offers the reserved argument caller
which returns the calling cell as xlwings range object:
@xw.func
def get_caller_address(caller):
# caller will not be exposed in Excel, so use it like so:
(continues on next page)
Note that caller will not be exposed in Excel but will be provided by xlwings behind the scenes.
By using the vba keyword, you can get access to any Excel VBA object in the form of a pywin32 object.
For example, if you wanted to pass the sheet object in the form of its CodeName, you can do it as follows:
@xw.func
@xw.arg('sheet1', vba='Sheet1')
def get_name(sheet1):
# call this function in Excel with:
# =get_name()
return sheet1.Name
Note that vba arguments are not exposed in the UDF but automatically provided by xlwings.
9.11 Macros
On Windows, as an alternative to calling macros via RunPython, you can also use the @xw.sub decorator:
import xlwings as xw
@xw.sub
def my_macro():
"""Writes the name of the Workbook into Range("A1") of Sheet 1"""
wb = xw.Book.caller()
wb.sheets[0].range('A1').value = wb.name
After clicking on Import Python UDFs, you can then use this macro by executing it via Alt + F8
or by binding it e.g. to a button. To do the latter, make sure you have the Developer tab selected under
File > Options > Customize Ribbon. Then, under the Developer tab, you can insert a button
via Insert > Form Controls. After drawing the button, you will be prompted to assign a macro to
it and you can select my_macro.
Imported functions can also be used from VBA. For example, for a function returning a 2d array:
Sub MySub()
arr = my_imported_function(...)
End Sub
import xlwings as xw
import time
@xw.func(async_mode='threading')
def myfunction(a):
time.sleep(5) # long running tasks
return a
You can use this function like any other xlwings function, simply by putting =myfunction("abcd")
into a cell (after you have imported the function, of course).
Note that xlwings doesn’t use the native asynchronous functions that were introduced with Excel 2010, so
xlwings asynchronous functions are supported with any version of Excel.
10.1 Matplotlib
fig = plt.figure()
plt.plot([1, 2, 3])
sheet = xw.Book().sheets[0]
sheet.pictures.add(fig, name='MyPlot', update=True)
Note: If you set update=True, you can resize and position the plot on Excel: subsequent calls to
pictures.add() with the same name ('MyPlot') will update the picture without changing its position
or size.
Calling the above code with RunPython and binding it e.g. to a button is straightforward and works cross-
platform.
39
xlwings - Make Excel Fly!, Release dev
However, on Windows you can make things feel even more integrated by setting up a UDF along the
following lines:
@xw.func
def myplot(n, caller):
fig = plt.figure()
plt.plot(range(int(n)))
caller.sheet.pictures.add(fig, name='MyPlot', update=True)
return 'Plotted with n={}'.format(n)
If you import this function and call it from cell B2, then the plot gets automatically updated when cell B1
changes:
10.1.3 Properties
Size, position and other properties can either be set as arguments within pictures.add(), or by manip-
ulating the picture object that is returned, see xlwings.Picture().
For example:
or:
10.1. Matplotlib 41
xlwings - Make Excel Fly!, Release dev
Here are a few examples of how you get a matplotlib figure object:
• via PyPlot interface:
or:
• via Pandas:
import pandas as pd
import numpy as np
10.2.1 Prerequisites
In addition to plotly, you will need kaleido, psutil, and requests. The easiest way to get it is
via pip:
or conda:
It works the same as with Matplotlib, however, rendering a Plotly chart takes slightly longer. Here is a
sample:
import xlwings as xw
import plotly.express as px
# Plotly chart
df = px.data.iris()
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")
# Add it to Excel
wb = xw.Book()
wb.sheets[0].pictures.add(fig, name='IrisScatterPlot', update=True)
When you work with Jupyter notebooks, you may use Excel as an interactive data viewer or scratchpad from
where you can load DataFrames. The two convenience functions view and load make this really easy.
Note: The view and load functions should exclusively be used for interactive work. If you write scripts,
use the xlwings API as introduced under Quickstart and Syntax Overview.
The view function accepts pretty much any object of interest, whether that’s a number, a string, a nested
list or a NumPy array or a pandas DataFrame. By default, it writes the data into an Excel table in a
new workbook. If you wanted to reuse the same workbook, provide a sheet object, e.g. view(df,
sheet=xw.sheets.active), for further options see view.
Changed in version 0.22.0: Earlier versions were not formatting the output as Excel table
To load in a range in an Excel sheet as pandas DataFrame, use the load function. If you only select one
cell, it will auto-expand to cover the whole range. If, however, you select a specific range that is bigger than
one cell, it will load in only the selected cells. If the data in Excel does not have an index or header, set them
to False like this: xw.load(index=False), see also load.
New in version 0.22.0.
45
xlwings - Make Excel Fly!, Release dev
xlwings comes with a command line client. On Windows, type the commands into a Command Prompt or
Anaconda Prompt, on Mac, type them into a Terminal. To get an overview of all commands, simply type
xlwings and hit Enter:
addin Run "xlwings addin install" to install the Excel add-
in (will be copied to the XLSTART folder). Instead of
"install" you can also use "update", "remove" or
"status". Note that this command may take a while. Use
the "--unprotected" flag to install the add-in without
password protection. You can install your custom add-
in by providing the name or path via the --file flag,
e.g. "xlwings add-in install --file custom.xlam"
(New in 0.6.0, the unprotected flag was added in 0.20.4)
quickstart Run "xlwings quickstart myproject" to create a folder
called "myproject" in the current directory with an
Excel file and a Python file, ready to be used. Use
the "--standalone" flag to embed all VBA code in the
Excel file and make it work without the xlwings add-
in.
runpython macOS only: run "xlwings runpython install" if you
want to enable the RunPython calls without installing
the add-in. This will create the following file:
~/Library/Application
Scripts/com.microsoft.Excel/xlwings.applescript
(new in 0.7.0)
restapi Use "xlwings restapi run" to run the xlwings REST API
via Flask dev server. Accepts "--host" and "--port" as
optional arguments.
license xlwings PRO: Use "xlwings license update -k KEY" where
"KEY" is your personal (trial) license key. This will
update ~/.xlwings/xlwings.conf with the LICENSE_KEY
(continues on next page)
47
xlwings - Make Excel Fly!, Release dev
Deployment
PYTHONPATH, "C:\path\to\myproject.zip"
13.2 RunFrozenPython
Note:
• This does not work with UDFs.
• Currently only available on Windows, but support for Mac should be easy to add.
49
xlwings - Make Excel Fly!, Release dev
• You need at least 0.15.2 to support arguments whereas the syntax changed in 0.15.6
Use it as follows:
Sub MySample()
RunFrozenPython "C:\path\to\dist\myproject\myproject.exe", "arg1 arg2"
End Sub
Troubleshooting
Solution:
1) xlwings32-<version>.dll and xlwings64-<version>.dll are both in the same direc-
tory as your python.exe. If not, something went wrong with your installation. Reinstall it with
pip or conda, see Installation.
2) Check your Interpreter in the add-in or config sheet. If it is empty, then you need to be
able to open a windows command prompt and type python to start an interactive Python session.
If you get the error 'python' is not recognized as an internal or external
command, operable program or batch file., then you have two options: Either add
the path of where your python.exe lives to your Windows path (see https://www.computerhope.
com/issues/ch000549.htm) or set the full path to your interpreter in the add-in or your config sheet,
e.g. C:\Users\MyUser\anaconda\pythonw.exe
Solution:
On either the xlwings.conf sheet or on the xlwings.conf file under your home folder (for location
see User Config: Ribbon/Config File), add the following setting:
"ONEDRIVE_WIN", "C:\path\to\OneDrive"
Note: Don’t use quotes on the xlwings.conf sheet and if you are on macOS, use ONEDRIVE_MAC
instead. You need to use the ONEDRIVE setting, even if you use SharePoint.
51
xlwings - Make Excel Fly!, Release dev
Introduced with v0.7.0, converters define how Excel ranges and their values are converted both during
reading and writing operations. They also provide a consistent experience across xlwings.Range objects
and User Defined Functions (UDFs).
Converters are explicitly set in the options method when manipulating Range objects or in the @xw.arg
and @xw.ret decorators when using UDFs. If no converter is specified, the default converter is applied
when reading. When writing, xlwings will automatically apply the correct converter (if available) according
to the object’s type that is being written to Excel. If no converter is found for that type, it falls back to the
default converter.
All code samples below depend on the following import:
Syntax:
xw.Range UDFs
read- xw.Range.options(convert=None, @arg('x',
ing **kwargs).value convert=None,
**kwargs)
writ- xw.Range.options(convert=None, @ret(convert=None,
ing **kwargs).value = myvalue **kwargs)
Note: Keyword arguments (kwargs) may refer to the specific converter or the default converter. For
example, to set the numbers option in the default converter and the index option in the DataFrame
converter, you would write:
53
xlwings - Make Excel Fly!, Release dev
• numbers
By default cells with numbers are read as float, but you can change it to int:
>>> sht.range('A1').value = 1
>>> sht.range('A1').value
1.0
>>> sht.range('A1').options(numbers=int).value
1
Alternatively, you can specify any other function or type which takes a single float argument.
Using this on UDFs looks like this:
@xw.func
@xw.arg('x', numbers=int)
def myfunction(x):
(continues on next page)
Note: Excel always stores numbers internally as floats, which is the reason why the int converter
rounds numbers first before turning them into integers. Otherwise it could happen that e.g. 5 might be
returned as 4 in case it is represented as a floating point number that is slightly smaller than 5. Should
you require Python’s original int in your converter, use raw int instead.
• dates
By default cells with dates are read as datetime.datetime, but you can change it to datetime.
date:
– Range:
• empty
Empty cells are converted per default into None, you can change this as follows:
– Range: >>> sht.range('A1').options(empty='NA').value
– UDFs: @xw.arg('x', empty='NA')
• transpose
This works for reading and writing and allows us to e.g. write a list in column orientation to Excel:
– Range: sht.range('A1').options(transpose=True).value = [1, 2, 3]
– UDFs:
@xw.arg('x', transpose=True)
@xw.ret(transpose=True)
def myfunction(x):
# x will be returned unchanged as transposed both when reading
˓→and writing
return x
• expand
This works the same as the Range properties table, vertical and horizontal but is only
evaluated when getting the values of a Range:
Note: The expand method is only available on Range objects as UDFs only allow to manipulate
the calling cells.
• chunksize
When you read and write from or to big ranges, you may have to chunk them or you will hit a timeout
or a memory error. The ideal chunksize will depend on your system and size of the array, so you
will have to try out a few different chunksizes to find one that works well:
import pandas as pd
import numpy as np
sheet = xw.Book().sheets[0]
data = np.arange(75_000 * 20).reshape(75_000, 20)
df = pd.DataFrame(data=data)
sheet['A1'].options(chunksize=10_000).value = df
xlwings offers several built-in converters that perform type conversion to dictionaries, NumPy arrays,
Pandas Series and DataFrames. These build on top of the default converter, so in most cases the options
described above can be used in this context, too (unless they are meaningless, for example the ndim in the
case of a dictionary).
It is also possible to write and register a custom converter for additional types, see below.
The samples below can be used with both xlwings.Range objects and UDFs even though only one
version may be shown.
The dictionary converter turns two Excel columns into a dictionary. If the data is in row orientation, use
transpose:
Note: instead of dict, you can also use OrderedDict from collections.
The same sample for UDF (starting in Range('A13') on screenshot) looks like this:
@xw.func
@xw.arg('x', pd.DataFrame, header=2)
@xw.ret(index=False)
def myfunction(x):
# x is a DataFrame, do something with it
return x
@xw.func
@xw.arg('x', 'range')
def myfunction(x):
return x.formula
This returns x as xlwings.Range object, i.e. without applying any converters or options.
• The raw converter delivers the values unchanged from the underlying libraries (pywin32 on Win-
dows and appscript on Mac), i.e. no sanitizing/cross-platform harmonizing of values are being
made. This might be useful in a few cases for efficiency reasons. E.g:
>>> sht.range('A1:B2').value
[[1.0, 'text'], [datetime.datetime(2016, 2, 1, 0, 0), None]]
– In write_value, value is the original object being written to Excel. It must be returned
in the format that the base converter expects. Again, if no base has been specified, this is the
default converter.
The options dictionary will contain all keyword arguments specified in the xw.Range.options
method, e.g. when calling xw.Range('A1').options(myoption='some value') or as
specified in the @arg and @ret decorator when using UDFs. Here is the basic structure:
from xlwings.conversion import Converter
class MyConverter(Converter):
@staticmethod
def read_value(value, options):
myoption = options.get('myoption', default_value)
return_value = value # Implement your conversion here
return return_value
@staticmethod
def write_value(value, options):
myoption = options.get('myoption', default_value)
return_value = value # Implement your conversion here
return return_value
• Optional: set a base converter (base expects a class name) to build on top of an ex-
isting converter, e.g. for the built-in ones: DictCoverter, NumpyArrayConverter,
PandasDataFrameConverter, PandasSeriesConverter
• Optional: register the converter: you can (a) register a type so that your converter becomes the default
for this type during write operations and/or (b) you can register an alias that will allow you to explicitly
call your converter by name instead of just by class name
The following examples should make it much easier to follow - it defines a DataFrame converter that extends
the built-in DataFrame converter to add support for dropping nan’s:
from xlwings.conversion import Converter, PandasDataFrameConverter
class DataFrameDropna(Converter):
base = PandasDataFrameConverter
@staticmethod
def read_value(builtin_df, options):
dropna = options.get('dropna', False) # set default to False
if dropna:
converted_df = builtin_df.dropna()
else:
converted_df = builtin_df
# This will arrive in Python when using the DataFrameDropna converter
˓→for reading
return converted_df
@staticmethod
(continues on next page)
# Write
sht.range('A1').value = df
# Read
sht.range('A1:C4').options(pd.DataFrame).value
• DataFrameDropna converter:
# Write
sht.range('A7').options(DataFrameDropna, dropna=True).value = df
# Read
sht.range('A1:C4').options(DataFrameDropna, dropna=True).value
DataFrameDropna.register('df_dropna')
# Write
sht.range('A12').options('df_dropna', dropna=True).value = df
# Read
sht.range('A1:C4').options('df_dropna', dropna=True).value
DataFrameDropna.register(pd.DataFrame)
# Write
sht.range('A13').options(dropna=True).value = df
# Read
sht.range('A1:C4').options(pd.DataFrame, dropna=True).value
@xw.func
@arg('x', DataFrameDropna, dropna=True)
@ret(DataFrameDropna, dropna=True)
def myfunction(x):
# ...
return x
Note: Python objects run through multiple stages of a transformation pipeline when they are being written
to Excel. The same holds true in the other direction, when Excel/COM objects are being read into Python.
Pipelines are internally defined by Accessor classes. A Converter is just a special Accessor which converts
to/from a particular type by adding an extra stage to the pipeline of the default Accessor. For example, the
PandasDataFrameConverter defines how a list of lists (as delivered by the default Accessor) should
be turned into a Pandas DataFrame.
The Converter class provides basic scaffolding to make the task of writing a new Converter easier. If you
need more control you can subclass Accessor directly, but this part requires more work and is currently
undocumented.
Debugging
Since xlwings runs in every Python environment, you can use your preferred way of debugging.
• RunPython: When calling Python through RunPython, you can set a mock_caller to make it
easy to switch back and forth between calling the function from Excel and Python.
• UDFs: For debugging User Defined Functions, xlwings offers a convenient debugging server
To begin with, Excel will show Python errors in a Message Box:
Note: On Mac, if the import of a module/package fails before xlwings is imported, the popup will
65
xlwings - Make Excel Fly!, Release dev
not be shown and the StatusBar will not be reset. However, the error will still be logged in the log file
(/Users/<User>/Library/Containers/com.microsoft.Excel/Data/xlwings.log).
16.1 RunPython
Consider the following sample code of your Python source code my_module.py:
# my_module.py
import os
import xlwings as xw
def my_macro():
wb = xw.Book.caller()
wb.sheets[0].range('A1').value = 1
if __name__ == '__main__':
# Expects the Excel file next to this source file, adjust accordingly.
xw.Book('myfile.xlsm').set_mock_caller()
my_macro()
my_macro() can now easily be run from Python for debugging and from Excel via RunPython without
having to change the source code:
Sub my_macro()
RunPython "import my_module; my_module.my_macro()"
End Sub
Windows only: To debug UDFs, just check the Debug UDFs in the Add-in & Settings, at the top of
the xlwings VBA module. Then add the following lines at the end of your Python source file and run it.
Depending on which IDE you use, you might need to run the code in “debug” mode (e.g. in case you’re
using PyCharm or PyDev):
if __name__ == '__main__':
xw.serve()
When you recalculate the Sheet (Ctrl-Alt-F9), the code will stop at breakpoints or output any print calls
that you may have.
The following screenshot shows the code stopped at a breakpoint in the community version of PyCharm:
Note: When running the debug server from a command prompt, there is currently no gracious way to
terminate it, but closing the command prompt will kill it.
Extensions
It’s easy to extend the xlwings add-in with own code like UDFs or RunPython macros, so that they can
be deployed without end users having to import or write the functions themselves. Just add another VBA
module to the xlwings addin with the respective code.
UDF extensions can be used from every workbook without having to set a reference.
The xlwings addin comes with a built-in extension that adds in-Excel SQL syntax (sqlite dialect):
As this extension uses UDFs, it’s only available on Windows right now.
69
xlwings - Make Excel Fly!, Release dev
Custom Add-ins
18.1 Quickstart
Start by running the following command on a command line (to create an add-in without a ribbon, you
would leave away the --ribbon flag):
This will create the familiar quickstart folder with a Python file and an Excel file, but this time, the Excel
file is in the xlam format.
• Double-click the Excel add-in to open it in Excel
• Add a new empty workbook (Ctrl+N on Windows or Command+N on macOS)
You should see a new ribbon tab called MyAddin like this:
The add-in and VBA project are currently always called myaddin, no matter what name you chose in the
quickstart command. We’ll see towards the end of this tutorial how we can change that, but for now we’ll
stick with it.
71
xlwings - Make Excel Fly!, Release dev
Compared to the xlwings add-in, the custom add-in offers an additional level of configuration: the configura-
tion sheet of the add-in itself which is the easiest way to configure simple add-ins with a static configuration.
Let’s open the VBA editor by clicking on Alt+F11 (Windows) or Option+F11 (macOS). In our project,
select ThisWorkbook, then change the Property IsAddin from True to False, see the following
screenshot:
This will make the sheet _myaddin.conf visible (again, we’ll see how to change the name of myaddin
at the end of this tutorial):
• Activate the sheet config by renaming it from _myaddin.conf to myaddin.conf
• Set your Interpreter_Win/_Mac or Conda settings (you may want to take them over from the
xlwings settings for now)
Once done, switch back to the VBA editor, select ThisWorkbook again, and change IsAddin back to
True before you save your add-in from the VBA editor. Switch back to Excel and click the Run button
under the My Addin ribbon tab and if you’ve configured the Python interpreter correctly, it will print
Hello xlwings! into cell A1 of the active workbook.
To change the buttons and items in the ribbon menu or the Backstage View, download and install the Office
RibbonX Editor. While it is only available for Windows, the created ribbons will also work on macOS. Open
your add-in with it so you can change the XML code that defines your buttons etc. You will find a good
tutorial here. The callback function for the demo Run button is in the RibbonMyAddin VBA module that
you’ll find in the VBA editor.
To import your UDFs into the custom add-in, run the ImportPythonUDFsToAddin Sub towards the
end of the xlwings module (click into the Sub and hit F5). Remember, you only have to do this whenever
you change the function name, argument or decorator, so your end users won’t have to deal with this.
If you are only deploying UDFs via your add-in, you probably don’t need a Ribbon menu and can leave
away the --ribbon flag in the quickstart command.
18.4 Configuration
As mentioned before, configuration works the same as with xlwings, so you could have your users override
the default configuration we did above by adding a myaddin.conf sheet on their workbook or you could
use the myaddin.conf file in the user’s home directory. For details see Add-in & Settings.
18.5 Installation
If you want to permanently install your add-in, you can do so by using the xlwings CLI:
This, however, means that you will need to adjust the PYTHONPATH for it to find your Python code (or move
your Python code to somewhere where Python looks for it—more about that below under deployment). The
command will copy your add-in to the XLSTART folder, a special folder from where Excel will open all
files everytime you start it.
Admittedly, this part is a bit cumbersome for now. Let’s assume, we would like to rename the addin from
MyAddin to Demo:
• In the xlwings VBA module, change Public Const PROJECT_NAME As String =
"myaddin" to Public Const PROJECT_NAME As String = "demo". You’ll find this
line at the top, right after the Declare statements.
• If you rely on the myaddin.conf sheet for your configuration, rename it to demo.conf
• Right-click the VBA project, select MyAddin Properties... and rename the Project Name
from MyAddin to Demo.
• If you use the ribbon, you want to rename the RibbonMyAddin VBA module to RibbonDemo.
To do this, select the module in the VBA editor, then rename it in the Properties window. If you
don’t see the Properties window, hit F4.
• Open the add-in in the Office RibbonX Editor (see above) and replace all occurrences of MyAddin
with Demo in the XML code.
And finally, you may want to rename your myproject.xlam file in the Windows explorer, but I assume
you have already run the quickstart command with the correct name, so this won’t be necessary.
18.7 Deployment
By far the easiest way to deploy your add-in to your end-users is to build an installer via the xlwings PRO
offering. This will take care of everything and your end users literally just need to double-click the installer
and they are all set (no existing Python installation required and no manual installation of the add-in or
adjusting of settings required).
If you want it the free (but hard) way, you either need to build an installer yourself or you need your users to
install Python and the add-in and take care of placing the Python code in the correct directory. This normally
involves tweaking the following settings, for example in the myaddin.conf sheet:
• Interpreter_Win/_Mac: if your end-users have a working version of Python, you can use en-
vironment variables to dynamically resolve to the correct path. For example, if they have Anaconda
installed in the default location, you could use the following configuration:
• PYTHONPATH: since you can’t have your Python source code in the XLSTART folder next to the
add-in, you’ll need to adjust the PYTHONPATH setting and add the folder to where the Python code
will be. You could point this to a shared drive or again make use of environment variables so the
users can place the file into a folder called MyAddin in their home directory, for example. However,
you can also place your Python code where Python looks for it, for example by placing them in the
site-packages directory of the Python distribution—an easy way to achieve this is to build a
Python package that you can install via pip.
18.7. Deployment 75
xlwings - Make Excel Fly!, Release dev
19.1 Threading
While xlwings is not technically thread safe, it’s still easy to use it in threads as long as you have at least
v0.13.0 and stick to a simple rule: Do not pass xlwings objects to threads. This rule isn’t a requirement on
macOS, but it’s still recommended if you want your programs to be cross-platform.
Consider the following example that will NOT work:
import threading
from queue import Queue
import xlwings as xw
num_threads = 4
def write_to_workbook():
while True:
rng = q.get()
rng.value = rng.address
print(rng.address)
q.task_done()
q = Queue()
for i in range(num_threads):
t = threading.Thread(target=write_to_workbook)
(continues on next page)
77
xlwings - Make Excel Fly!, Release dev
for cell in ['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']:
# THIS DOESN'T WORK - passing xlwings objects to threads will fail!
rng = xw.Book('Book1.xlsx').sheets[0].range(cell)
q.put(rng)
q.join()
To make it work, you simply have to fully qualify the cell reference in the thread instead of passing a Book
object:
import threading
from queue import Queue
import xlwings as xw
num_threads = 4
def write_to_workbook():
while True:
cell_ = q.get()
xw.Book('Book1.xlsx').sheets[0].range(cell_).value = cell_
print(cell_)
q.task_done()
q = Queue()
for i in range(num_threads):
t = threading.Thread(target=write_to_workbook)
t.daemon = True
t.start()
for cell in ['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']:
q.put(cell)
q.join()
19.2 Multiprocessing
The same rules apply to multiprocessing as for threading, here’s a working example:
def write_to_workbook(cell):
xw.Book('Book1.xlsx').sheets[0].range(cell).value = cell
print(cell)
if __name__ == '__main__':
with Pool(4) as p:
p.map(write_to_workbook,
['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10'])
19.2. Multiprocessing 79
xlwings - Make Excel Fly!, Release dev
Missing Features
This works accordingly for the other objects like sheet.range('A1').api etc.
The underlying objects will offer you pretty much everything you can do with VBA, using the syntax
of pywin32 (which pretty much feels like VBA) and appscript (which doesn’t feel like VBA). But
apart from looking ugly, keep in mind that it makes your code platform specific (!), i.e. even if you
go for option 2), you should still follow option 1) and open an issue so the feature finds it’s way into
the library (cross-platform and with a Pythonic syntax).
# Windows
sheet.range('A1').api.WrapText = True
# Mac
sheet.range('A1').api.wrap_text.set(True)
81
xlwings - Make Excel Fly!, Release dev
xlwings can also be used to call Python functions from VBA within Office apps other than Excel (like
Outlook, Access etc.).
Note: New in v0.12.0 and still in a somewhat early stage that involves a bit of manual work. Currently,
this functionality is only available on Windows for UDFs. The RunPython functionality is currently not
supported.
21.1 How To
1) As usual, write your Python function and import it into Excel (see User Defined Functions (UDFs)).
2) Press Alt-F11 to get into the VBA editor, then right-click on the xlwings_udfs VBA module
and select Export File.... Save the xlwings_udfs.bas file somewhere.
3) Switch into the other Office app, e.g. Microsoft Access and click again Alt-F11 to get into the
VBA editor. Right-click on the VBA Project and Import File..., then select the file that you
exported in the previous step. Once imported, replace the app name in the first line to the one that
you are using, i.e. Microsoft Access or Microsoft Outlook etc. so that the first line then
reads: #Const App = "Microsoft Access"
4) Now import the standalone xlwings VBA module (xlwings.bas). You can find it in your xlwings
installation folder. To know where that is, do:
83
xlwings - Make Excel Fly!, Release dev
And finally do the same as in the previous step and replace the App name in the first line with the
name of the corresponding app that you are using. You are now able to call the Python function from
VBA.
21.2 Config
The other Office apps will use the same global config file as you are editing via the Excel ribbon add-
in. When it makes sense, you’ll be able to use the directory config file (e.g. you can put it next to your
Access or Word file) or you can hardcode the path to the config file in the VBA standalone module, e.g. in
the function GetDirectoryConfigFilePath (e.g. suggested when using Outlook that doesn’t really
have the same concept of files like the other Office apps). NOTE: For Office apps without file concept, you
need to make sure that the PYTHONPATH points to the directory with the Python source file. For details on
the different config options, see Config.
The purpose of xlwings PRO is to finance the continued maintenance and enhancement of xlwings. This
will allow you to rely on the package without being left with the dreaded “this library currently has no active
maintainers” message that happens to too many open-source packages after a couple of years.
xlwings PRO offers access to additional functionality. All PRO features are marked with xlwings PRO in
the docs.
Note: To get access to the additional functionality of xlwings PRO, you need a (trial) license key and at
least xlwings v0.19.0. Everything under the xlwings.pro subpackage is distributed under a commercial
license. To make use of xlwings PRO functionality beyond the trial, you will need to subscribe to one of our
paid plans.
• One-click Installer: Easily build your own Python installer including all dependencies—your end
users don’t need to know anything about Python.
• Embedded code: Store your Python source code directly in Excel for easy deployment.
• xlwings Reports: A template-based reporting mechanism, allowing business users to change the layout
of the report without having to touch the Python code.
• Markdown Formatting: Support for Markdown formatting of text in cells and shapes like e.g., text
boxes.
• Permissioning of Code Execution: Control which users can run which Python modules via xlwings.
• Table.update(): An easy way to keep an Excel table in sync with a pandas DataFrame
85
xlwings - Make Excel Fly!, Release dev
• Pricing: https://www.xlwings.org/pricing
• Trial license key: https://www.xlwings.org/trial
xlwings Reports
87
xlwings - Make Excel Fly!, Release dev
23.1 Quickstart
You can work on the workbook or the sheet level. Let’s start with rendering full workbooks!
If your template is a workbook, you can use the create_report function. Start by creating the following
Python script mytemplate.py:
Run the Python script (or run the code from a Jupyter notebook):
python mytemplate.py
This will copy the template and create the following output by replacing the variables in double curly braces
with the value from the Python variable:
In production, you’ll often want to run this in a separate and hidden Excel instance as well as use fully
qualified Path objects. It’s also often easier to collect the data into a data dictionary:
import pandas as pd
import xlwings as xw
base_dir = Path(r'C:\Users\myuser\myreport')
data = dict(
title='MyTitle',
df=pd.DataFrame(data={'one': [1, 2], 'two': [3, 4]})
)
(continues on next page)
Note: By default, xlwings Reports overwrites existing values in templates if there is not enough free space
for your variable. If you want your rows to dynamically shift according to the height of your array, use
Frames.
Note: By default, DataFrames don’t write out the index. If you need the index to appear in Excel, use
df.reset_index(), see DataFrames.
Sometimes, it’s useful to render a single sheet instead of using the create_report function. This is a
workbook stored as Book1.xlsx:
Running the following code:
23.1. Quickstart 89
xlwings - Make Excel Fly!, Release dev
import xlwings as xw
book = xw.Book('Book1.xlsx')
sheet = book.sheets['template'].copy(name='report')
sheet.render_template(title='A Demo!', table=[[1, 2], [3, 4]])
book.to_pdf()
23.2 DataFrames
To write DataFrames in a consistent manner to Excel, xlwings Reports ignores the DataFrame indices. If you
need to pass the index over to Excel, reset the index before passing in the DataFrame to create_report
or render_template: df.reset_index().
When working with pandas DataFrames, the report designer often needs to tweak the data. Thanks to
filters, they can do the most common operations directly in the template without the need to write Python
code. A filter is added to the placeholder in Excel by using the pipe character: {{ myplaceholder |
myfilter }}. You can combine multiple filters by using multiple pipe characters: they are applied from
left to right, i.e. the result from the first filter will be the input for the next filter. Let’s start with an example
before listing each filter with its details:
import xlwings as xw
import pandas as pd
book = xw.Book('Book1.xlsx')
sheet = book.sheets['template'].copy(name='report')
df = pd.DataFrame({'one': [1, 2, 3], 'two': [4, 5, 6], 'three': [7, 8, 9]})
sheet.render_template(df=df)
{{ df | noheader }}
23.2. DataFrames 91
xlwings - Make Excel Fly!, Release dev
{{ df | header }}
{{ df | sortasc(1, 0) }}
{{ df | sortdesc(0, 1) }}
• columns: Select/reorder columns and insert empty columns (indices are zero-based)
See also: colslice
Example: introduce an empty column (None) as the second column and switch the order of the second
and third column:
{{ df | columns(0, None, 2, 1) }}
Note: Merged cells: you’ll also have to introduce empty columns if you are using merged cells in
your Excel template.
• mul, div, sum, sub: Apply an arithmetic operation (multiply, divide, sum, subtract) on a column
(indices are zero-based)
Syntax:
fill_value is optional and determines whether empty cells are included in the operation or not.
To include empty values and thus make it behave like in Excel, set it to 0.
Example: multiply the first column by 100:
{{ df | mul(100, 0) }}
Example: multiply the first column by 100 and the second column by 2:
{{ df | mul(100, 0) | mul(2, 1) }}
{{ df | add(100, 0, 0) }}
• maxrows: Maximum number of rows (currently, only sum is supported as aggregation function)
If your DataFrame has 12 rows and you use maxrows(10, "Other") as filter, you’ll get a table
that shows the first 9 rows as-is and sums up the remaining 3 rows under the label Other. If your
data is unsorted, make sure to call sortasc/sortdesc first to make sure the correct rows are
aggregated.
See also: aggsmall, head, tail, rowslice
Syntax:
label_col_ix is optional: if left away, it will label the first column of the DataFrame (index is
zero-based)
Examples:
{{ df | maxrows(10, "Other") }}
{{ df | sortasc(1)| maxrows(5, "Other") }}
{{ df | maxrows(10, "Other", 1) }}
• aggsmall: Aggregate rows with values below a certain threshold (currently, only sum is supported as
aggregation function)
If the values in the specified row are below the threshold values, they will be summed up in a single
row.
See also: maxrows, head, tail, rowslice
Syntax:
label_col_ix is optional: if left away, it will label the first column of the DataFrame (indices are
zero-based)
Examples:
{{ df | aggsmall(0.1, 2, "Other") }}
{{ df | sortasc(1) | aggsmall(0.1, 2, "Other") }}
{{ df | aggsmall(0.5, 1, "Other", 1) }}
{{ df | head(3) }}
{{ df | tail(5) }}
23.2. DataFrames 93
xlwings - Make Excel Fly!, Release dev
{{ df | rowslice(start_index, stop_index) }}
stop_index is optional: if left away, it will stop at the end of the DataFrame
Example: Show rows 2 to 4 (indices are zero-based and interval is half-open, i.e. the start is including
and the end is excluding):
{{ df | rowslice(2, 5) }}
{{ df | rowslice(2) }}
{{ df | colslice(start_index, stop_index) }}
stop_index is optional: if left away, it will stop at the end of the DataFrame
Example: Show columns 2 to 4 (indices are zero-based and interval is half-open, i.e. the start is
including and the end is excluding):
{{ df | colslice(2, 5) }}
{{ df | colslice(2) }}
Using Excel tables is the recommended way to format tables as the styling can be applied dynamically across
columns and rows. You can also use themes and apply alternating colors to rows/columns. Go to Insert
> Table and make sure that you activate My table has headers before clicking on OK. Add the
placeholder as usual on the top-left of your Excel table (note that this example makes use of Frames):
Running the following script:
nrows, ncols = 3, 3
(continues on next page)
Note:
• At the moment, you can only assign pandas DataFrames to tables
2. If your data source is dynamic, turn it into an Excel Table (Insert > Table). Make sure you do
this before adding the chart in the next step.
4. Reduce the Excel table to a 2 x 2 range and add the placeholder in the top-left corner (in our example
{{ chart_data }}) . You can leave in some dummy data or clear the values of the Excel table:
5. Assuming your file is called mytemplate.xlsx and your sheet template like on the previous
screenshot, you can run the following code:
import xlwings as xw
import pandas as pd
book = xw.Book("mytemplate.xlsx")
sheet = book.sheets['template'].copy(name='report')
sheet.render_template(chart_data=df.reset_index())
This will produce the following report, with the chart source correctly adjusted:
Note: If you don’t want the source data on your report, you can place it on a separate sheet. It’s easiest
if you add and design the chart on the separate sheet, before cutting the chart and pasting it on your report
template. To prevent the data sheet from being printed when calling to_pdf, you can give it a name that
starts with # and it will be ignored.
23.5 Images
Images are inserted so that the cell with the placeholder will become the top-left corner of the image. For
example, write the following placeholder into you desired cell: {{ logo }}, then run the following code:
import xlwings as xw
from xlwings.pro.reports import Image
book = xw.Book('Book1.xlsx')
sheet = book.sheets['template'].copy(name='report')
sheet.render_template(logo=Image(r'C:\path\to\logo.png'))
If you want to use vector-based graphics, you can use svg on Windows and pdf on macOS. You can control
the appearance of your image by applying filters on your placeholder.
Available filters for Images:
• width: Set the width in pixels (height will be scaled proportionally).
Example:
{{ logo | width(200) }}
{{ logo | height(200) }}
• width and height: Setting both width and height will distort the proportions of the image!
Example:
• scale: Scale your image using a factor (height and width will be scaled proportionally).
Example:
{{ logo | scale(1.2) }}
• top: Top margin. Has the effect of moving the image down (positive pixel number) or up (negative
pixel number), relative to the top border of the cell. This is very handy to fine-tune the position of
graphics object.
See also: left
Example:
{{ logo | top(5) }}
• left: Left margin. Has the effect of moving the image right (positive pixel number) or left (negative
pixel number), relative to the left border of the cell. This is very handy to fine-tune the position of
graphics object.
See also: top
Example:
{{ logo | left(5) }}
For a general introduction on how to handle Matplotlib and Plotly, see also: Matplotlib & Plotly Charts.
There, you’ll also find the prerequisites to be able to export Plotly charts as pictures.
23.6.1 Matplotlib
Write the following placeholder in the cell where you want to paste the Matplotlib plot: {{ lineplot
}}. Then run the following code to get your Matplotlib Figure object:
fig = plt.figure()
plt.plot([1, 2, 3])
book = xw.Book('Book1.xlsx')
sheet = book.sheets['template'].copy(name='report')
sheet.render_template(lineplot=fig)
23.6.2 Plotly
import plotly.express as px
import xlwings as xw
To change the appearance of the Matplotlib or Plotly plot, you can use the same filters as with images.
Additionally, you can use the following filter:
• format: allows to change the default image format from png to e.g., vector, which will export the
plot as vector graphics (svg on Windows and pdf on macOS). As an example, to make the chart
smaller and use the vector format, you would write the following placeholder:
23.7 Text
You can work with placeholders in text that lives in cells or shapes like text boxes. If you have more than
just a few words, text boxes usually make more sense as they won’t impact the row height no matter how
you style them. Using the same gird formatting across worksheets is key to getting a consistent multi-page
report.
While this works for simple text, you will lose the formatting if you have any. To prevent that, use a
Markdown object, as explained in the next section.
If you will be printing on a PDF Layout with a dark background, you may need to change the font color to
white. This has the nasty side effect that you won’t see anything on the screen anymore. To solve that issue,
use the fontcolor filter:
• fontcolor: Change the color of the whole (!) cell or shape. The primary purpose of this filter is to
make white fonts visible in Excel. For most other colors, you can just change the color in Excel itself.
Note that this filter changes the font of the whole cell or shape and only has an effect if there is just a
single placeholder—if you need to manipulate single words, use Markdown instead, see below. Black
and white can be used as word, otherwise use a hex notation of your desired color.
Example:
{{ mytitle | fontcolor("white") }}
{{ mytitle | fontcolor("#efefef") }}
import xlwings as xw
from xlwings.pro import Markdown
mytext = """\
# Title
* A first bullet
* A second bullet
# {{ second_title }}
This will render this template with the placeholder in a cell and a shape:
Like this (this uses the default formatting):
For more details about Markdown, especially about how to change the styling, see Markdown Formatting.
If a placeholder corresponds to a Python datetime object, by default, Excel will format that cell as a
date-formatted cell. This isn’t always desired as the formatting depends on the user’s regional settings. To
prevent that, format the cell in the Text format or use a TextBox and use the datetime filter to format
the date in the desired format. The datetime filter accepts the strftime syntax—for a good reference, see
e.g., strftime.org.
To control the language of month and weekday names, you’ll need to set the locale in your Python code.
For example, for German, you would use the following:
import locale
locale.setlocale(locale.LC_ALL, 'de_DE')
{{ mydate | datetime }}
Example: To apply a specific formatting, provide the desired format as filter argument. For example, to get
it in the 12/31/20 format:
{{ mydate | datetime("%m/%d/%y") }}
The format filter allows you to format numbers by using the same mechanism as offered by Python’s
f-strings. For example, to format the placeholder performance=0.13 as 13.0%, you would do the
following:
{{ performance | format(".1%") }}
Frames are vertical containers in which content is being aligned according to their height. That is, within
Frames:
• Variables do not overwrite existing cell values as they do without Frames.
• Formatting is applied dynamically, depending on the number of rows your object uses in Excel
To use Frames, insert a Note with the text <frame> into row 1 of your Excel template wherever you want
a new dynamic column to start. Frames go from one <frame> to the next <frame> or the right border of
the used range.
How Frames behave is best demonstrated with an example: The following screenshot defines two frames.
The first one goes from column A to column E and the second one goes from column F to column I, since
this is the last column that is used.
create_report('my_template.xlsx',
'my_report.xlsx',
**data)
Using the layout parameter in the to_pdf() command, you can “print” your Excel workbook on pro-
fessionally designed PDFs for pixel-perfect reports in your corporate layout including headers, footers,
backgrounds and borderless graphics:
from xlwings.pro.reports import create_report
import pandas as pd
(continues on next page)
book = create_report('template.xlsx',
'report.xlsx',
month_year = 'May 21',
summary_text = '...')
book.to_pdf('report.pdf', layout='monthly_layout.pdf')
Note that the layout PDF either needs to consist of a single page (will be used for each reporting page) or will
need to have the same number of pages as the report (each report page will be printed on the corresponding
layout page).
To create your layout PDF, you can use any program capable of exporting a file in PDF format such as
PowerPoint or Word, but for the best results consider using a professional desktop publishing software such
as Adobe InDesign.
Markdown Formatting
mytext = """\
# Title
* A first bullet
* A second bullet
# Another Title
(continues on next page)
111
xlwings - Make Excel Fly!, Release dev
sheet = xw.Book("Book1.xlsx").sheets[0]
# Range
sheet['A1'].clear()
sheet['A1'].value = Markdown(mytext)
Running this code will give you this nicely formatted text:
But why not make things a tad more stylish? By providing a MarkdownStyle object, you can define your
style. Let’s change the previous example like this:
mytext = """\
# Title
* A first bullet
* A second bullet
# Another Title
sheet = xw.Book("Book1.xlsx").sheets[0]
# Styling
style = MarkdownStyle()
style.h1.font.color = (255, 0, 0)
style.h1.font.size = 14
style.h1.font.name = 'Comic Sans MS' # No, that's not a font recommendation..
˓→.
style.h1.blank_lines_after = 0
style.unordered_list.bullet_character = '\N{heavy black heart}' # Emojis are
˓→fun!
# Range
sheet['A1'].clear()
sheet['A1'].value = Markdown(mytext, style) # <= provide your style object
˓→here
You can override all properties, i.e., you can change the emphasis from italic to a red font or anything else
you want:
Markdown objects can also be used with template-based reporting, see xlwings Reports.
Note: macOS currently doesn’t support the formatting (bold, italic, color etc.) of Markdown text due to a
113
xlwings - Make Excel Fly!, Release dev
bug with AppleScript/Excel. The text will be rendered correctly though, including bullet points.
115
xlwings - Make Excel Fly!, Release dev
As a subscriber of one of our paid plans, you will get access to a private GitHub repository, where you can
build your one-click installer:
1) Update your requirements.txt file with your dependencies: in your repository, start by clicking
on the requirements.txt file. This will open the following screen where you can click on the
pencil icon to edit the file (if you know your way around Git, you can also clone the repository and
use your local commit/push workflow instead):
After you’re done with your edits, click on the green Commit changes button.
Note: If you are unsure about your dependencies, it’s best to work locally with a virtual or
Conda environment. In the virtual/Conda environment, only install packages that you need,
then run: pip list --format=freeze.
On the next screen, click on Draft a new release (note, the very first time, you will see
a green button called Create a new release instead):
This will bring up the following screen, where you’ll only have to fill in a Tag version (e.g.,
1.0.0), then click on the green button Publish release:
After 3-5 minutes (you can follow the progress under the Actions tab), you’ll find the installer
ready for download under Releases (ignore the zip and tar.gz files):
Note: The one-click installer is a normal Python installation that you can use with multiple Excel work-
books. Hence, you don’t need to create a separate installer for each workbook as long as they all work with
the same set of dependencies as defined by the requirements.txt file.
The release command is part of the xlwings CLI (command-line client) and will prepare your Excel file to
work with the one-click installer generated in the previous step. Before anything else:
• Make sure that you have enabled Trust access to the VBA project object model
under File > Options > Trust Center > Trust Center Settings > Macro
Settings. You only need to do this once and since this is a developer setting, your end users won’t
need to bother about this. This setting is needed so that xlwings can update the Excel file with the
correct version of the VBA code.
• Run the installer from the previous step. This will not interfere with your existing Python installation
as it won’t touch your environment variables or registry. Instead, it will only write to the following
folder: %LOCALAPPDATA%\<installer-name>.
• Make sure that your local version of xlwings corresponds to the version of xlwings in the
requirements.txt from the installer. The easiest way to double-check this is to run pip
freeze on a Command Prompt or Anaconda Prompt. If your local version of xlwings differs, in-
stall the same version as the installer uses via: pip install xlwings==<version from
installer>.
To work with the release command, you should have your workbook in the xlsm format and all the Python
modules in the same folder:
myworkbook.xlsm
mymodule_one.py
mymodule_two.py
...
You currently can’t organize your code in directories, but you can easily import mymodule_two from
mymodule_one.
Make sure that your Excel workbook is the active workbook, then run the following command on a Com-
mand/Anaconda Prompt:
xlwings release
If this is the first time you are running this command, you will be asked a few questions. If you are shown a
[Y/n], you can hit Enter to accept the default as expressed by the capitalized letter:
• Name of your one-click installer? Type in the name of your one-click installer. If you
want to use a different Python distribution (e.g., Anaconda), you can leave this empty (but you will
need to update the xlwings.conf sheet with the Conda settings once the release command has been
run).
• Embed your Python code? [Y/n] This will copy the Python code into the sheets of the Excel
file. It will respect all Python files that are in the same folder as the Excel workbook.
• Hide the config sheet? [Y/n] This will hide the xlwings.conf sheet.
• Hide the sheets with the embedded Python code? [Y/n] If you embed your
Python code, this will hide all sheets with a .py ending.
• Allow your tool to run without the xlwings add-in? [Y/n] This will remove
the VBA reference to xlwings and copy in the xlwings VBA modules so that the end users don’t need to
have the xlwings add-in installed. Note that in this case, you will need to have your RunPython calls
bound to a button as you can’t use the Ribbon’s Run main button anymore.
Whatever answers you pick, you can always change them later by editing the xlwings.conf sheet or by
deleting the xlwings.conf sheet and re-running the xlwings release command. If you go with the
defaults, you only need to provide your end users with the one-click installer and the Excel workbook, no
external Python files are required.
To edit your Python code, it’s easiest to work with external Python files and not with embedded code. To
stop xlwings from using the embedded code, simply delete all sheets with a .py ending and the workbook
will again use the external Python modules. Once you are done editing the files, simply run the xlwings
release command again, which will embed the updated code. If you haven’t done any changes to your
dependencies (i.e., you haven’t upgraded a package or introduced a new one), you only need to redeploy
your Excel workbook to have the end users get the update.
If you did make changes to the requirements.txt and release a new one-click installer, you will need
to have the users install the new version of the installer first.
Note: Every time you change the xlwings version in requirements.txt of your one-click installer,
make sure to upgrade your local xlwings installatino to the same version and run xlwings release
again!
When you run the xlwings release command, your code will be embedded automatically (except if
you switch this behavior off). You can, however, also embed code directly: on a command line, run the
following command:
This will import all Python files from the current directory and paste them into Excel sheets of the cur-
rently active workbook. Now, you can use RunPython as usual: RunPython "import mymodule;
mymodule.myfunction()".
Note that you can have multiple Excel sheets and import them like normal Python files. Consider this
example:
You can call the main function from VBA like so:
Sub RandomNumbers()
RunPython "import random_numbers;random_numbers.main()"
End Sub
Note:
• UDFs modules don’t have to be added to the UDF Modules explicitly when using embedded code.
However, in contrast to how it works with external files, you currently need to re-import the functions
when you change them.
• While you can hide your sheets with your code, they will be written to a temporary directory in clear
text.
Note: This feature does not stop users from running arbitrary Python code through Python directly. Rather,
think of it as a mechanism to prevent accidental execution of Python code from Excel via xlwings.
26.1 Prerequisites
• This functionality requires every end user to have the requests and cryptography libraries
installed. You can install them via pip:
123
xlwings - Make Excel Fly!, Release dev
or via Conda:
• You need to have a LICENSE_KEY in the form of a trial key, a paid license key or a deploy key.
26.2 Configuration
While xlwings offers various ways to configure your workbook (see Configuration), it will only respect the
permissioning settings in the config file in the user’s home folder (on Windows, this is %USERPROFILE%\.
xlwings\xlwings.conf):
• To prevent end users from overwriting xlwings.conf, you’ll need to make sure that the file is
owned by the Administrator while giving end users read-only permissions.
• Add the following settings while replacing the PERMISSION_CHECK_URL and
PERMISSION_CHECK_METHOD (POST or GET) with the appropriate value for your case:
"LICENSE_KEY","YOUR_LICENSE_OR_DEPLOY_KEY"
"PERMISSION_CHECK_ENABLED","True"
"PERMISSION_CHECK_URL","https://myurl.com"
"PERMISSION_CHECK_METHOD","POST"
You can generate the static JSON file by using the xlwings CLI:
• Print the JSON string for all Python modules in a certain folder:
cd myfolder
xlwings permission cwd
• Print the JSON string for all embedded modules of the active workbook:
{
"modules": [
{
"file_name": "myfile.py",
"sha256":
˓→"cea259922207049a734c88930b5c09109deb6b55f692fd0832f4e57052d85896",
"machine_names": [
"DESKTOP-QQ27RP3"
(continues on next page)
If you work with POST requests, xlwings will post a payload similar to the following:
{
"machine_name": "DESKTOP-QQ27RP3",
"modules": [
{
"file_name": "myfile.py",
"sha256":
˓→"cea259922207049a734c88930b5c09109deb6b55f692fd0832f4e57052d85896"
},
{
"file_name": "myfile2.py",
"sha256":
˓→"355200bb9ae00fcec1d7b660e7dd95fb3dbf246a9db397a6daa2471458a8e6cb"
}
]
}
Note that xlwings only checks for HTTP status code 200, so any other status code will fail.
Python API
Note: Only use this in an interactive context like e.g. a Jupyter notebook! Don’t use this in a script
as it depends on the active book.
Parameters
• obj (any type with built-in converter) – the object to display,
e.g. numbers, strings, lists, numpy arrays, pandas dataframes
• sheet (Sheet, default None) – Sheet object. If none provided, the first
sheet of a new workbook is used.
• table (bool, default True) – If your object is a pandas DataFrame, by
default it is formatted as an Excel Table
• chunksize (int, default 5000) – Chunks the loading of big arrays.
Examples
127
xlwings - Make Excel Fly!, Release dev
Note: Only use this in an interactive context like e.g. a Jupyter notebook! Don’t use this in a script
as it depends on the active book.
Parameters
• index (bool or int, default 1) – Defines the number of columns on
the left that will be turned into the DataFrame’s index
• header (bool or int, default 1) – Defines the number of rows at the
top that will be turned into the DataFrame’s columns
• chunksize (int, default 5000) – Chunks the loading of big arrays.
Examples
27.2.1 Apps
class xlwings.main.Apps(impl)
A collection of all app objects:
active
Returns the active app.
New in version 0.9.0.
add()
Creates a new App. The new App becomes the active one. Returns an App object.
count
Returns the number of apps.
New in version 0.9.0.
keys()
Provides the PIDs of the Excel instances that act as keys in the Apps collection.
New in version 0.13.0.
27.2.2 App
import xlwings as xw
>>> xw.apps
Apps([<Excel App 1668>, <Excel App 1644>])
>>> xw.apps[1668] # get the available PIDs via xw.apps.keys()
<Excel App 1668>
>>> xw.apps.active
<Excel App 1668>
Parameters
• visible (bool, default None) – Returns or sets a boolean value that
determines whether the app is visible. The default leaves the state unchanged or
sets visible=True if the object doesn’t exist yet.
• spec (str, default None) – Mac-only, use the full path to the Excel appli-
cation, e.g. /Applications/Microsoft Office 2011/Microsoft
Excel or /Applications/Microsoft Excel
On Windows, if you want to change the version of Excel that xlwings talks to, go
to Control Panel > Programs and Features and Repair the Of-
fice version that you want as default.
Note: On Mac, while xlwings allows you to run multiple instances of Excel, it’s a feature that is
not officially supported by Excel for Mac: Unlike on Windows, Excel will not ask you to open a
read-only version of a file if it is already open in another instance. This means that you need to watch
out yourself so that the same file is not being overwritten from different instances.
activate(steal_focus=False)
Activates the Excel app.
Parameters steal_focus (bool, default False) – If True, make front-
most application and hand over focus from Python to Excel.
New in version 0.9.0.
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.9.0.
books
A collection of all Book objects that are currently open.
New in version 0.9.0.
calculate()
Calculates all open books.
New in version 0.3.6.
calculation
Returns or sets a calculation value that represents the calculation mode. Modes: 'manual',
'automatic', 'semiautomatic'
Examples
Examples
Function MySum(x, y)
MySum = x + y
End Function
Examples
import xlwings as xw
app = App()
# Makes sure the status bar is reset even if an error happens in the
˓→with block
with app.properties(status_bar='Calculating...'):
# do stuff
quit()
Quits the application without saving any workbooks.
New in version 0.3.3.
range(cell1, cell2=None)
Range object from the active sheet of the active book, see Range().
New in version 0.9.0.
screen_updating
Turn screen updating off to speed up your script. You won’t be able to see what the script is
doing, but it will run faster. Remember to set the screen_updating property back to True when
your script ends.
New in version 0.3.3.
selection
Returns the selected cells as Range.
New in version 0.9.0.
startup_path
Returns the path to XLSTART which is where the xlwings add-in gets copied to by doing
xlwings addin install.
New in version 0.19.4.
status_bar
Gets or sets the value of the status bar. Returns False if Excel has control of it.
New in version 0.20.0.
version
Returns the Excel version number object.
Examples
27.2.3 Books
class xlwings.main.Books(impl)
A collection of all book objects:
27.2.4 Book
The easiest way to connect to a book is offered by xw.Book: it looks for the book in all app instances
and returns an error, should the same book be open in multiple instances. To connect to a book in the
active app instance, use xw.books and to refer to a specific app, use:
xw.Book xw.books
New book xw.Book() xw.books.add()
Unsaved book xw.Book('Book1') xw.books['Book1']
Book by xw.Book(r'C:/path/to/ xw.books.open(r'C:/path/to/
(full)name file.xlsx') file.xlsx')
Parameters
• fullname (str or path-like object, default None) – Full path
or name (incl. xlsx, xlsm etc.) of existing workbook or name of an unsaved work-
book. Without a full path, it looks for the file in the current working directory.
• update_links (bool, default None) – If this argument is omitted, the
user is prompted to specify how links will be updated
• read_only (bool, default False) – True to open workbook in read-
only mode
• format (str) – If opening a text file, this specifies the delimiter character
• password (str) – Password to open a protected workbook
• write_res_password (str) – Password to write to a write-reserved work-
book
• ignore_read_only_recommended (bool, default False) – Set to
True to mute the read-only recommended message
• origin (int) – For text files only. Specifies where it originated. Use XlPlat-
form constants.
• delimiter (str) – If format argument is 6, this specifies the delimiter.
• editable (bool, default False) – This option is only for legacy Mi-
crosoft Excel 4.0 addins.
• notify (bool, default False) – Notify the user when a file becomes
available If the file cannot be opened in read/write mode.
• converter (int) – The index of the first file converter to try when opening the
file.
• add_to_mru (bool, default False) – Add this workbook to the list of
recently added workbooks.
• local (bool, default False) – If True, saves files against the language
of Excel, otherwise against the language of VBA. Not supported on macOS.
• corrupt_load (int, default xlNormalLoad) – Can be one of xlNor-
malLoad, xlRepairFile or xlExtractData. Not supported on macOS.
activate(steal_focus=False)
Activates the book.
Parameters steal_focus (bool, default False) – If True, make front-
most window and hand over focus from Python to Excel.
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.9.0.
app
Returns an app object that represents the creator of the book.
New in version 0.9.0.
classmethod caller()
References the calling book when the Python function is called from Excel via RunPython.
Pack it into the function being called from Excel, e.g.:
import xlwings as xw
def my_macro():
wb = xw.Book.caller()
wb.sheets[0].range('A1').value = 1
To be able to easily invoke such code from Python for debugging, use xw.Book.
set_mock_caller().
New in version 0.3.0.
close()
Closes the book without saving it.
New in version 0.1.1.
fullname
Returns the name of the object, including its path on disk, as a string. Read-only String.
macro(name)
Runs a Sub or Function in Excel VBA.
Parameters name (Name of Sub or Function with or without module name, e.g.
'Module1.MyMacro' or 'MyMacro') –
Examples
Function MySum(x, y)
MySum = x + y
End Function
Example
Examples
# This code runs unchanged from Excel via RunPython and from Python
˓→directly
import os
import xlwings as xw
def my_macro():
sht = xw.Book.caller().sheets[0]
sht.range('A1').value = 'Hello xlwings!'
if __name__ == '__main__':
xw.Book('file.xlsm').set_mock_caller()
my_macro()
Examples
>>> wb = xw.Book()
>>> wb.sheets[0]['A1'].value = 'PDF'
>>> wb.to_pdf()
27.2.5 PageSetup
class xlwings.main.PageSetup(impl)
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.24.2.
print_area
Gets or sets the range address that defines the print area.
Examples
27.2.6 Sheets
class xlwings.main.Sheets(impl)
A collection of all sheet objects:
27.2.7 Sheet
Examples
Examples
# Create two books and add a value to the first sheet of the first
˓→book
first_book = xw.Book()
second_book = xw.Book()
first_book.sheets[0]['A1'].value = 'some value'
delete()
Deletes the Sheet.
index
Returns the index of the Sheet (1-based as in Excel).
name
Gets or sets the name of the Sheet.
names
Returns a names collection that represents all the sheet-specific names (names defined with the
“SheetName!” prefix).
New in version 0.9.0.
page_setup
Returns a PageSetup object.
New in version 0.24.2.
pictures
See Pictures
New in version 0.9.0.
range(cell1, cell2=None)
Returns a Range object from the active sheet of the active book, see Range().
New in version 0.9.0.
render_template(**data)
This method requires xlwings PRO.
Replaces all Jinja variables (e.g {{ myvar }}) in the sheet with the keyword argument that
has the same name. Following variable types are supported:
strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, PIL Image objects that
have a filename and Matplotlib figures.
Examples
Examples
>>> wb = xw.Book()
>>> sheet = wb.sheets[0]
>>> sheet['A1'].value = 'PDF'
>>> sheet.to_pdf()
27.2.8 Range
Examples
Active Sheet:
import xlwings as xw
xw.Range('A1')
xw.Range('A1:C3')
xw.Range((1,1))
xw.Range((1,1), (3,3))
xw.Range('NamedRange')
xw.Range(xw.Range('A1'), xw.Range('B2'))
Specific Sheet:
xw.books['MyBook.xlsx'].sheets[0].range('A1')
Examples
count
Returns the number of cells.
current_region
This property returns a Range object representing a range bounded by (but not including) any
combination of blank rows and blank columns or the edges of the worksheet. It corresponds to
Ctrl-* on Windows and Shift-Ctrl-Space on Mac.
Returns
Return type Range object
delete(shift=None)
Deletes a cell or range of cells.
Parameters shift (str, default None) – Use left or up. If omitted, Excel
decides based on the shape of the range.
Returns
Return type None
end(direction)
Returns a Range object that represents the cell at the end of the region that contains the source
range. Equivalent to pressing Ctrl+Up, Ctrl+down, Ctrl+left, or Ctrl+right.
Parameters direction (One of 'up', 'down', 'right', 'left') –
Examples
Examples
Examples
Examples
Returns
Return type Range
Example
Examples
row_height
Gets or sets the height, in points, of a Range. If all rows in the Range have the same height,
returns the height. If rows in the Range have different heights, returns None.
row_height must be in the range: 0 <= row_height <= 409.5
Note: If the Range is outside the used range of the Worksheet, and rows in the Range have
different heights, returns the height of the first row.
Returns
Return type float
New in version 0.4.0.
rows
Returns a RangeRows object that represents the rows in the specified range.
New in version 0.9.0.
select()
Selects the range. Select only works on the active book.
New in version 0.9.0.
shape
Tuple of Range dimensions.
New in version 0.3.0.
sheet
Returns the Sheet object to which the Range belongs.
New in version 0.9.0.
size
Number of elements in the Range.
New in version 0.3.0.
table
Returns a Table object if the range is part of one, otherwise None.
New in version 0.21.0.
top
Returns the distance, in points, from the top edge of row 1 to the top edge of the range. Read-
only.
Returns
Return type float
New in version 0.6.0.
unmerge()
Separates a merged area into individual cells.
value
Gets and sets the values for the given Range. See see xlwings.Range.options() about
how to set options, e.g. to transform it into a DataFrame or how to set a chunksize.
Returns object
Return type returned object depends on the converter being used, see xlwings.
Range.options()
width
Returns the width, in points, of a Range. Read-only.
Returns
Return type float
New in version 0.4.0.
wrap_text
Returns True if the wrap_text property is enabled and False if it’s disabled. If not all cells
have the same value in a range, on Windows it returns None and on macOS False.
New in version 0.23.2.
27.2.9 RangeRows
class xlwings.RangeRows(rng)
Represents the rows of a range. Do not construct this class directly, use Range.rows instead.
Example
import xlwings as xw
rng = xw.Range('A1:C4')
rng.rows[0].value = 'a'
for r in rng.rows:
print(r.address)
autofit()
Autofits the height of the rows.
count
Returns the number of rows.
New in version 0.9.0.
27.2.10 RangeColumns
class xlwings.RangeColumns(rng)
Represents the columns of a range. Do not construct this class directly, use Range.columns in-
stead.
Example
import xlwings as xw
rng = xw.Range('A1:C4')
rng.columns[0].value = 'a'
for c in rng.columns:
print(c.address)
autofit()
Autofits the width of the columns.
count
Returns the number of columns.
New in version 0.9.0.
27.2.11 Shapes
class xlwings.main.Shapes(impl)
A collection of all shape objects on the specified sheet:
27.2.12 Shape
27.2.13 Charts
class xlwings.main.Charts(impl)
A collection of all chart objects on the specified sheet:
Returns
Return type Chart
Examples
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
count
Returns the number of objects in the collection.
27.2.14 Chart
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.9.0.
chart_type
Returns and sets the chart type of the chart. The following chart types are available:
3d_area, 3d_area_stacked, 3d_area_stacked_100, 3d_bar_clustered,
3d_bar_stacked, 3d_bar_stacked_100, 3d_column, 3d_column_clustered,
3d_column_stacked, 3d_column_stacked_100, 3d_line, 3d_pie,
3d_pie_exploded, area, area_stacked, area_stacked_100, bar_clustered,
bar_of_pie, bar_stacked, bar_stacked_100, bubble, bubble_3d_effect,
column_clustered, column_stacked, column_stacked_100,
combination, cone_bar_clustered, cone_bar_stacked,
cone_bar_stacked_100, cone_col, cone_col_clustered,
cone_col_stacked, cone_col_stacked_100, cylinder_bar_clustered,
cylinder_bar_stacked, cylinder_bar_stacked_100,
cylinder_col, cylinder_col_clustered, cylinder_col_stacked,
27.2.15 Pictures
class xlwings.main.Pictures(impl)
A collection of all picture objects on the specified sheet:
Examples
1. Picture
2. Matplotlib
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
count
Returns the number of objects in the collection.
27.2.16 Picture
class xlwings.Picture(impl=None)
The picture object is a member of the pictures collection:
lock_aspect_ratio
True will keep the original proportion, False will allow you to change height and width
independently of each other (read/write).
New in version 0.24.0.
name
Returns or sets the name of the picture.
New in version 0.5.0.
parent
Returns the parent of the picture.
New in version 0.9.0.
top
Returns or sets the number of points that represent the vertical position of the picture.
New in version 0.5.0.
update(image, format=None)
Replaces an existing picture with a new one, taking over the attributes of the existing picture.
Parameters image (str or path-like object or matplotlib.
figure.Figure) – Either a filepath or a Matplotlib figure object.
New in version 0.5.0.
width
Returns or sets the number of points that represent the width of the picture.
New in version 0.5.0.
27.2.17 Names
class xlwings.main.Names(impl)
A collection of all name objects in the workbook:
Returns
Return type Name
New in version 0.9.0.
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.9.0.
count
Returns the number of objects in the collection.
27.2.18 Name
class xlwings.Name(impl)
The name object is a member of the names collection:
27.2.19 Note
class xlwings.main.Note(impl)
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.24.2.
delete()
Delete the note.
New in version 0.24.2.
text
Gets or sets the text of a note. Keep in mind that the note must already exist!
Examples
27.2.20 Tables
class xlwings.main.Tables(impl)
A collection of all table objects on the specified sheet:
Examples
27.2.21 Table
display_name
Returns or sets the display name for the specified Table object
header_row_range
Returns an xlwings range object that represents the range of the header row
insert_row_range
Returns an xlwings range object representing the row where data is going to be inserted. This is
only available for empty tables, otherwise it’ll return None
name
Returns or sets the name of the Table.
parent
Returns the parent of the table.
range
Returns an xlwings range object of the table.
resize(range)
Resize a Table by providing an xlwings range object
New in version 0.24.4.
show_autofilter
Turn the autofilter on or off by setting it to True or False (read/write boolean)
show_headers
Show or hide the header (read/write)
show_table_style_column_stripes
Returns or sets if the Column Stripes table style is used for (read/write boolean)
show_table_style_first_column
Returns or sets if the first column is formatted (read/write boolean)
show_table_style_last_column
Returns or sets if the last column is displayed (read/write boolean)
show_table_style_row_stripes
Returns or sets if the Row Stripes table style is used (read/write boolean)
show_totals
Gets or sets a boolean to show/hide the Total row.
table_style
Gets or sets the table style. See Tables.add for possible values.
totals_row_range
Returns an xlwings range object representing the Total row
update(data, index=True)
This method requires xlwings PRO
Updates the Excel table with the provided data. Currently restricted to DataFrames.
Changed in version 0.24.0.
Parameters
• data (pandas DataFrame) – Currently restricted to pandas DataFrames.
If you want to hide the index, set the first column as the index, e.g. df.
set_index('column_name').
• index (bool, default True) – Whether or not the index of a pandas
DataFrame should be written to the Excel table.
Returns
Return type Table
Examples
import pandas as pd
import xlwings as xw
sheet = xw.Book('Book1.xlsx').sheets[0]
table_name = 'mytable'
# Sample DataFrame
nrows, ncols = 3, 3
df = pd.DataFrame(data=nrows * [ncols * ['test']],
columns=['col ' + str(i) for i in range(ncols)])
# Hide the index, then insert a new table if it doesn't exist yet,
# otherwise update the existing one
df = df.set_index('col 0')
if table_name in [table.name for table in sheet.tables]:
sheet.tables[table_name].update(df)
else:
mytable = sheet.tables.add(source=sheet['A1'], name=table_name).
˓→update(df)
27.2.22 Font
class xlwings.main.Font(impl)
The font object can be accessed as an attribute of the range or shape object.
• mysheet['A1'].font
• mysheet.shapes[0].font
New in version 0.23.0.
api
Returns the native object (pywin32 or appscript obj) of the engine being used.
New in version 0.23.0.
bold
Returns or sets the bold property (boolean).
>>> sheet['A1'].font.size = 13
>>> sheet['A1'].font.size
13
27.2.23 Characters
class xlwings.main.Characters(impl)
The characters object can be accessed as an attribute of the range or shape object.
• mysheet['A1'].characters
• mysheet.shapes[0].characters
Note: On macOS, characters are currently not supported due to bugs/lack of support in Apple-
Script.
27.2.24 Markdown
Note: On macOS, formatting is currently not supported, but things like bullet points will still work.
Parameters
• text (str) – The text in Markdown syntax
• style (MarkdownStyle object, optional) – The MarkdownStyle ob-
ject defines how the text will be formatted.
Examples
27.2.25 MarkdownStyle
class xlwings.pro.MarkdownStyle
MarkdownStyle defines how Markdown objects are being rendered in Excel cells or shapes. Start
by instantiating a MarkdownStyle object. Printing it will show you the current (default) style:
>>> style = MarkdownStyle()
>>> style
<MarkdownStyle>
h1.font: .bold: True
h1.blank_lines_after: 1
paragraph.blank_lines_after: 1
unordered_list.bullet_character: •
unordered_list.blank_lines_after: 1
strong.bold: True
emphasis.italic: True
You can override the defaults, e.g., to make **strong** text red instead of bold, do this:
>>> style.strong.bold = False
>>> style.strong.color = (255, 0, 0)
>>> style.strong
strong.color: (255, 0, 0)
import xlwings as xw
import numpy as np
@xw.func
@xw.arg('x', np.array, ndim=2)
def add_one(x):
return x + 1
xlwings.ret(convert=None, **options)
Apply converters and options to return values, see also Range.options().
Examples
1) Suppress the index and header of a returned DataFrame:
import pandas as pd
@xw.func
@xw.ret(index=False, header=False)
def get_dataframe(n, m):
return pd.DataFrame(np.arange(n * m).reshape((n, m)))
2) Dynamic array:
Note: If your version of Excel supports the new native dynamic arrays, then you don’t have to
do anything special, and you shouldn’t use the expand decorator! To check if your version of
Excel supports it, see if you have the =UNIQUE() formula available. Native dynamic arrays were
introduced in Office 365 Insider Fast at the end of September 2018.
expand='table' turns the UDF into a dynamic array. Currently you must not use volatile func-
tions as arguments of a dynamic array, e.g. you cannot use =TODAY() as part of a dynamic array.
Also note that a dynamic array needs an empty row and column at the bottom and to the right and will
overwrite existing data without warning.
Unlike standard Excel arrays, dynamic arrays are being used from a single cell like a standard function
and auto-expand depending on the dimensions of the returned array:
import xlwings as xw
import numpy as np
@xw.func
@xw.ret(expand='table')
def dynamic_array(n, m):
return np.arange(n * m).reshape((n, m))
27.4 Reports
Examples
In my_template.xlsx, put the following Jinja variables in two cells: {{ title }} and {{
df }}
With many template variables it may be useful to collect the data first:
**data)
You can control the Excel instance by passing in an xlwings App instance. For example, to run the
report in a separate and hidden instance of Excel, do the following:
class xlwings.pro.reports.Image(filename)
Use this class to provide images to either mysheet.render_template() or xw.pro.
reports.create_report().
Parameters filename (str or pathlib.Path object) – The file name or path
class xlwings.pro.reports.Markdown(text, style=<MarkdownStyle> h1.font:
.bold: True paragraph.blank_lines_after:
1 unordered_list.bullet_character: • un-
ordered_list.blank_lines_after: 1 strong.bold:
True emphasis.italic: True)
Markdown objects can be assigned to a single cell or shape via myrange.value or myshape.
text. They accept a string in Markdown format which will cause the text in the cell to be formatted
accordingly. They can also be used in mysheet.render_template().
Note: On macOS, formatting is currently not supported, but things like bullet points will still work.
Parameters
• text (str) – The text in Markdown syntax
• style (MarkdownStyle object, optional) – The MarkdownStyle ob-
ject defines how the text will be formatted.
Examples
You can override the defaults, e.g., to make **strong** text red instead of bold, do this:
REST API
28.1 Quickstart
xlwings offers an easy way to expose an Excel workbook via REST API both on Windows and macOS. This
can be useful when you have a workbook running on a single computer and want to access it from another
computer. Or you can build a Linux based web app that can interact with a legacy Excel application while
you are in the progress of migrating the Excel functionality into your web app (if you need help with that,
give us a shout).
You can run the REST API server from a command prompt or terminal as follows (this requires Flask>=1.0,
so make sure to pip install Flask):
Then perform a GET request e.g. via PowerShell on Windows or Terminal on Mac (while having an unsaved
“Book1” open). Note that you need to run the server and the GET request from two separate terminals (or
you can use something more convenient like Postman or Insomnia for testing the API):
$ curl "http://127.0.0.1:5000/book/book1/sheets/0/range/A1:B2"
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 10.0,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
(continues on next page)
175
xlwings - Make Excel Fly!, Release dev
In the command prompt where your server is running, press Ctrl-C to shut it down again.
The xlwings REST API is a thin wrapper around the Python API which makes it very easy if you have
worked previously with xlwings. It also means that the REST API does require the Excel application to be
up and running which makes it a great choice if the data in your Excel workbook is constantly changing as
the REST API will always deliver the current state of the workbook without the need of saving it first.
Note: Currently, we only provide the GET methods to read the workbook. If you are also interested in
the POST methods to edit the workbook, let us know via GitHub issues. Some other things will also need
improvement, most notably exception handling.
xlwings restapi run will run a Flask development server on http://127.0.0.1:5000. You can pro-
vide --host and --port as command line args and it also respects the Flask environment variables like
FLASK_ENV=development.
If you want to have more control, you can run the server directly with Flask, see the Flask docs for more
details:
set FLASK_APP=xlwings.rest.api
flask run
28.3 Indexing
While the Python API offers Python’s 0-based indexing (e.g. xw.books[0]) as well as Excel’s 1-based
indexing (e.g. xw.books(1)), the REST API only offers 0-based indexing, e.g. /books/0.
The REST API accepts Range options as query parameters, see xlwings.Range.options() e.g.
/book/book1/sheets/0/range/A1?expand=table&transpose=true
Remember that options only affect the value property.
28.6.1 /book
GET /book/<fullname_or_name>
Example response:
{
"app": 1104,
"fullname": "C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"name": "Book1.xlsx",
"names": [
"Sheet1!myname1",
"myname2"
],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1",
"Sheet2"
]
}
GET /book/<fullname_or_name>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
},
{
"name": "myname2",
"refers_to": "=Sheet1!$A$1"
}
]
}
GET /book/<fullname_or_name>/names/<name>
Example response:
{
"name": "myname2",
"refers_to": "=Sheet1!$A$1"
}
GET /book/<fullname_or_name>/names/<name>/range
Example response:
{
"address": "$A$1",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 1,
"current_region": "$A$1:$B$2",
"formula": "=1+1.1",
"formula_array": "=1+1,1",
"height": 14.25,
"last_cell": "$A$1",
"left": 0.0,
"name": "myname2",
"number_format": "General",
"row": 1,
"row_height": 14.3,
"shape": [
1,
1
],
"size": 1,
"top": 0.0,
"value": 2.1,
"width": 51.0
}
GET /book/<fullname_or_name>/sheets
Example response:
{
"sheets": [
{
"charts": [
"Chart 1"
],
"name": "Sheet1",
"names": [
"Sheet1!myname1"
],
"pictures": [
"Picture 3"
],
"shapes": [
"Chart 1",
"Picture 3"
],
"used_range": "$A$1:$B$2"
},
{
"charts": [],
"name": "Sheet2",
"names": [],
(continues on next page)
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>
Example response:
{
"charts": [
"Chart 1"
],
"name": "Sheet1",
"names": [
"Sheet1!myname1"
],
"pictures": [
"Picture 3"
],
"shapes": [
"Chart 1",
"Picture 3"
],
"used_range": "$A$1:$B$2"
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/charts
Example response:
{
"charts": [
{
"chart_type": "line",
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"width": 355.0
}
]
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/charts/<chart_name_or_ix>
Example response:
{
"chart_type": "line",
(continues on next page)
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
]
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/names/<sheet_scope_name>
Example response:
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/names/<sheet_scope_name>/ran
Example response:
{
"address": "$B$2:$C$3",
"color": null,
"column": 2,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"",
""
],
[
"",
""
]
],
"formula_array": "",
"height": 28.5,
(continues on next page)
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/pictures
Example response:
{
"pictures": [
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"width": 100.0
}
]
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/pictures/<picture_name_or_ix
Example response:
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"width": 100.0
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/range
Example response:
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"=1+1.1",
"a string"
],
[
"43395.0064583333",
""
]
],
"formula_array": null,
"height": 28.5,
"last_cell": "$B$2",
"left": 0.0,
"name": null,
"number_format": null,
"row": 1,
"row_height": 14.3,
"shape": [
2,
2
],
"size": 4,
"top": 0.0,
"value": [
[
2.1,
"a string"
],
[
"Mon, 22 Oct 2018 00:09:18 GMT",
null
]
],
"width": 102.0
}
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/range/<address>
Example response:
{
"address": "$A$1:$B$2",
(continues on next page)
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/shapes
Example response:
{
"shapes": [
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
(continues on next page)
GET /book/<fullname_or_name>/sheets/<sheet_name_or_ix>/shapes/<shape_name_or_ix>
Example response:
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"type": "chart",
"width": 355.0
}
28.6.2 /books
GET /books
Example response:
{
"books": [
{
"app": 1104,
"fullname": "Book1",
"name": "Book1",
"names": [],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1"
]
},
{
"app": 1104,
"fullname": "C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"name": "Book1.xlsx",
(continues on next page)
GET /books/<book_name_or_ix>
Example response:
{
"app": 1104,
"fullname": "C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"name": "Book1.xlsx",
"names": [
"Sheet1!myname1",
"myname2"
],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1",
"Sheet2"
]
}
GET /books/<book_name_or_ix>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
},
(continues on next page)
GET /books/<book_name_or_ix>/names/<name>
Example response:
{
"name": "myname2",
"refers_to": "=Sheet1!$A$1"
}
GET /books/<book_name_or_ix>/names/<name>/range
Example response:
{
"address": "$A$1",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 1,
"current_region": "$A$1:$B$2",
"formula": "=1+1.1",
"formula_array": "=1+1,1",
"height": 14.25,
"last_cell": "$A$1",
"left": 0.0,
"name": "myname2",
"number_format": "General",
"row": 1,
"row_height": 14.3,
"shape": [
1,
1
],
"size": 1,
"top": 0.0,
"value": 2.1,
"width": 51.0
}
GET /books/<book_name_or_ix>/sheets
Example response:
{
"sheets": [
(continues on next page)
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>
Example response:
{
"charts": [
"Chart 1"
],
"name": "Sheet1",
"names": [
"Sheet1!myname1"
],
"pictures": [
"Picture 3"
],
"shapes": [
"Chart 1",
"Picture 3"
],
"used_range": "$A$1:$B$2"
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/charts
Example response:
{
"charts": [
{
"chart_type": "line",
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"width": 355.0
}
]
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/charts/<chart_name_or_ix>
Example response:
{
"chart_type": "line",
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"width": 355.0
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
]
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names/<sheet_scope_name>
Example response:
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names/<sheet_scope_name>/ran
Example response:
{
"address": "$B$2:$C$3",
"color": null,
"column": 2,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"",
""
],
[
"",
""
]
],
"formula_array": "",
"height": 28.5,
"last_cell": "$C$3",
"left": 51.0,
"name": "Sheet1!myname1",
"number_format": "General",
"row": 2,
"row_height": 14.3,
"shape": [
2,
2
],
"size": 4,
"top": 14.25,
"value": [
[
null,
null
],
[
null,
null
]
],
"width": 102.0
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/pictures
Example response:
{
"pictures": [
{
"height": 100.0,
"left": 0.0,
(continues on next page)
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/pictures/<picture_name_or_ix
Example response:
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"width": 100.0
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/range
Example response:
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"=1+1.1",
"a string"
],
[
"43395.0064583333",
""
]
],
"formula_array": null,
"height": 28.5,
"last_cell": "$B$2",
"left": 0.0,
"name": null,
"number_format": null,
"row": 1,
"row_height": 14.3,
"shape": [
2,
2
],
(continues on next page)
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/range/<address>
Example response:
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"=1+1.1",
"a string"
],
[
"43395.0064583333",
""
]
],
"formula_array": null,
"height": 28.5,
"last_cell": "$B$2",
"left": 0.0,
"name": null,
"number_format": null,
"row": 1,
"row_height": 14.3,
"shape": [
2,
2
],
"size": 4,
"top": 0.0,
"value": [
[
(continues on next page)
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/shapes
Example response:
{
"shapes": [
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"type": "chart",
"width": 355.0
},
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"type": "picture",
"width": 100.0
}
]
}
GET /books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/shapes/<shape_name_or_ix>
Example response:
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"type": "chart",
"width": 355.0
}
28.6.3 /apps
GET /apps
Example response:
{
"apps": [
{
"books": [
"Book1",
"C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"Book4"
],
"calculation": "automatic",
"display_alerts": true,
"pid": 1104,
"screen_updating": true,
"selection": "[Book1.xlsx]Sheet2!$A$1",
"version": "16.0",
"visible": true
},
{
"books": [
"Book2",
"Book5"
],
"calculation": "automatic",
"display_alerts": true,
"pid": 7920,
"screen_updating": true,
"selection": "[Book5]Sheet2!$A$1",
"version": "16.0",
"visible": true
}
]
}
GET /apps/<pid>
Example response:
{
"books": [
"Book1",
"C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"Book4"
],
"calculation": "automatic",
"display_alerts": true,
"pid": 1104,
"screen_updating": true,
"selection": "[Book1.xlsx]Sheet2!$A$1",
(continues on next page)
GET /apps/<pid>/books
Example response:
{
"books": [
{
"app": 1104,
"fullname": "Book1",
"name": "Book1",
"names": [],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1"
]
},
{
"app": 1104,
"fullname": "C:\\Users\\felix\\DEV\\xlwings\\scripts\\Book1.xlsx",
"name": "Book1.xlsx",
"names": [
"Sheet1!myname1",
"myname2"
],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1",
"Sheet2"
]
},
{
"app": 1104,
"fullname": "Book4",
"name": "Book4",
"names": [],
"selection": "Sheet2!$A$1",
"sheets": [
"Sheet1"
]
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>
Example response:
{
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
},
{
"name": "myname2",
"refers_to": "=Sheet1!$A$1"
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>/names/<name>
Example response:
{
"name": "myname2",
"refers_to": "=Sheet1!$A$1"
}
GET /apps/<pid>/books/<book_name_or_ix>/names/<name>/range
Example response:
{
"address": "$A$1",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 1,
"current_region": "$A$1:$B$2",
"formula": "=1+1.1",
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/sheets
Example response:
{
"sheets": [
{
"charts": [
"Chart 1"
],
"name": "Sheet1",
"names": [
"Sheet1!myname1"
],
"pictures": [
"Picture 3"
],
"shapes": [
"Chart 1",
"Picture 3"
],
"used_range": "$A$1:$B$2"
},
{
"charts": [],
"name": "Sheet2",
"names": [],
"pictures": [],
"shapes": [],
"used_range": "$A$1"
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>
Example response:
{
"charts": [
"Chart 1"
],
"name": "Sheet1",
"names": [
"Sheet1!myname1"
],
"pictures": [
"Picture 3"
],
"shapes": [
"Chart 1",
"Picture 3"
],
"used_range": "$A$1:$B$2"
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/charts
Example response:
{
"charts": [
{
"chart_type": "line",
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"width": 355.0
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/charts/<chart_nam
Example response:
{
"chart_type": "line",
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"width": 355.0
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names
Example response:
{
"names": [
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names/<sheet_scop
Example response:
{
"name": "Sheet1!myname1",
"refers_to": "=Sheet1!$B$2:$C$3"
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/names/<sheet_scop
Example response:
{
"address": "$B$2:$C$3",
"color": null,
"column": 2,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"",
""
],
[
"",
""
]
],
"formula_array": "",
"height": 28.5,
"last_cell": "$C$3",
"left": 51.0,
"name": "Sheet1!myname1",
"number_format": "General",
"row": 2,
"row_height": 14.3,
"shape": [
2,
2
],
"size": 4,
"top": 14.25,
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/pictures
Example response:
{
"pictures": [
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"width": 100.0
}
]
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/pictures/<picture
Example response:
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
"width": 100.0
}
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/range
Example response:
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/range/<address>
Example response:
{
"address": "$A$1:$B$2",
"color": null,
"column": 1,
"column_width": 8.47,
"count": 4,
"current_region": "$A$1:$B$2",
"formula": [
[
"=1+1.1",
"a string"
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/shapes
Example response:
{
"shapes": [
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"type": "chart",
"width": 355.0
},
{
"height": 100.0,
"left": 0.0,
"name": "Picture 3",
"top": 0.0,
(continues on next page)
GET /apps/<pid>/books/<book_name_or_ix>/sheets/<sheet_name_or_ix>/shapes/<shape_nam
Example response:
{
"height": 211.0,
"left": 0.0,
"name": "Chart 1",
"top": 0.0,
"type": "chart",
"width": 355.0
}
205
xlwings - Make Excel Fly!, Release dev
206 Index
xlwings - Make Excel Fly!, Release dev
Index 207
xlwings - Make Excel Fly!, Release dev
T
Table (class in xlwings.main), 165
table (xlwings.Range attribute), 153
table_style (xlwings.main.Table attribute), 166
Tables (class in xlwings.main), 164
tables (xlwings.Sheet attribute), 143
text (xlwings.main.Characters attribute), 169
text (xlwings.main.Note attribute), 164
text (xlwings.Shape attribute), 157
to_pdf() (xlwings.Book method), 138
to_pdf() (xlwings.Sheet method), 143
top (xlwings.Chart attribute), 159
top (xlwings.Picture attribute), 162
top (xlwings.Range attribute), 153
top (xlwings.Shape attribute), 157
totals_row_range (xlwings.main.Table at-
tribute), 166
type (xlwings.Shape attribute), 157
U
unmerge() (xlwings.Range method), 153
update() (xlwings.main.Table method), 166
update() (xlwings.Picture method), 162
used_range (xlwings.Sheet attribute), 144
V
value (xlwings.Range attribute), 153
version (xlwings.App attribute), 133
view() (in module xlwings), 127
visible (xlwings.App attribute), 133
visible (xlwings.Sheet attribute), 144
W
width (xlwings.Chart attribute), 159
width (xlwings.Picture attribute), 162
width (xlwings.Range attribute), 154
width (xlwings.Shape attribute), 157
wrap_text (xlwings.Range attribute), 154
X
xlwings (module), 127
xlwings.arg() (in module xlwings), 171
xlwings.func() (in module xlwings), 170
xlwings.pro.reports (module), 172
xlwings.ret() (in module xlwings), 171
xlwings.sub() (in module xlwings), 171
208 Index