Schedule a function to be called after the current Excel calculation cycle has completed.
The function is called in an Excel macro context so it is safe to use
xl_app and other COM and macro functions.
This can be used by worksheet functions that need to modify the worksheet where calling back into Excel would fail or cause a deadlock.
From Python 3.7 onwards when called from the PyXLL asyncio event loop and
‘nowait’ is not set this function returns an asyncio.Future. This future
can be awaited on to get the result of the call (see warning about awaiting
in an async UDF below).
NOTE: In the stubs version (not embedded in PyXLL) the function is always called immediately and will not retry.
func – Function or callable object to call in an Excel macro context at some time in the near future.
args – Arguments to be passed to the the function.
delay – Delay in seconds to wait before calling the function.
nowait – Do not return a Future even if called from the asyncio event loop.
retries – Integer number of times to retry.
retry_delay – Time in seconds to wait between retries.
retry_backoff – Multiplier to apply to ‘retry_delay’ after each retry. This can be used to increase the time between each retry by setting ‘retry_backoff’ to > 1.0.
retry_filter – Callable that receives the exception value in the case of an error. It should return True if a retry should be attempted or False otherwise.
disable_calculation –
Disable automatic calculations while the callback is being called. This switches the Excel calculation mode to manual and restores it to its previous mode after the call is complete.
New in PyXLL 5.2
disable_screen_updating –
Disable Excel’s screen updating while the callback is being called. Screen updating is restored to its previous mode after the call is complete.
New in PyXLL 5.2
Example usage:
from pyxll import xl_func, xl_app, xlfCaller, schedule_call
@xl_func(macro=True)
def set_values(rows, cols, value):
"""Copies 'value' to a range of rows x cols below the calling cell."""
# Get the address of the calling cell
caller = xlfCaller()
address = caller.address
# The update is done asynchronously so as not to block Excel
# by updating the worksheet from a worksheet function.
def update_func():
xl = xl_app()
xl_range = xl.Range(address)
# get the cell below and expand it to rows x cols
xl_range = xl.Range(range.Resize(2, 1), range.Resize(rows+1, cols))
# and set the range's value
xl_range.Value = value
# Schedule calling the update function
pyxll.schedule_call(update_func)
return address
Note
This function doesn’t allow passing keyword arguments to the schedule function. To do that, use functools.partial().
# Will schedule "print("Hello", flush=True)"
schedule_call(functools.partial(print, "Hello", flush=True))
Warning
If called from an async UDF it is important not to await on the result of this call! Doing so is likely to cause a deadlock resulting in the Excel process hanging.
This is because the scheduled call won’t run until the current calculation has completed, so your function will not complete if awaiting for the result.
Causes the PyXLL addin and any modules listed in the config file to be reloaded once the calling function has returned control back to Excel.
If the ‘deep_reload’ configuration option is turned on then any dependencies of the modules listed in the config file will also be reloaded.
The Python interpreter is not restarted.
Causes the PyXLL addin to rebuild the bindings between the exposed Python functions and Excel once the calling function has returned control back to Excel.
This can be useful when importing modules or declaring new Python functions dynamically and you want newly imported or created Python functions to be exposed to Excel without reloading.
Example usage:
from pyxll import xl_macro, rebind
@xl_macro
def load_python_modules():
import another_module_with_pyxll_functions
rebind()
the PyXLL config as a ConfigParser.SafeConfigParser instance
See also Configuring PyXLL.
the type of the current dialog that initiated the call into the current Python function
xlDialogTypeNone
or xlDialogTypeFunctionWizard
or xlDialogTypeSearchAndReplace
Returns the current number of cached objects.
When objects are returns from worksheet functions using the object or var type they are stored
in an internal object cache and a handle is returned to Excel.
Once the object is no longer referenced in Excel the object is removed from the cache automatically.
See Cached Objects.
