New in PyXLL 4.4.0
The startup_script option can be used to run a batch or Powershell script when Excel starts, and again
each time PyXLL is reloaded.
This can be useful for ensuring the Python environment is installed correctly and any Python packages are up to date, or for any other tasks you need to perform when starting Excel.
The script runs before Python is initialized, and can therefore be used to set up a Python environment
if one doesn’t already exist. The PyXLL config can be manipulated from the startup script so any
settings such as the modules list, pythonpath or even the Python executable can be set
on startup rather than being fixed in the pyxll.cfg file.
The startup script can be a local file, a file on a network drive, or even a URL. Using a network drive or a URL can be a good option when deploying PyXLL to multiple users where you want to have control over what’s run on startup without having to update each PC.
Batch files (.bat or .cmd) and Powershell files (.ps1) are supported. Script files must use one of these file extensions.
The script is run with the current working directory (CWD) set to the same folder as the PyXLL add-in itself, and so relative paths can be used relative to the xll file.
If successful the script should exit with exit code 0. Any other exit code will be interpreted as the script not having been run successfully by PyXLL.
See also Using a startup script to install and update Python code.
A startup script could be used to download a Python environment and configure PyXLL.
REM startup-script.bat
@ECHO OFF
REM If the Python env already exists no need to download it
IF EXIST ./python-env-xx GOTO SKIPDOWNLOAD
REM Download and unpack a Python environment to ./python-env-xx/
wget https://intranet/python/python-env-xx.tar.gz
tar -xzf python-env-xx.tar.gz --directory python-env-xx
:SKIPDOWNLOAD
REM Update the PyXLL settings with the executable
ECHO pyxll-set-option PYTHON executable ./python-venv-xx/pythonw.exe
The script is configured in the pyxll.cfg file, and could be on a remote network drive or web server.
[PYXLL]
startup_script = https://intranet/pyxll/startup-script.bat
When PyXLL runs the startup script (either a batch or Powershell script) it monitors the stdout of the script for special commands. These commands can be used by your script to get information from PyXLL, update settings, and give the user information.
To call one of the commands from your script you echo it to the stdout. For example, the command
pyxll-set-option can be used to set one of PyXLL’s configuration options. In a batch file, to set
the LOG/verbosity setting to debug it would be called as follows:
ECHO pyxll-set-option LOG verbosity debug
Calling the command from Powershell is the same:
Echo "pyxll-set-option LOG verbosity debug"
Some commands return results back to the script. They do this by writing the result to the script’s
stdin. To read the result from a command that returns something you need to read it from the
stdin into a variable. The command pyxll-get-command is one that returns a result and can be
used from a batch file as follows:
ECHO pyxll-get-option PYTHON executable
SET /p EXECUTABLE=
REM The PYTHON executable setting is now in the variable %EXECUTABLE%
Or in Powershell it would look like:
Echo "pyxll-get-option PYTHON executable"
$executable = Read-Host
Below is a list of the available commands.
Gets the value of any option from the config.
Takes two arguments, SECTION and OPTION, and returns the option’s value.
Batch File
ECHO pyxll-get-option SECTION OPTION
SET /p VALUE=
Powershell
Echo "pyxll-get-option SECTION OPTION"
$value = Read-Host
If used on a multi-line option (e.g. PYTHON/modules and PYTHON/pythonpath) the value returned will be a list of value delimited by the separator documented for the setting.
Sets a config option.
Takes three arguments, SECTION, OPTION and VALUE. Doesn’t return a value.
Batch File
ECHO pyxll-set-option SECTION OPTION VALUE
Powershell
Echo "pyxll-set-option SECTION OPTION VALUE"
When used with multi-line options (e.g. PYTHON/modules and PYTHON/pythonpath) this command appends
to the list of values. Use pyxll-unset-option to clear the list first if you want to overwrite any
current value.
Unsets the specified option.
Takes two arguments, SECTION and OPTION. Doesn’t return value.
Batch File
ECHO pyxll-unset-option SECTION OPTION
Powershell
Echo "pyxll-unset-option SECTION OPTION"
Display or update a progress indicator dialog to inform the user of the current progress.
This is useful for potentially long running start up scripts, such as when downloading files from a network location or installing a large number of files.
Takes one argument, the current progress as a number between 0 and 100. Doesn’t return a value.
Batch File
ECHO pyxll-set-progress PERCENT_COMPLETE
Powershell
Echo "pyxll-set-progress PERCENT_COMPLETE"
Displays the progress indicator without setting the current progress.
This shows the progress indicator in ‘marquee’ style where it animates continuously rather than showing any specific progress.
If the progress indicator is already shown this command does nothing.
Takes no arguments and doesn’t return a value.
Batch File
ECHO pyxll-show-progress
Powershell
Echo "pyxll-show-progress"
Sets the status text of the progress indicator dialog.
This does not show the progress indicator if it is not already shown. Use pyxll-show-progress or
pyxll-set-progress to show the progress indicator.
Takes one argument, STATUS, and doesn’t return a value.
Batch File
ECHO pyxll-set-progress-status STATUS
Powershell
Echo "pyxll-set-progress-status STATUS"
Sets the title of the progress indicator dialog.
This does not show the progress indicator if it is not already shown. Use pyxll-show-progress or
pyxll-set-progress to show the progress indicator.
Takes one argument, TITLE, and doesn’t return a value.
Batch File
ECHO pyxll-set-progress-title TITLE
Powershell
Echo "pyxll-set-progress-title TITLE"
Sets the caption text of the progress indicator dialog.
This does not show the progress indicator if it is not already shown. Use pyxll-show-progress or
pyxll-set-progress to show the progress indicator.
Takes one argument, CAPTION, and doesn’t return a value.
Batch File
ECHO pyxll-set-progress-caption CAPTION
Powershell
Echo "pyxll-set-progress-caption CAPTION"
Gets the version of the installed PyXLL add-in.
Takes no arguments and returns the version.
Batch File
ECHO pyxll-get-version
SET /p VERSION=
Powershell
Echo "pyxll-get-version"
$version = Read-Host
Gets the version of Python the installed PyXLL add-in is compatible with in the form PY_MAJOR_VERSION.PY_MINOR_VERSION.
Takes no arguments and returns the Python version.
Batch File
ECHO pyxll-get-python-version
SET /p VERSION=
Powershell
Echo "pyxll-get-python-version"
$version = Read-Host
Gets the machine architecture of the Excel process and PyXLL add-in.
Takes no arguments and returns either ‘x86’ for 32 bit or ‘x64’ for a 64 bit.
Batch File
ECHO pyxll-get-arch
SET /p ARCH=
Powershell
Echo "pyxll-get-arch"
$arch = Read-Host
Gets the process id of the Excel process.
Takes no arguments and the process id.
Batch File
ECHO pyxll-get-pid
SET /p PID=
Powershell
Echo "pyxll-get-pid"
$pid = Read-Host
Displays a message box to the user informing them Excel needs to restart. If the user selects ‘Ok’ then Excel will restart. The user can cancel this and if they do so the script will be terminated.
This can be used if your script needs to install something that would require Excel to be restarted. When Excel restarts your script will be run again and so you should ensure that it doesn’t repeatedly request to restart Excel.
One possible use case is if you want to upgrade the PyXLL add-in itself. You can rename the existing one (it can’t be deleted while Excel is using it, but it can be renamed) and copy a new one in its place and then request to restart Excel.
Takes one optional argument, MESSAGE, which will be disaplyed to the user. Doesn’t return a result.
Batch File
ECHO pyxll-restart-excel MESSAGE
Powershell
Echo "pyxll-restart-excel MESSAGE"
New in PyXLL 5.6
Sets the error message to be displayed to the user if the script fails.
This can be used to customize what the user sees in the message box if the script exits with a non-zero exit code.
Batch File
ECHO pyxll-set-error-message MESSAGE
Powershell
Echo "pyxll-set-error-message MESSAGE"
