The config file is used to control settings for PyXLL. It’s a plain text file that should be kept in the same folder as the PyXLL addin .xll file, and should be called the same as the addin but with the extension .cfg. In most cases this will simply be pyxll.cfg.
If you do not have a config file, or it’s not readable by PyXLL you will get an error when starting Excel or adding the addin and PyXLL will not work.
Paths used in the config file may be absolue or relative paths. Any relative paths should be relative to the config file.
Config values may contain environment variable substitutions. To substitute an environment variable into your value use %(your_envvar_name)s, eg verbosity = %(MY_PYXLL_LOG_VERBOSITY)s.
The config file is broken down into several section, each of which is documented below.
Settings that determine the basic behavior of the PyXLL addin are put in the [PYXLL] config section:
[PYXLL] pythonpath = semi-colon or new line delimited list of directories modules = comma or new line delimited list of python modules developer_mode = (optional) 1 or 0 indicating whether or not to use the developer mode external_config = (optional) paths of additional config files to load name = (optional) name of the addin visible in Excel allow_abort = (optional) 1 or 0 to set the default value for the allow_abort kwarg
The standard pythonpath is appended with whatever paths you specify in the pythonpath setting. This is useful so you can tell PyXLL where to look for the python modules containing your addin code.
When PyXLL is started (or re-loaded) it will import all modules listed in the config file. It’s these modules that expose worksheet functions and menu functions.
The developer_mode setting can be used to put PyXLL in a developer mode, which is useful when you’re developing your addin. In addition to whatever menu items you have added, when the developer mode is used there will be an additional menu item to reload the addin. This can be used to allow you to develop your python modules and test changes without having to restart Excel. If unset, the default is to not use the developer mode.
The external_config setting may be used to reference another config file somewhere else. For example, if you want to have the main pyxll.cfg installed on users’ local PCs but want to control the configuration via a shared file on the network you can use this to reference that external config file. Multiple external config files can be used by specifying them as a comma seperated list. Values in external config files override what’s in the parent config file, apart from pythonpath, modules and external_config which get appended to.
The name setting is optional and only has an effect when a valid license for PyXLL is found. It is used to change the name of the addin as it appears in Excel. When using this setting the addin in Excel is indistinguishable from any other addin, and there is no reference to the fact it was written using PyXLL. If there are any menu items in the default menu, that menu will take the name of the addin instead of the default ‘PyXLL’.
The allow_abort setting is optional and sets the default value for the allow_abort keyword argument to the decorators xl_func, xl_macro and xl_menu. It should be set to 1 for True or 0 for False. By default the allow_abort kwarg is False.
PyXLL redirects all stdout and stderr to a log file. All logging is done using the standard logging python module.
The [LOG] section of the config file determines where logging information is redirected to, and the verbosity of the information logged:
[LOG] verbosity = logging level (debug, info, warning, error or critical) path = directory of where to write the log file file = filename of the log file format = format string
The items in the config file may include substitution values that will be replaced with other section values or the config defaults setup by PyXLL.
These may be used, for example, to create the log file name file = pyxll.%(date)s.%(pid)s.%(xlversion)s.log. For more information about variable substitution in the config please see ConfigParser.get.
The format string is used by the logging module to format any log messages. An example format string is "%(asctime)s - %(name)s - %(levelname)s - %(message)s". For more information about log formatting, please see the logging module documentation.
For some python modules it can be helpful to set some environment variables before they are imported. Usually this would be done in the environment running the python script, but in Excel it’s more complicated as it would require either changing the global environment variables on each PC, or using a batch script to launch Excel.
For this reason, it’s possible to set environment variables in the [ENVIRONMENT] section of the config file:
[ENVIRONMENT] NAME = VALUE ...
For each environement variable you would like set, add a line to the [ENVIRONMENT] section.
If you have licensed PyXLL for commercial or evaluation use, you should put the license key in the [LICENSE] section of the config file.
If you do not have a license key, you may omit this section. Unlicensed versions of PyXLL will display a dialog box each time the addin is loaded which must be acknowledged before Excel will continue.
For convenience for users with site licenses it’s also possible to specify a license file instead of a license key. The license file is a text file containing the site license key that must be readable by all users of PyXLL. This simplifies the process of updating a site license as it only needs to be updated in one shared file, rather than every installed instance of PyXLL. In the event that both key and file are specified, key takes precedence.
[LICENSE] key = (optional) license key file = (optional) path to shared license key file