These decorators enable the user to register functions that will be called when certain events occur in the PyXLL addin.
xl_on_open(func)Decorator for callbacks that should be called after PyXLL has been opened and the user modules have been imported.
The callback takes a list of tuples of three three items:
(modulename, module, exc_info)
When a module has been loaded successfully, exc_info is None.
When a module has failed to load, module is None and exc_info
is the exception information (exc_type, exc_value, exc_traceback).
Example usage:
from pyxll import xl_on_open
@xl_on_open
def on_open(import_info):
for modulename, module, exc_info in import_info:
if module is None:
exc_type, exc_value, exc_traceback = exc_info
... do something with this error ...
xl_on_reload(func)Decorator for callbacks that should be called after a reload is attempted.
The callback takes a list of tuples of three three items:
(modulename, module, exc_info)
When a module has been loaded successfully, exc_info is None.
When a module has failed to load, module is None and exc_info
is the exception information (exc_type, exc_value, exc_traceback).
Example usage:
from pyxll import xl_on_reload, xlcCalculateNow
@xl_on_reload
def on_reload(reload_info):
for modulename, module, exc_info in reload_info:
if module is None:
exc_type, exc_value, exc_traceback = exc_info
... do something with this error ...
# recalcuate all open workbooks
xlcCalculateNow()
xl_on_close(func)Decorator for registering a function that will be called when Excel is about to close.
This can be useful if, for example, you’ve created some background threads and need to stop them cleanly for Excel to shutdown successfully. You may have other resources that you need to release before Excel closes as well, such as COM objects, that would prevent Excel from shutting down. This callback is the place to do that.
This callback is called when the user goes to close Excel. However, they may choose to then cancel the close operation but the callback will already have been called. Therefore you should ensure that anything you clean up here will be re-created later on-demand if the user decides to cancel and continue using Excel.
To get a callback when Python is shutting down, which occurs when Excel is finally quitting, you should use the standard atexit Python module. Python will not shut down in some circumstances (e.g. when a non-daemonic thread is still running or if there are any handles to Excel COM objects that haven’t been released) so a combination of the two callbacks is sometimes required.
Example usage:
from pyxll import xl_on_close
@xl_on_close
def on_close():
print("closing...")
xl_license_notifier(func)Decorator for registering a function that will be called when PyXLL is starting up and checking the license key.
It can be used to alert the user or to email a support or IT person when the license is coming up for renewal, so a new license can be arranged in advance to minimize any disruption.
The registered function takes 4 arguments: string name, datetime.date expdate, int days_left, bool is_perpetual.
If the license is perpetual (doesn’t expire) expdate will be the end date of the maintenance agreement (when maintenance builds are available until) and days_left will be the days between the PyXLL build date and expdate.
Example usage:
from pyxll import xl_license_notifier
@xl_license_notifier
def my_license_notifier(name, expdate, days_left, is_perpetual):
if days_left < 30:
... do something here...
