schedule_call(func, *args, delay=0, nowait=False, retries=0, retry_delay=0, retry_backoff=1.0, retry_filter=None, disable_calculation=False, disable_screen_updating=False)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.
| Parameters: |
|
|---|
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.
reload()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.
rebind()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()
get_config()| Returns: | the PyXLL config as a ConfigParser.SafeConfigParser instance |
|---|
See also Configuring PyXLL.
get_dialog_type()| Returns: | the type of the current dialog that initiated the call into the current Python function
or or |
|---|
xlDialogTypeNone = 0xlDialogTypeFunctionWizard = 1xlDialogTypeSearchAndReplace = 2cached_object_count()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.
